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 subcommand.
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:
debug is active and the header x-cpln-debug: true is in the request.
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.
GET https://doc-test-v39red0.cpln.app/ HTTP/1.1Host: doc-test-v39red0.cpln.appConnection: keep-alivex-cpln-debug: true
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.The endpoint can be configured to use the org endpoint prefix.
This adds the prefix as a subdomain to cpln.app.
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
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.
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.
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.
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. 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.
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 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 or API without any additional authentication.Examples:
** 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.
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
query for the workload and GVC name.
Example LogQL Query
{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 page for additional details.
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, 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.
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.
Indicates under which circumstances a retry should be attempted. Can include HTTP or GRPC policies.By default, retryOn will be set to [connect-failure,refused-stream,unavailable,cancelled,resource-exhausted,retriable-status-codes]
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.
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
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.
spec.defaultOptions.timeoutSecondsThe 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.
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.
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.
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.
