> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.
# General
> Workload reference overview covering access reports, identity assignment, the connect feature for debugging, and replica management across locations.
## Workload Overview
Refer to the [Workload concepts](/concepts/workload) page.
## Create a Workload
Refer to the [Create a Workload](/guides/create-workload) guide for additional details.
## Access Report
Displays the permissions granted to principals for the workload.
## Identity
Refer to the [identities](/reference/identity) page for additional details.
## Connect
A specific replica of a workload can be connected to (similar to `exec`) from either the console or the CLI. This can be used for troubleshooting any issues with the replica.
To connect using the console, click the `Connect` link from a workload. Select the location, container, replica, and command. Click `Connect` to execute the command. By default, the `bash` shell will be executed.
To connect using the CLI, review the workload [connect](/cli-reference/commands/workload#workload-connect) subcommand.
## Debug
In order to see detailed routing for the global georouted endpoint of a workload, debug values can be included within the response headers of a workload's endpoint request.
The values will only be returned when:
1. `debug` is active and the header `x-cpln-debug: true` is in the request.
2. The global or canonical endpoint is being requested.
Using the console, debug can be activated by:
* Clicking `Options`.
* Clicking the `Debug` switch to `on`.
* Clicking `Save`.
After the workload redeploys, the response from the workload's endpoint will contain the following headers if the header `x-cpln-debug: true` is in the request:
* `x-cpln-location`: Location of the responding replica.
* `x-cpln-replica`: Name of the responding replica.
```text Sample Request Headers theme={null}
GET https://doc-test-v39red0.cpln.app/ HTTP/1.1
Host: doc-test-v39red0.cpln.app
Connection: keep-alive
x-cpln-debug: true
```
```text Sample Response Headers theme={null}
HTTP/1.1 200 OK
content-length: 2993
content-type: text/plain
date: Fri, 10 Sep 2021 21:34:27 GMT
x-envoy-upstream-service-time: 2
x-cpln-location: aws-us-west-2
x-cpln-replica: doc-test-00083-deployment-75584b7d66-f8wtb
```
## Endpoints
### Canonical Endpoint (global)
This URL is globally load-balanced and TLS terminated. This can be used for testing if there is an issue with the custom domain that is associated with the [GVC](/reference/gvc).
The endpoint can be configured to use the [org endpoint prefix](/reference/gvc#endpoint-naming-format).
This adds the prefix as a subdomain to `cpln.app`.
#### Canonical Endpoint Formatting
The format depends on whether the GVC is configured to use an org-prefixed name.
* default name: `$workloadName-$gvcAlias.cpln.app`
* org-prefixed name: `$workloadName-$gvcAlias.$orgEndpointPrefix.cpln.app`
### Location-Specific Endpoint
One endpoint will be created for each location in the [GVC](/reference/gvc).
Format: `$workloadName-$gvcAlias.$locationName.controlplane.us`
### Replica-Direct Endpoints
For stateful workloads, Control Plane optionally provides endpoints which point directly to each workload replica.
Format: `$workloadName-$gvcAlias-$replicaIndex.$locationName.controlplane.us`
Example: stateful-workload-name-cry3tqvce07s4-0.aws-us-west-2.controlplane.us
These are built-in `controlplane.us` endpoints. For per-replica access under your own custom domain, see [Replica Direct Routing](/reference/domain#replica-direct-routing) in the Domain reference.
### Custom Domain Endpoints
Additional globally load-balanced endpoints will show in the workload status for each domain route that is configured to use this workload.
### Internal Mutual-TLS Endpoint
Each workload can be allowed to receive requests from other workloads in the same org internally using the provided internal endpoint. Access to this endpoint is controlled by the internal firewall settings.
#### Internal Endpoint Formatting
Typically, the workload endpoint is used. For stateful workloads with `replicaDirect` enabled, you may also use the replica-direct endpoint
* workload: `$workloadName.$gvcName.cpln.local:$port`
* replica-direct: `replica-$replicaIndex.$workloadName.$locationName.$gvcName.cpln.local:$port`
## Publish Not-Ready Addresses
By default, Control Plane only routes internal traffic to workload replicas that have passed their readiness probe. For clustered applications that need to discover peers during startup (before becoming ready), you can enable publishing not-ready addresses.
To enable this feature, add the following tag to your workload:
| Tag | Value |
| :------------------------------ | :----- |
| `cpln/publishNotReadyAddresses` | `true` |
When enabled, the internal service endpoint will include all pod IP addresses, even those that haven't passed their readiness probe yet. This is useful for:
* Distributed databases that need peer discovery during initialization
* Clustered applications where nodes must communicate before becoming ready
* Any application using StatefulSet-style stable network identities for bootstrapping
Enabling this feature means traffic may be routed to pods that are not yet ready to handle requests. Only use this for applications specifically designed to handle connections during startup.
## Inter-Container Communication
Containers deployed within the same workload can communicate with each other using their names and assigned ports. This setup facilitates direct networking between containers.
* **Container Identification** - Each container is uniquely identified by its name.
* **Port Allocation** - Containers are assigned specific ports for network communication.
### Example Scenario
* Imagine two containers within the same workload: `foo` and `bar`.
* Container `foo` is running on port **4020**.
* Container `bar` is running on port **4030**.
`foo` can access `bar` using the URL **[http://bar:4030](http://bar:4030)**. This URL combines the name of the destination container `bar` and its assigned port **4030**, enabling direct communication between the two containers.
This method ensures efficient and organized networking within a multi-container workload environment.
## Built-in Variables
Each workload has the following built-in environment variables:
| Variable Name | Description | Format |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
| CPLN\_GLOBAL\_ENDPOINT | The canonical Host header that the container will receive requests on | `${\workloadName}-${gvcAlias}.cpln.app` |
| CPLN\_GVC | The Global Virtual Cloud (/reference/gvc) the container is running under | string |
| CPLN\_GVC\_ALIAS | The Global Virtual Cloud Alias | 13 digit alphanumeric value |
| CPLN\_LOCATION | The [location](/reference/location) the container is serving the request from | aws-us-west-2, azure-eastus2, gcp-us-east1, etc. |
| CPLN\_NAMESPACE | The namespace of the container | Generated random string (e.g., aenhg2ec6pywt) |
| CPLN\_PROVIDER | The cloud provider the container is serving the request from | aws, azure, gcp, etc. |
| CPLN\_ORG | The org the container is running under | string |
| CPLN\_WORKLOAD | The workload the container is running under | string |
| CPLN\_WORKLOAD\_VERSION | The Control Plane version of the Workload, only updated when needed to apply changes. For example, changing scaling settings will not cause this to change. | numeric |
| CPLN\_TOKEN | A token used to authenticate to the Control Plane CLI / API | Random authorization token |
| CPLN\_IMAGE | The image as defined for this container in the Control Plane api | string |
Since a workload identity can be the target of a policy, a running workload can be authorized to exercise the
Control Plane [CLI](/cli-reference/overview) or [API](/api-reference/api) without any additional authentication.
Examples:
* Direct call to the Control Plane API:
* `curl ${CPLN_ENDPOINT}/org/${CPLN_ORG} -H "Authorization: ${CPLN_TOKEN}"`
* If the Control Plane CLI installed:
* `cpln org get ${CPLN_ORG}`
\*\* The value of CPLN\_TOKEN is valid only if the request originates from the workload it is injected in. If it is used from another workload or externally, a `403 Forbidden` response will be returned. \*\*
If a workload is not assigned an identity, it can still `GET` its parent org.
## Logs
Workload logs are consolidated from all the deployed locations and can be viewed using the UI or CLI.
Using the UI, the logs page will be prefilled with the [LogQL](https://grafana.com/docs/loki/latest/logql/)
query for the workload and [GVC](/reference/gvc) name.
```log Example LogQL Query theme={null}
{gvc="test-gvc", workload="test-workload"}
```
Logs can be further filtered by:
* `Date`
* `Location`
* `Container`
Grafana can be used to view the logs by clicking the `Explore on Grafana` link within the console.
Refer to the [logs](/core/logs) page for additional details.
## Rollout Options
Settings to control the rollout process between versions.
```yaml YAML theme={null}
spec:
rolloutOptions:
minReadySeconds: 0
maxUnavailableReplicas: 1
maxSurgeReplicas: 100%
scalingPolicy: OrderedReady
terminationGracePeriodSeconds: 30
```
### minReadySeconds
The minimum number of seconds that a workload replica must be running before the rollout progresses.
### maxUnavailableReplicas
The maximum number or percentage of replicas that can be unavailable during a rollout or during regular rescheduling of workloads.
### maxSurgeReplicas
The maximum number or percentage of new replicas that can be added during a rollout for each batch.
Example: If there are 4 running replicas and maxSurgeReplicas is set to 50%, then during each rollout 2 replicas will be added at the new version. Once they are healthy as determined by the [ReadinessProbe](#readiness-probe), the rollout will continue, -2 old replicas, +2 new replicas, -2 old replicas.
In cases where a short rollout cutover is needed, a maxSurgeReplicas setting of `100%` is recommended.
### scalingPolicy
The strategies used to update applications and services deployed. Valid values: `OrderedReady` (Updates workloads in a rolling fashion, taking down old ones and bringing up new ones incrementally, ensuring that the service remains available during the update.), `Parallel` (Causes all pods affected by a scaling operation to be created or destroyed simultaneously. This does not affect update operations.). Default: `OrderedReady`.
## Automatic Retries
Settings to control automatic http/grpc request retries
```yaml YAML theme={null}
spec:
requestRetryPolicy:
attempts: 2
retryOn:
- connect-failure
- '501'
```
### attempts
The amount of retries before sending the response to the client.
By default, attempts will be set to `2`.
### retryOn
Indicates under which circumstances a retry should be attempted. Can include [HTTP](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#x-envoy-retry-on) or [GRPC](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#x-envoy-retry-grpc-on) policies.
By default, retryOn will be set to `[connect-failure,refused-stream,unavailable,cancelled,resource-exhausted,retriable-status-codes]`
## Default Ephemeral Storage
Each workload replica receives at least 1GB of local ephemeral solid state drive (SSD) storage. Workloads that request more than 1 core of CPU receive 1GB of storage for each core. For example, a workload that requests 1500 millicore of CPU can consume up to 1.5GB of ephemeral storage.
If the replica uses more than its allotted ephemeral storage, it will be replaced with a new replica.
## Suspend
Each workload can be suspended which immediately stops the workload from serving traffic. This is the same as setting the min/max scale to 0. When the workload is unsuspended, it will resume serving traffic.
To temporarily deactivate a workload choose `Stop` from the Actions menu.
```yaml YAML theme={null}
spec:
defaultOptions:
suspend: true
```
The workload will stop running and will not serve any traffic.
To reactivate the workload, choose `Start` from the actions menu.
```yaml YAML theme={null}
spec:
defaultOptions:
suspend: false
```
## Timeout Seconds
`spec.defaultOptions.timeoutSeconds`
The maximum request duration in seconds before Control Plane will timeout. This timeout amount can be reached when Control Plane is waiting for the workload to respond or when waiting for a new workload to become available when using Autoscaling.
The minimum value is **1 second** and the maximum value is **600 seconds**.
### Metering and Billing
The CPU, memory and egress used for mounted object stores are billed to the workload. To review the costs of mounting an object store, query the container named `cpln-mounter` for the workload within the metrics page.
## Workload Health
* Possible values:
* `Loading`
* `Healthy`
* `Unhealthy`
* `Deleting`
* `Unknown`
## Multi-Zone
Multi-zone deployment distributes workload replicas across multiple availability zones within a location for higher availability. When enabled, Control Plane will attempt to spread replicas evenly across available zones.
```yaml YAML theme={null}
spec:
defaultOptions:
multiZone:
enabled: true
```
### Configuration
| Property | Type | Description |
| :-------- | :------ | :------------------------------------------------------- |
| `enabled` | boolean | Enable multi-zone replica distribution. Default: `false` |
Not all locations support multi-zone deployments. Confirm that your target location supports multiple availability zones before enabling this option.
When using multi-zone with a dedicated load balancer, enable `multiZone` on the GVC's load balancer settings as well to reduce cross-zone traffic costs.
## Special Tags
Control Plane supports special tags prefixed with `cpln/` that modify workload behavior. These tags provide access to advanced or niche configuration options that have not yet been implemented as first-class API options.
Some tags listed below are deprecated in favor of first-class spec options. Where indicated, prefer using the spec option as tags may be removed in future releases.
### Traffic and Networking
| Tag | Value | Description | Status |
| :------------------------------------ | :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| `cpln/publishNotReadyAddresses` | `true` | Routes internal traffic to replicas that haven't passed their readiness probe. See [Publish Not-Ready Addresses](#publish-not-ready-addresses). | |
| `cpln/protocol` | `http`, `http2`, `grpc`, `tcp` | Override the protocol detection for the workload. | Deprecated. Use [`ports[].protocol`](/reference/workload/containers#protocol). |
| `cpln/bypassProxyOutbound` | `true` | Bypass the service mesh proxy for outbound traffic. | |
| `cpln/disableServiceMeshInboundPort` | port number | Exclude specific inbound port from service mesh. | |
| `cpln/disableServiceMeshOutboundPort` | port number | Exclude specific outbound port from service mesh. | |
| `cpln/multiZone` | `true` | Enable multi-zone deployment for the workload. | Deprecated. Use [`spec.defaultOptions.multiZone`](#multi-zone). |
| `cpln/skipLocationEndpointHeaders` | `true` | Skip adding location endpoint headers in redirect responses. | |
| `cpln/discoverCrossGvcReplicas` | `true` | Enable discovery of replicas across different GVCs via mTLS. | |
### Observability
| Tag | Value | Description |
| :--------------------- | :----- | :--------------------------------------------- |
| `cpln/tracingDisabled` | `true` | Disable distributed tracing for this workload. |
### Resources
| Tag | Value | Description | Status |
| :---------------------------- | :----------------- | :------------------------------------------------------- | :---------------------------------------------------------------------------- |
| `cpln/largeDisk` | `true` | Enable large ephemeral disk allocation for the workload. | |
| `cpln/timeoutSecondsOverride` | seconds (max 3600) | Override the timeout seconds beyond the standard limit. | Use [`spec.defaultOptions.timeoutSeconds`](#timeout-seconds) for values ≤600. |
### BYOK and Direct Load Balancer Tags
These tags are only available for workloads running on [BYOK](/reference/location#byok-locations) clusters or workloads with [Direct Load Balancer](/reference/workload/load-balancing#direct-load-balancer) enabled.
| Tag | Value | Description |
| :------------------------------------ | :--------- | :-------------------------------------------------------------------------- |
| `cpln/disableServiceMesh` | `true` | Disable the service mesh entirely. |
| `cpln/disableServiceMeshOutboundCIDR` | CIDR range | Exclude specific CIDR range from service mesh outbound traffic. |
| `cpln/k8sClusterRole` | role name | Bind a Kubernetes ClusterRole to the workload's service account. BYOK only. |
### External Authorization
Configure an external authorization service for the workload. All requests will be checked against this service before being processed.
| Tag | Value | Default | Description |
| :---------------------------------------- | :-------------- | :--------- | :------------------------------------------ |
| `cpln/externalAuthAddress` | hostname/IP | (required) | Address of the external auth service. |
| `cpln/externalAuthPort` | port | `443` | Port of the external auth service. |
| `cpln/externalAuthProtocol` | `grpc`, `http` | `grpc` | Protocol to use for auth requests. |
| `cpln/externalAuthScheme` | `https`, `http` | `https` | URL scheme for the auth service. |
| `cpln/externalAuthTimeout` | duration | `1s` | Timeout for auth requests. |
| `cpln/externalAuthFailureAllow` | `true`, `false` | `true` | Allow requests if auth service fails. |
| `cpln/externalAuthPackAsBytes` | `true`, `false` | `false` | Pack request body as bytes. |
| `cpln/externalAuthRemoveRequestBody` | `true`, `false` | `false` | Remove request body before forwarding. |
| `cpln/externalAuthIncludePeerCert` | `true`, `false` | `false` | Include client certificate in auth request. |
| `cpln/externalAuthPathPrefix` | path | - | Path prefix for auth requests. |
| `cpln/externalAuthUpstreamHeaderPrefixes` | prefixes | - | Header prefixes to forward upstream. |
| `cpln/externalAuthListenPort` | port | - | Specific listen port to apply auth to. |
### External Rate Limiting
Configure an external rate limiting service for the workload.
| Tag | Value | Default | Description |
| :-------------------------- | :-------------- | :---------- | :------------------------------------- |
| `cpln/rateLimitAddress` | hostname/IP | (required) | Address of the rate limit service. |
| `cpln/rateLimitPort` | port | `443` | Port of the rate limit service. |
| `cpln/rateLimitDomain` | string | `cpln` | Rate limit domain identifier. |
| `cpln/rateLimitScheme` | `https`, `http` | `https` | URL scheme for the rate limit service. |
| `cpln/rateLimitDescriptors` | string | `authority` | Descriptors to use for rate limiting. |
### Internal Tags
The following tag is used internally and should generally not be set manually:
| Tag | Value | Description |
| :------------ | :----- | :---------------------------------------------------------------------------- |
| `cpln/ignore` | `true` | Causes the scheduler to ignore this workload. Used for internal testing only. |
## CLI
To view the CLI documentation for Workloads, see the [Workload CLI reference](/cli-reference/commands/workload).