Deployment

The observed state of one workload in one location: its endpoints, the versions running there, per-container readiness and restarts, and cron job history.

A deployment is generated by Control Plane, never created by you. A workload has one deployment per location its GVC spans, named after that location, and every field on it is read-only.

Example

cpln workload get-deployments my-app --gvc my-gvc --org my-org -o json

{
  "kind": "deployment",
  "name": "aws-eu-central-1",
  "lastModified": "2026-08-26T16:29:19.450Z",
  "status": {
    "endpoint": "https://my-app-a1gm4cx40er00.aws-eu-central-1.controlplane.us/",
    "remote": "https://remote-a4e2dc319c383ac09ceeed0475a71f33.aws-eu-central-1.controlplane.us",
    "ready": true,
    "deploying": false,
    "lastProcessedVersion": 11,
    "expectedDeploymentVersion": 11,
    "versions": [
      {
        "workload": 11,
        "created": "2026-08-26T16:28:02.412Z",
        "ready": true,
        "message": "",
        "containers": {
          "app": {
            "name": "app",
            "image": "/org/my-org/image/my-app:1.4.0",
            "ready": true,
            "resources": { "replicas": 2, "replicasReady": 2, "cpu": 500, "memory": 512 }
          }
        }
      }
    ]
  },
  "links": [
    { "href": "/org/my-org/gvc/my-gvc/workload/my-app/deployment/aws-eu-central-1", "rel": "self" },
    { "href": "/org/my-org/gvc/my-gvc/workload/my-app", "rel": "workload" },
    { "href": "/org/my-org/location/aws-eu-central-1", "rel": "location" }
  ]
}

Status

Field	Type	Description
endpoint	string	The location-specific endpoint for this workload, on controlplane.us.
remote	string	The location’s control endpoint. Replica operations such as cpln workload exec and cpln replica get are routed through it.
ready	boolean	Whether the expected version is fully up in this location, DNS included. False during a rollout until the new version serves, while its replicas fail their readiness probes, and while the location is suspended. The previous version can keep serving while this is false.
deploying	boolean	True from the moment the expected version is applied until the deployment is fully ready, DNS included. It stops being true on failure, so deploying: false with ready: false means something went wrong rather than that work is in progress.
message	string	Free-form diagnosis of the current state. Empty when healthy.
lastProcessedVersion	integer	The workload version this location has most recently acted on.
expectedDeploymentVersion	integer	The workload version this location should converge to.
desiredScale	integer	The replica count autoscaling currently targets in this location.
versions	array	One entry per workload version still present here. See Deployment version.
jobExecutions	array	Cron workloads only. See Job executions.
internal	object	Platform bookkeeping. Shape is not part of the contract; do not read it.

Deployment version

Each entry in status.versions is one version of the workload as it exists in this location. During a rolling update two entries appear at once.

Field	Type	Description
workload	integer	The version of the workload resource this was rendered from.
gvc	integer	The version of the GVC resource in effect.
created	date	When this version started rolling out here.
ready	boolean	Whether this version is serving.
message	string	Why it is not ready, when it is not.
zone	string	The availability zone, when multi-zone is enabled.
desiredScale	integer	The replica count targeted for this version.
containers	object	A map keyed by container name. See Container status.

Container status

Field	Type	Description
name	string	The container name from the workload spec.
image	string	The image actually running, which is what to check after a supportDynamicTags redeploy.
ready	boolean	Whether the container passes its readiness probe.
message	string	Diagnostic text aggregated from cluster events.
resources.replicas	number	Replicas of this container in this location.
resources.replicasReady	number	How many of them are ready. A gap between the two is the signature of a failing probe or a crash loop.
resources.cpu	number	CPU in millicores, as resolved after Capacity AI.
resources.memory	number	Memory in MiB, as resolved after Capacity AI.
restarts.count	number	Restarts observed.
restarts.exitCode	number	The exit code of the last failure.
restarts.reason	string	The reason reported for the last restart, such as OOMKilled.
restarts.lastRestartTime	date	When the last restart happened.

Job executions

Cron workloads record their run history in status.jobExecutions, capped at the workload’s job.historyLimit.

Field	Type	Description
name	string	The name of the underlying job.
replica	string	The replica that ran it, which is the label to filter logs by.
status	string	pending, active, successful, failed, invalid, or removed.
workloadVersion	integer	The workload version this run used.
startTime	date	When the run moved from pending to active.
completionTime	date	When the run finished. Present on failures too, so it is not a success signal.
conditions	array	Each with type, status, reason, message, lastDetectionTime, and lastTransitionTime.
containers	object	Per-container status for the run, keyed by name.
message	string	Diagnostic text aggregated from cluster events, semicolon-separated.

A run reaches removed when it was deleted before finishing, usually because job.concurrencyPolicy is Replace and the next run was due, or because job.activeDeadlineSeconds elapsed.

Reading a rollout

Compare the two version numbers first.

Condition	What it means
lastProcessedVersion equals expectedDeploymentVersion, ready: true	Converged and serving.
lastProcessedVersion behind expectedDeploymentVersion	The change has not reached this location yet.
deploying: true	The rollout is in progress.
deploying: false, ready: false	The rollout stopped without succeeding. Read status.message, then the per-container message and restarts.
lastProcessedVersion ahead of expectedDeploymentVersion	The location is not converging on the current spec, which is what a suspended location looks like.

A location switched off through spec.localOptions reports ready: false with the message This workload location is deactivated because suspend is set to true. That is the expected state, not a failure.

Stale and expired deployments

Each location reports in on a schedule. When a report is overdue by more than 45 minutes, Control Plane overwrites status.message with Status details are stale, so an unreachable location cannot present old data as current. Suspended locations are exempt, since they have nothing to report.

A record untouched for 24 hours is dropped from the list entirely. A workload whose deployments are missing rather than unhealthy has not been deployed to those locations recently.

Permissions

Deployments carry no permissions of their own. Reading one requires view on its workload.

CLI

cpln workload get-deployments my-app --gvc my-gvc --org my-org

Add -o json or -o yaml for the full object; the default table view shows readiness per location. See the workload CLI reference.

API

Operation	Path
Every deployment in a GVC	GET /org/my-org/gvc/my-gvc/workload/-deployment
Deployments of one workload	GET /org/my-org/gvc/my-gvc/workload/my-app/deployment
One deployment by location	GET /org/my-org/gvc/my-gvc/workload/my-app/deployment/aws-eu-central-1

The GVC-wide listing returns one item per workload and location pair. Deployment names repeat across workloads, so use each item’s workload link to tell them apart.