Deployment

One read-only status record per location, written by Control Plane: ready says whether that location serves, deploying says whether a rollout is still under way, and old and new versions stay listed side by side until the new one is ready.

A workload describes what you want to run; a deployment records what is actually running in one location: the workload’s replicas there, version by version. You never create a deployment: Control Plane generates one for every location the workload’s GVC spans, names it after that location, and keeps it current as replicas start, scale, and fail. When an update looks stuck or a location stops serving, that location’s deployment is where you find out why.

How It Fits

In Kubernetes terms, a Control Plane deployment is not the Deployment object you apply; it is the status you read back. What you apply is the workload, and Control Plane answers with one deployment per location.

Relationship	Rule
Workload	One deployment per location the GVC spans, named after that location. Editing the workload is the only way to change a deployment; the deployment itself is read-only on every interface.
Versions	Every edit of the workload produces a new version, and the deployment lists each version still running in that location, each with its own ready state.
Replicas	The deployment counts the replicas of each version: how many exist, how many are ready, and the count autoscaling currently targets there.
Endpoint	Each deployment carries the location’s own endpoint for the workload, the per-location URL that the global endpoint routes to.
Cron runs	For a cron workload, the deployment records the run history in its location: each run, its outcome, and the replica that ran it.

The health you see on a workload anywhere is read from its deployments: the Console’s workload page, cpln workload get-deployments, and the API all show the same record.

Key Behaviors

• A rollout shows as two versions at once. The old version stays in the list and keeps serving while the new one starts; the update is done when the new version reports ready and the old one leaves the list. How many replicas turn over at once is a workload setting.
• ready follows the version you asked for. During an update it turns false until the newest version is fully up, DNS included, while the previous version keeps serving: not ready does not always mean down.
• deploying stops on failure. It is true from the moment a new version is expected until that version is ready, and a crash or failing probe turns it off. deploying: false with ready: false means the rollout stopped; read the version messages and restart counts to see why.
• Deployments trail the workload. A deployment appears once its location first reports, so a just-created workload can list none until those reports arrive, and a location newly added to the GVC joins the list the same way.
• Replica commands route through the deployment. cpln workload connect, exec, and replica listings reach a location’s replicas through that location’s deployment, which is why those commands take a location.
• A silent location is flagged, then dropped. When a location stops reporting for 45 minutes, Control Plane overwrites the deployment’s message with Status details are stale, so an unreachable location cannot present old data as current; a record untouched for 24 hours leaves the list entirely. Suspended locations are exempt from the stale flag.

Gotchas

• Not ready is sometimes the state you asked for. A suspended location reports ready: false with the message This workload location is deactivated because suspend is set to true. Read the message before treating a location as failed.
• A missing deployment is absence, not an error. A workload with no deployment in some location has not run there recently: the record was dropped after 24 silent hours, or the location left the GVC. Check the GVC’s locations before hunting for a failure.
• Deployment names repeat across workloads. Every workload names its deployments after the same locations, so aws-us-east-1 alone never identifies one; it is always the pair of workload and location.
• Fixes go to the workload, never the deployment. Nothing on a deployment can be edited, restarted, or deleted, so correct the cause at its source: the workload spec, or the secret access it is waiting on. cpln workload force-redeployment starts a fresh rollout of the same spec, and the deployment converges once the cause is fixed, not before.
• Cron history is capped per location. A deployment keeps at most job.historyLimit finished runs (default 5, at most 10), so older runs fall off the list; ship logs somewhere durable if you audit every run.

Learn More

Deployment reference

Every status field, reading a rollout, job executions, and the stale and expiry rules.

Workload

What you edit to change a deployment: containers, type, options, and rollout settings.

Replica

The running copies a deployment counts, and how autoscaling sizes them per location.

Location

What deployments are named after: cloud regions and Kubernetes clusters of your own.