Skip to main content
Most of Control Plane is declarative: you describe a workload or volume set, and Control Plane keeps the running system matching the description. Some operations don’t fit that model because they are one-off actions, like running a cron workload right now, stopping one replica, or expanding a volume. A command is the resource for those actions. You create it, Control Plane carries it out in the background, and the command records how far it got.

​
How It Fits

A command belongs to the resource it acts on and is created at that resource’s -command endpoint. The command’s type names the action, and its spec holds the action’s inputs. Creating a command returns 201 Created with a Location header that links to the new command. The work has started, but it hasn’t finished: poll the command to see where it is. Creating a workload command requires the matching exec permission, such as exec.runCronWorkload.

​
Lifecycle

The lifecycleStage field shows where a command is. It starts at pending and normally ends in one of the three final stages. completed means the action itself succeeded, not just the request. For example, a runCronWorkload command completes only when the job it started has finished. completed and cancelled are permanent. In rare cases, a failed command is corrected to completed once Control Plane sees the work actually finished.

​
Working with Commands

The examples use cpln rest, which sends an authenticated request to any API path. Any HTTP client works the same way against https://api.cpln.io. Create a command by posting its type and spec:
List a resource’s commands, or get one by its ID. The list is paginated, and ?lifecycleStage=STAGE narrows it to one stage:
Only Control Plane moves a command between stages. To stop a runCronWorkload run that is in progress, stop its replica: that deletes the run’s job and marks its command cancelled.

​
Gotchas

  • A 201 doesn’t mean the action finished. It means the command was accepted. Read lifecycleStage until it reaches completed, failed, or cancelled.
  • A command is read-only once created. A PATCH from a user or service account is rejected with 403 Cannot modify commands, and a DELETE isn’t allowed. A command stays as a record of what ran until the workload or volume set it belongs to is deleted, which deletes its commands too.
  • Some commands conflict, and they conflict in different ways.
    • A second stopReplica for the same replica is rejected with 400 while the first is still in progress.
    • A volume set command that overlaps one already in progress on the same volume is rejected with 409. The exception is deleteVolume, which fails the overlapping commands instead.
    • runCronWorkload has no such check, so a second on-demand run starts alongside the first.

​
Learn More

Workload types: Run Now

The runCronWorkload spec, including per-run container overrides and deadlines.

Stop a Replica

The stopReplica spec and what Control Plane does when a replica is stopped.

Volume set commands

Expand, shrink, delete, snapshot, and restore the volumes of a volume set.

Workload security

The exec permissions that allow a principal to create workload commands.