Schedule management
osapi manages scheduled entries on target hosts. It has two placement modes:
- Custom schedule. The provider writes
/etc/cron.d/{name}with a 5-field cron expression. - Periodic interval. The provider writes an executable script to
/etc/cron.{hourly,daily,weekly,monthly}/.
A scheduled entry refers by name to a script in the NATS Object Store. First, upload a script with the file management commands. Then make an entry that points to it. Thus the script content and the schedule configuration are separate, and you can update a script as a new version.
How it works
Object-based workflow
The cron provider is a meta provider: it does not keep the script content.
Each entry has an object name that refers to a file in the NATS Object Store.
When the agent deploys or updates an entry, it does these steps:
- It gets the named object from the Object Store.
- It writes the script content to the correct path under
/etc/cron.d/or/etc/cron.{interval}/. - It records the deploy state in the file-state KV bucket (SHA-256, path, times).
create and update are idempotent on the content. The agent compares the
requested content with the file on disk, and writes the file only when they are
different. Thus it puts back an entry that somebody changed by hand.
create has one exception. If an entry with the same name exists under a
different schedule, create reports changed: false. It does not write a
second copy in a different directory. Use update to move the entry.
Custom schedule (/etc/cron.d/)
For an entry with a schedule field, the provider writes a drop-in file. The
file content comes from the object in the Object Store:
0 2 * * * root /usr/local/bin/backup.sh --full
root owns the file, and its mode is 0644. The provider writes no header
comment. The file-state KV records the ownership.
Periodic interval (/etc/cron.{interval}/)
For an entry with an interval field, the provider writes an executable script
to the directory of that interval. The file content comes from the object. It
must start with a #!/bin/sh line:
#!/bin/sh
/usr/sbin/logrotate /etc/logrotate.conf
The provider writes the file with mode 0755, so that run-parts can run it.
Give schedule or interval, not both. The API checks this. If you give both
or neither, it returns 400.
File-state KV tracking
The provider records the deploy state in the file-state KV bucket. It does not put a header comment in the deployed file. Thus:
- A deployed cron file has only the script content. It has no
# Managed by osapimarker. - The list and get operations read the file-state KV to find the managed entries. They do not touch files that somebody made by hand.
- The state stays in the KV until you remove it. When you delete an entry, the agent removes the file from disk but keeps the file-state record.
Template support
If the object has content_type: template, the agent renders it as a Go
text/template before it writes the file to disk. Give variables at deploy time
with --var. Give one --var for each variable:
# Upload a template script
osapi client file upload --name backup-script.tmpl \
--content-type template --file ./backup.sh.tmpl
# Create a scheduled entry that renders the template on deploy
osapi client node schedule create --target web-01 \
--name backup --schedule "0 2 * * *" \
--object backup-script.tmpl \
--var retention_days=30 --var s3_bucket=my-bucket
The agent merges the template variables with its system facts and its hostname. Refer to File Management for the full template context.
Operations
| Operation | Description |
|---|---|
| List | List all entries that osapi manages |
| Get | Get one entry by name |
| Create | Upload the script, then make the entry |
| Update | Upload a new version of the script, then update |
| Delete | Remove the cron file from disk |
CLI usage
# Upload a script to the Object Store first
osapi client file upload --name backup-script \
--file ./backup.sh
# Create with a custom schedule (/etc/cron.d/)
osapi client node schedule create --target web-01 \
--name backup --schedule "0 2 * * *" \
--object backup-script --user root
# Create with an interval (/etc/cron.daily/)
osapi client node schedule create --target web-01 \
--name logrotate --interval daily \
--object logrotate-script
# List all managed entries
osapi client node schedule list --target web-01
# Get a specific entry
osapi client node schedule get --target web-01 --name backup
# Update: upload a new script version and redeploy
osapi client file update --name backup-script \
--file ./backup-v2.sh
osapi client node schedule update --target web-01 \
--name backup --schedule "0 3 * * *" \
--object backup-script
# Delete an entry (undeploys file from disk; state preserved in KV)
osapi client node schedule delete --target web-01 --name backup
All commands accept --json to give the raw JSON output.
File permissions
The provider sets the file owner and mode that cron needs:
| Type | Path | Mode | Notes |
|---|---|---|---|
| Schedule | /etc/cron.d/{name} | 0644 | Not executable, root is the owner |
| Interval | /etc/cron.{interval}/{name} | 0755 | Executable, starts with #!/bin/sh |
The agent writes the files as root. A name must not have dots, because
run-parts does not run files with dots in their names.
Undeploy behavior
When you delete an entry, the agent undeploys the file. It removes the file from the filesystem, but keeps the file-state KV record. Thus:
- When you make the entry again with the same name and object, the agent finds the previous state. It writes the file only if the content is different.
- The KV record is an audit trail of the last deploy.
To remove the file-state record, delete the file-state entry through the file management API after you remove the scheduled entry.
Supported platforms
| OS family | Support |
|---|---|
| Debian | Full |
| Darwin | Skipped |
On a platform that is not supported, cron operations return status: skipped.
They do not fail. Refer to Platform Detection
for how osapi finds the OS family.
Permissions
| Operation | Permission |
|---|---|
| List, Get | schedule:read |
| Create, Update, Delete | schedule:write |
All built-in roles (admin, write, read) have schedule:read. The admin
and write roles also have schedule:write.
Naming rules
An entry name can have only letters, digits, hyphens and underscores (pattern:
^[a-zA-Z0-9_-]+$). For example, backup-daily, log_rotate and
health_check are valid. The API rejects names with /, .. or spaces.
Idempotent updates
The update operation compares the new content with the file that exists, through
the SHA-256 in the file-state KV. If the script content and the schedule
parameters did not change, the response is changed: false. Thus you can run an
update many times, and it writes to the filesystem only when necessary.
Future: crontab and systemd timers
Cron drop-in management is the first provider of the schedule domain. Future
providers will add:
- Crontab: user crontab management (
crontab -u <user>) - Systemd timers: systemd timer unit management
They will have separate API endpoints, /node/{hostname}/schedule/crontab and
/node/{hostname}/schedule/timer.
Related
- File Management: upload scripts and render templates
- CLI Reference: the schedule commands
- Platform Detection: how osapi finds the OS family
- Configuration: all configuration settings