Expiration

An expiration time makes ctrl stop or delete a Workspace automatically when it arrives. This page shows how to set, change, and clear it, at creation, on its own, or together with start and stop.

Setting at creationCopy Anchor Link

Create a Workspace that expires eight hours after ctrl accepts the command:

kibo workspace create --template "$template_id" --expires-in 8h

• The countdown starts when ctrl accepts the command and includes the time creation takes.
• Without --expires-in, no expiration time is set.
• Accessing files or running commands does not extend the expiration time.
• kibo transfer restore accepts the same parameters.

--expiration-action chooses what happens at the expiration time:

Expiration actions are carried out by ctrl, so exiting kibo does not affect them.

Viewing the expirationCopy Anchor Link

Show the Workspace and its expiration:

kibo workspace expiration get "$workspace_id"

The expiration in the output of kibo workspace get and list contains:

Changing it separatelyCopy Anchor Link

Set a new expiration time and action, or clear the expiration time:

workspace_id=workspace-example
kibo workspace expiration set "$workspace_id" --expires-in 20m --expiration-action delete
kibo workspace expiration clear "$workspace_id"

Which change is allowed depends on the Workspace state:

A FAILED Workspace can keep an expiration time, for example when a start failed during placement and left behind the expiration time set at start.

Setting with start and stopCopy Anchor Link

kibo workspace start and stop also accept --expires-in and --expiration-action, or --clear-expiration to clear the expiration time. The two groups of parameters are mutually exclusive.

Stop a Workspace and leave it without an expiration time, or start it with an expiration time for this run:

# Stop, and leave the stopped Workspace without an expiration time.
kibo workspace stop "$workspace_id" --clear-expiration
# Start, and set an expiration time for this run. Start time counts toward it.
kibo workspace start "$workspace_id" --expires-in 30m --expiration-action stop

• The expiration setting is submitted in the same operation as the command. There is no intermediate state of "started but without an expiration time yet", and you do not need to run expiration set again after success.
• When the command succeeds, the revision goes up by one, and the response carries the new expiration.revision and expires_at. A failed command does not change the expiration setting.
• Expiration parameters are part of the command input. The same command ID with a different --expires-in is treated as a conflict and does not silently extend the time.

Without expiration parametersCopy Anchor Link

Expected revisionsCopy Anchor Link

These commands carry the revision of the expiration setting they expect, expiration.revision:

• Without the flag, kibo reads the current revision before submitting. A value you pass is submitted as is.
• A revision mismatch returns failed_precondition. For expiration set and clear, a disallowed state returns the same code; tell the two apart by observed_workspace in the error details.
• When you get failed_precondition, read the Workspace again before deciding. Do not overwrite the new state with the old intent.

For a script that needs to replay, pass --command-id together with the expected revision:

revision=$(kibo --json workspace get "$workspace_id" | jq -er '.result.expiration.revision')
kibo workspace expiration set "$workspace_id" --command-id renew-example \
  --expected-revision "$revision" --expires-in 20m

With the APICopy Anchor Link

Both fields correspond to expiration.revision.

Next stepsCopy Anchor Link

• Lifecycle: what stop, start, and delete do to a Workspace.
• Volumes, export, and restore: which Volumes are deleted with a Workspace.
• kibo CLI: command IDs and replaying a command safely.