> ## 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.
# Workload
> Up to eight containers that deploy and scale together in every location of their GVC: the type decides how they scale and serve, the identity decides what they may reach, and the firewall decides who may reach them.
Everything you run on Control Plane is a workload: the unit you deploy, scale, route traffic to, and read logs from. Two choices shape everything else about it: the [type](/reference/workload/types) it is created as, and the [identity](/concepts/identity) attached to it.
## How It Fits
| Relationship | Rule |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Parent | One [GVC](/concepts/gvc), which decides the [locations](/concepts/location). A workload cannot move to another GVC. |
| Locations | Every location the GVC spans, automatically, with one [deployment](/concepts/deployment) per location. |
| Containers | 1 to 8, each with its own image, resources, and ports. They deploy and scale together and reach each other over `localhost`. |
| Identity | At most one identity, attached to give the workload its credentials for secrets, cloud services, and private networks. |
| Storage | Persistent disks come from a [volume set](/reference/volumeset) in the same GVC: a disk per [replica](/concepts/replica) for one `stateful` or `vm` workload, or a `shared` filesystem any type can mount. Containers also mount [S3, GCS, and Azure buckets, secrets, and ephemeral scratch space](/reference/workload/volumes). |
Editing the workload creates a new version, and every location rolls it out beside the version already serving:
The type, chosen at creation, decides how the workload scales, serves traffic, and updates:
| Type | Pick it for |
| ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `serverless` | Request-driven services: can scale to zero and wake on the next request, and exposes exactly one port. |
| `standard` | Always-on services and background workers: any number of ports, or none. |
| `cron` | Scheduled jobs: each run goes to completion and serves no network traffic. |
| `stateful` | Databases and clustered systems: stable replica names and a volume per replica. |
| `vm` | A full virtual machine with its own guest OS, inside the same networking, identity, and observability as containers. |
## Key Behaviors
* **A broken update cannot take the workload down.** Each location keeps serving the last healthy version until the new one reports ready, which your [health probes](/reference/workload/containers#probes) define; then traffic switches to the new version and the old one drains, with no gap in service. [Rollout options](/reference/workload/general#rollout-options) set how many replicas turn over at once, and with [dynamic tags](/reference/workload/containers#images), pushing a new image under the same tag starts the rollout by itself.
* **Per-location differences are overrides, not separate workloads.** [Local options](/reference/workload/general#location-specific-options) name a location and restate any of the default options, so one region can run a wider replica range than the rest. [Suspend](/reference/workload/general#suspend) the workload to stop every location, or set it in one location's overrides to stop that location alone; the workload then reports `partiallySuspended`.
* **Scale-to-zero depends on the type.** A `serverless` workload scales to zero on any metric it supports. `standard` and `stateful` reach zero only through [KEDA](/reference/workload/autoscaling#keda), which the GVC must have enabled first. `cron` and `vm` cannot reach zero at all, and `minScale: 0` is rejected with `workloads of type 'vm' are unable to scale to zero, please set minScale > 0`.
* **[Capacity AI](/reference/workload/capacity) right-sizes what autoscaling does not.** It moves CPU and memory between their minimum and maximum from historical usage, which is why it cannot run alongside CPU-based [autoscaling](/reference/workload/autoscaling): the combination is rejected with `CapacityAI may not be enabled when the autoscaling metric is 'cpu'`, and GPU containers exclude it too. Because sizing follows history, a sudden spike can outrun the current allocation until Capacity AI raises it.
* **Nothing reaches a workload until its firewall allows it.** Other workloads address it at `my-app.my-gvc.cpln.local` over mutual TLS, but the [internal firewall](/reference/workload/firewall#internal) defaults to `none`. Open it to `same-gvc`, `same-org`, or a `workload-list` naming exact workloads, which can cross GVCs. Public traffic is a separate [external firewall](/reference/workload/firewall#external) decision.
* **A global endpoint and one per location come built in.** The global one is the [canonical endpoint](/reference/workload/general#canonical-endpoint-global): one HTTPS URL that sends each request to the nearest healthy location. Each location publishes an HTTPS endpoint of its own, and a [domain](/reference/domain) route puts a hostname you own in front of the workload, with its TLS certificate issued for you.
* **Control Plane retries and times out requests for you.** A request that fails to connect to the workload is retried, twice by default, and a request the workload has not answered within 5 seconds fails. The [retry policy](/reference/workload/general#automatic-retries) and the [timeout](/reference/workload/general#timeout-seconds) are both workload settings.
* **Logs, metrics, and a shell are built in.** Every replica streams [logs](/core/logs) and [metrics](/guides/default-metrics) automatically, containers can publish [custom metrics](/reference/workload/custom-metrics) of their own, and [`cpln workload connect`](/guides/cli/workload/connect) opens a shell in a running replica.
## Gotchas
* **The type cannot be changed after creation.** A request that edits the type is rejected with `Workload type may not be changed.` Switching means creating a second workload, so capture the old spec first.
* **A `serverless` workload must expose exactly one port, in one container.** No port at all is rejected with `workloads of type 'serverless' must have at least one container port exposed.`, and so is a second port or a second container with ports; portless background work belongs in a `standard` workload.
* **A `cron` workload runs its schedule in every location the GVC spans.** The one per-location override that applies is `suspend`, which stops the schedule in that location alone.
* **A missing [secret](/reference/secret) pauses the deployment rather than failing it.** A `cpln://secret/my-secret` reference the workload's identity cannot yet `reveal` holds the rollout until [access is granted](/reference/secret#reveal-permission); `cpln workload force-redeployment` clears it once it is.
* **Replicas, CPU, and memory are quota'd per workload.** The replica [quota](/concepts/quota) caps autoscaling's `maxScale`, the CPU and memory quotas cap the totals across all containers, and all three are raised on request rather than by editing the spec; the [quota catalog](/guides/manage-quotas#browse-the-quota-catalog) lists the defaults.
## Learn More
Every field: containers, options, endpoints, rollout, suspend, and tags.
Deploy an image from the Console, the CLI, or a manifest.
What each type can expose, how it scales, and how it updates.
The locations a workload runs in, and the settings every workload in a GVC shares.