​
Overview

Refer to the Workload concepts page.

​
Create a Workload

Refer to the Create a Workload guide for additional details.

​
Access Report

Displays the permissions granted to principals for the workload.

​
Identity

Refer to the identities 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 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.
GET https://doc-test-v39red0.cpln.app/ HTTP/1.1
Host: doc-test-v39red0.cpln.app
Connection: keep-alive
x-cpln-debug: true

​
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.

The endpoint can be configured to use the org endpoint prefix. 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.

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

​
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

​
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. 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 NameDescriptionFormat
CPLN_GLOBAL_ENDPOINTThe canonical Host header that the container will receive requests on${\workloadName}-${gvcAlias}.cpln.app
CPLN_GVCThe Global Virtual Cloud (/reference/gvc) the container is running understring
CPLN_GVC_ALIASThe Global Virtual Cloud Alias13 digit alphanumeric value
CPLN_LOCATIONThe location the container is serving the request fromaws-us-west-2, azure-eastus2, gcp-us-east1, etc.
CPLN_NAMESPACEThe namespace of the containerGenerated random string (e.g., aenhg2ec6pywt)
CPLN_PROVIDERThe cloud provider the container is serving the request fromaws, azure, gcp, etc.
CPLN_ORGThe org the container is running understring
CPLN_WORKLOADThe workload the container is running understring
CPLN_WORKLOAD_VERSIONThe 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_TOKENA token used to authenticate to the Control Plane CLI / APIRandom authorization token
CPLN_IMAGEThe image as defined for this container in the Control Plane apistring

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:

  • 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 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.

​
Rollout Options

Settings to control the rollout process between versions.

YAML
spec:
  rolloutOptions:
    minReadySeconds: 0
    maxUnavailableReplicas: 1
    maxSurgeReplicas: 100%
    scalingPolicy: OrderedReady

​
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 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.

​
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
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 or GRPC 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
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
spec:
  defaultOptions:
    suspend: false

​
Timeout

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

​
CLI

To view the CLI documentation for Workloads, click here.