Skip to main content

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:

  1. It gets the named object from the Object Store.
  2. It writes the script content to the correct path under /etc/cron.d/ or /etc/cron.{interval}/.
  3. 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 osapi marker.
  • 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​

OperationDescription
ListList all entries that osapi manages
GetGet one entry by name
CreateUpload the script, then make the entry
UpdateUpload a new version of the script, then update
DeleteRemove 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:

TypePathModeNotes
Schedule/etc/cron.d/{name}0644Not executable, root is the owner
Interval/etc/cron.{interval}/{name}0755Executable, 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 familySupport
DebianFull
DarwinSkipped

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​

OperationPermission
List, Getschedule:read
Create, Update, Deleteschedule: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.