> ## Documentation Index > Fetch the complete documentation index at: https://controlplanecorporation-majid-docs-content-expansion.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/reference/workload/general) has one deployment per [location](/reference/location) its [GVC](/reference/gvc) spans, named after that location, and every field on it is read-only. ## Example ```bash theme={null} cpln workload get-deployments my-app --gvc my-gvc --org my-org -o json ``` ```json theme={null} { "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](#deployment-version). | | `jobExecutions` | array | Cron workloads only. See [Job executions](#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](/reference/workload/general#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). | ### 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](/reference/workload/capacity). | | `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`](/reference/workload/types#cron-configuration). | 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](/core/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`](/reference/workload/types#cron-configuration) 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`](/reference/workload/general#location-specific-options) 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](/reference/workload/general#permissions). ## CLI ```bash theme={null} 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](/cli-reference/commands/workload). ## 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`](/api-reference/workload/list-deployments-in-a-workload) | | One deployment by location | [`GET /org/my-org/gvc/my-gvc/workload/my-app/deployment/aws-eu-central-1`](/api-reference/workload/get-a-deployment-by-gvc-workload-and-name) | 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.