Copy page

Features

Cron Jobs / Scheduled Wake-ups

Scheduled operations let you automatically start, stop, delete, checkpoint, or exec a command in instances on a calendar-based schedule. Each scheduled operation specifies a name, a calendar expression, and an action (start, stop, delete, exec, or checkpoint).

Calendar expression format

Unikraft Cloud uses systemd calendar events (see systemd.time(7)). Calendar expressions have the following fields:

Code
[WEEKDAY] [[YEAR-]MONTH-DAY] [HOUR:MINUTE[:SECOND]]

The expression syntax supports ranges, steps, and comma-separated lists:

Syntax	Description
*	Any value
5	Exact value
1..5	Range
1..5/2	Range with step
1,2,5	Comma-separated list

Setting a schedule at instance creation

Pass schedules in the create request. For example, to start an instance every day at 09:00 UTC and stop it at 18:00 UTC:

To run a command inside the instance every night at midnight, use the exec action with an args array:

Updating schedules of an existing instance

Add, set, or remove scheduled operations via PATCH:

Add an exec schedule the same way, but include args with the command to run:

Actions

Action	Description
start	Start the instance at the scheduled time
stop	Stop the instance at the scheduled time
delete	Delete the instance at the scheduled time
exec	Execute a command inside the instance at the scheduled time. Requires the args field.
checkpoint	Create a checkpoint of the instance at the scheduled time, as described under scheduled checkpoints

The args field is an array of strings specifying the command to run when using the exec action. The first element is the executable and the remaining elements are its arguments.

Code
{
  "name": "daily-report",
  "when": "*-*-* 06:00:00",
  "action": "exec",
  "args": ["/usr/bin/python3", "/app/report.py", "--daily"]
}

No need to specify it for all other actions.

Scheduled checkpoints

The checkpoint action periodically creates restore points for an instance. Every occurrence creates a checkpoint of the instance, the same way a call to POST /instances/checkpoints does. This builds a history of restore points without an external scheduler, but it doesn't rotate older checkpoints - they persist until explicitly deleted.

To checkpoint an instance every night at 03:00 UTC:

Code
unikraft api /v1/instances -X POST --metro fra \
  '{
    "image": "...",
    "schedules": [
      {
        "name": "nightly-checkpoint",
        "when": "*-*-* 03:00:00",
        "action": "checkpoint"
      }
    ]
  }'

The platform names each new checkpoint after the instance and appends a random suffix, which matches the name a checkpoint gets when you create one through the API without one. Find the resulting checkpoints in the instance's checkpoint history.

Note the following:

• Scheduled checkpoints need a license that covers checkpointing. The platform checks the license when you configure the schedule and again at every occurrence, so an expired or replaced license stops an existing schedule from taking further checkpoints.
• Scheduled checkpoints only work with block-based volumes (for example, ext4) - occurrences fail for other volume types.
• Full VMs running on QEMU ("type": "full") don't support checkpointing yet, so the action fails on them.
• A failing occurrence leaves the schedule in place and doesn't affect the other scheduled operations of the instance. Because the instance status reports only the next elapse of a schedule and not the result of past runs, use the checkpoint history to confirm that occurrences produce checkpoints.

Learn more

• Checkpoints: creating, listing, and loading the restore points a checkpoint schedule produces.
• Unikraft Cloud's REST API reference, in particular the section on instances.