Refer to the Workload concepts page.
Refer to the Create a Workload guide for additional details.
Refer to the CLI documentation for workloads.
Displays the permissions granted to principals for the workload.
Workload auto-scaling is configured by setting a strategy and target value which controls when the workload will scale up & down.
The current capacity is evaluated every 2 seconds and compared against the scale target. It averages requests completed over the previous 60 seconds to avoid rapid changes. If ever a scaling decision is made which results in a scale increase above 200% then it suspends scale down decisions and averages over 6 seconds for 60 seconds. This is to allow for rapid scaling when a burst of traffic is detected.
As the system scales up, traffic will not be sent to the new replicas until they pass the readiness probe, if configured. If there is no probe configured or if it is a basic TCP port check, the requests will hit the new replicas before they are ready to respond. This could cause a delay or errors for end-user traffic.
Selectable Scaling Strategies:
(requests * requestDuration)/(timePeriod * replicas)
.(1000 * .05)/(1 * 5) = 10
.Options:
Maximum Scale
inclusive).Capacity AI is not available if CPU Utilization is selected because dynamic allocation of CPU resources cannot be accomplished while scaling replicas based on the usage of its CPU.
Workloads can leverage intelligent allocation of its container's resources (CPU and Memory) by using Capacity AI.
Capacity AI uses an analysis of historical usage to adjust these resources up to a configured maximum.
This can significantly reduce cost, but may cause temporary performance issues with sudden spikes in usage.
If capacity AI is disabled, the amount of resources configured will be fully allocated.
Capacity AI must be disabled if the autoscaling strategy is set to CPU Utilization
.
Changes made to a workload will reset its historical usage and will restart the analysis process.
When resources are not being used, Capacity AI will downscale CPU usage to a minimum of 25 millicores. The minimum will increase depending on the memory size being recommended by Capacity AI using a 1:3 ratio of CPU millicores to memory MiB.
The container entrypoint can be overridden by entering a custom command value.
Custom command line arguments can be sent to the container during deployment.
These arguments will be appended to the image ENTRYPOINT
.
The argument list is ordered and will be passed to the container in the same order.
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.
Workloads must have at least one container configured with the following:
If a workload has more than one container, only one can serve traffic.
The ports listed below are blocked and are not allowed to be used.
Containers which attempt to use these ports will not be able to bind.
8012, 8022, 9090, 9091, 15000, 15001, 15006, 15020, 15021, 15090, 41000
The following rules apply to the name of a container:
cpln_
.To deactivate / shut-down a workload, perform the following steps:
Options
.Min Scale
and Max Scale
settings to 0
.Save
The workload will scale to zero and will not serve any traffic. To reactivate the workload, restore the
Min Scale
and Max Scale
settings to their needed values.
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.Using the console, debug can be activated by:
Options
.Debug
switch to on
.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.Sample Request Headers:
copyGET https://doc-test-v39red0.cpln.app/ HTTP/1.1Host: doc-test-v39red0.cpln.appConnection: keep-alivex-cpln-debug: true
Sample Response Headers:
copyHTTP/1.1 200 OKcontent-length: 2993content-type: text/plaindate: Fri, 10 Sep 2021 21:34:27 GMTx-envoy-upstream-service-time: 2x-cpln-location: aws-us-west-2x-cpln-replica: doc-test-00083-deployment-75584b7d66-f8wtb
This URL is globally load-balanced and TLS terminated. If a domain configured for the GVC, this endpoint will use that domain.
This URL is similar to the global endpoint but maps to the built-in Control Plane domain cpln.app
. This can be used for
testing if there is an issue with the custom domain that is associated with the GVC.
Within each deployment, a location specific URL is available that can be used for testing if there is an issue with the global/canonical URL or with a specific location.
Custom environment variables can be made available to the image running within a container.
The value of the variable can be in plain text or a secret value.
The length of an environment variable value cannot be greater than 4096 characters.
Each workload has the following built-in environment variables:
Variable Name | Description | Format |
---|---|---|
CPLN_ENDPOINT | The domain name that the container will be receiving requests from | Fully Qualified Domain Name (e.g., controlplane.us) |
CPLN_GVC | The Global Virtual Cloud (GVC) the container is running under | /org/ORG_NAME/gvc/GVC_NAME |
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 | ORG_NAME |
CPLN_WORKLOAD | The workload the container is running under | /org/ORG_NAME/gvc/GVC_NAME/WORKLOAD_NAME |
CPLN_TOKEN | An token used to authenticate to the Control Plane CLI / API | Random authorization token |
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.
TIP: If a Workload is not assigned an Identity, it can still GET
its parent Org.
Sensitive values can be used as an environment variable by using a secret.
The identity of the workload must be member of a profile that has the reveal
permissions on the secret.
When adding an environment variable using the UI, a list of available secrets can be accessed by pressing Control-S within the value textbox.
If you do not have any secrets defined, the prefix cpln://secret/
will be inserted.
The following variable names are not allowed to be used as a custom environment variable:
K_SERVICE
K_CONFIGURATION
K_REVISION
The PORT
environment variable is provided at runtime and available to a container.
It can be assigned as a custom environment variable in all cases except when the container is exposed and the value doesn't match that of the exposed port.
For example:
3000
:3000
.3000
.A .env file can be uploaded using the console to import multiple environment variables. Secret values are supported.
Sample .env file:
copyURL=http://test.example.comUSERNAME=user001PASSWORD=cpln://secret/username_secret.passwordDATA=cpln://secret/opaque_secret.payload
The external firewall is used to control Internet traffic to/from a workload.
Inbound Requests:
The CIDR address 0.0.0.0/0
allows full inbound access from the entire public Internet.
Outbound Requests:
The CIDR address 0.0.0.0/0
allows full outbound access to the entire public Internet.
The internal firewall is used to control access between other workloads within an org.
Available Options:
None
: No access is allowed between workloads.Same GVC
: Workloads running in the same GVC are accessible.Same Org
: Workloads running in the same org are accessible.Specific Workloads
: Specific workloads are allowed access this workload.view
permission, set within a policy, on the workload being specified.Allow to Access Itself
: Enables replicas of this workload to access themselves.Refer to the identities page for additional details.
Each workload must be configured with at least one container, associated with an image.
Images can be pulled from:
A public registry
Org's private registry
/org/ORG_NAME/image/IMAGE_NAME:TAG
//image/IMAGE_NAME:TAG
Each Workload container can be configured to execute the PostStart
lifecycle hook.
This hook is executed immediately after a container is created. However, there is no guarantee that the hook will execute before the container ENTRYPOINT.
This hook can be configured using the console or cpln apply.
Using the console
Save
.Using cpln apply
Only the exec
type is supported.
Example:
Add the lifecycle
section to an existing workload container.
copyspec:containers:- name: advanced-options-exampleargs: []cpu: 50menv: []image: '/org/ORG_NAME/image/IMAGE:TAG'memory: 128Miport: 8080lifecycle:postStart:exec:command:- sh- '-c'- sleep 10
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 Querycopy{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.
Control Plane can collect custom metrics from your workload by having your application emit a Prometheus formatted list of metrics at a path and port of your choosing. The port can be different than the one serving traffic. Each container in a workload can be configured with metrics.
The convention is to use the path /metrics
, but any path can be used.
Sample output from the metrics endpoint:
copyMY_COUNTER 788MY_COUNTER_2 123NUM_USERS 2NUM_ORDERS 91
The platform will scrape all the replicas in the workload every 30 seconds and they must respond within 5 seconds. Metric names
with the prefix cpln_
will be ignored by the scrapping process.
The collected metrics can be viewed by clicking the Metrics
link on the workload page within the console. Clear any existing query and
enter the name of the metric. Click Run Query
to execute.
The time-series displayed will include these labels:
org
gvc
location
provider
region
cluster_id
replica
To pause / suspend a workload, set the min and max scale to 0 within the Autoscaling configuration of the Options page.
The permissions below are used to define policies together with one or more of the four principal types:
Permission | Description | Implies |
---|---|---|
create | Create new workloads | |
delete | Delete existing workloads | |
edit | Modify existing workloads | view |
manage | Full access | create, delete, edit, manage, view |
view | Read-only access |
Probes are a feature of Kubernetes that are used to control the health of an application running inside a container.
The readiness probe is an action that is defined to let the workload know that the application running within the container is ready to receive traffic. For example, if the application is performing some actions during start-up and needs it to complete before serving requests, the readiness probe can fail until the actions have been completed.
The liveness probe is an action that is defined to check if the application running within the container is healthy. If the probe fails, the container will be restarted. For example, if the application code caused itself to be in a deadlock, the liveness probe can catch that the container is not healthy, since it didn't respond to the probe, and restart. This will ensure that the application is available until the bug that is causing the deadlock is fixed.
Health Check Type:
Configurable Limits:
Unready
. (must be between 1 and 20 inclusive, default is 3).Refer to the Kubernetes probe documentation here for additional details.
Each container can have its amount of CPU and Memory configured. Select an appropriate value for your container.
If capacity AI is enabled, these values will be the maximum that the container could be provisioned with.
If capacity AI is disabled, these values will be reserved when the container is provisioned.
Resource Type | Default Unit | Default Value | Min | Max |
---|---|---|---|---|
CPU | Millicores | 50 | 0 | 8000 |
Memory | MiB | 128 | 1 | 8192 |
Memory Units:
You can express memory as a plain integer or as a fixed-point number
using one of these suffixes: E
, P
, T
, G
, M
, k
.
You can also use the power-of-two equivalents: Ei
, Pi
, Ti
, Gi
, Mi
, Ki
.
For example, the following represent roughly the same value:
128974848, 129e6, 129M, 123Mi
Refer to the Kubernetes Meaning of Memory reference page for additional details.
Each workload replica receives 1GB of local ephemeral solid state drive (SSD) storage.
If the replica uses more than 1GB, it will be replaced with a new, fresh replica.
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.
Object stores, such as S3, can be mounted as a file system on a container by adding one or more volumes.
A volume consists of a URI and a Mount Path. The URI is prefixed with the provider scheme followed by the bucket/storage name (e.g., s3://my-s3-bucket). The Mount Path must be a unique absolute path (e.g., /s3-files). This path will be added to the container's file system and accessible by the running application.
During the set up of a volume using the console, the URI name can be entered manually or an existing Cloud Account can assist looking up the name.
The identity of the workload is used to authenticate to the provider's cloud storage API when accessing a mounted path. A Cloud Account for each cloud storage provider, with the necessary access/roles, must exist and be associated with the workload identity.
Provider | URI Scheme | Mode | Example |
---|---|---|---|
AWS S3 | s3:// | read-only | s3://my-s3-bucket |
Google Cloud Storage | gs:// | read-only | gs://my-google-bucket |
Azure Blob Storage | azureblob:// | read-only | azureblob://my-azure-account/container |
Azure Files | azurefs:// | read-write | azurefs://my-azure-account/my-files |
To allow a workload identity the ability to authenticate to an object store, a cloud access rule must be created for each provider. A Cloud Account for each provider must exists in order to create the cloud access rule.
The following list contains the minimum roles/scopes that must be added to a cloud access rule:
S3 (using an AWS Cloud Account)
Create a new AWS role with existing policies
and choose AmazonS3ReadOnlyAccess
.Google Cloud Storage (using a Google Cloud Account)
Create a new GCP service account
.Select bucket name
.Storage Legacy Bucket Reader
and Storage Legacy Object Reader
.Storage Admin
role.Azure Blob Storage and Files (using an Azure Cloud Account)
Select storage account
.Storage Blob Data Reader
.To allow a Workload access to the object stores, the outbound requests of its external firewall
must either be set to All Outbound Requests Allowed
or the hostnames listed below for the corresponding object store must
be added to the Outbound Hostname Allow List
.
AWScopy*.amazonaws.com
Azure Blobcopy*.blob.core.windows.net*.azure.com
Azure Filecopy*.file.core.windows.net*.azure.com
GCPcopy*.googleapis.com
/dev
/dev/log
/tmp
/var
/var/log
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.
The container working directory can be overridden by entering a custom directory. The value must be an absolute path.
Loading
Healthy
Unhealthy
Deleting
Unknown