Glossary

StackPath offers many ways for you to customize your Edge Compute Workload through our API. This page contains a list of all available Edge Compute settings along with their definitions.

πŸ“˜

Create a workload now

Please see our API Reference to start creating your new workload.

name

The name you give to your workload will appear in the Workloads dashboard in the StackPath Control Portal. Customizable workload names are perfect for organizational purposes.

slug

Each workload will have a slug which is a stack-unique, immutable, human readable, stable identifier for the workload. The slug is used in combination with the stack's slug, the target's name, and other information to compose an instance's name.

If a slug is not provided at the time of workload creation, one will be generated based on the name of the workload. If specifying a slug, it must be a valid DNS 1123 label or more specifically, match the following constraints:

  • MUST be at least 1 character, and no more than 63
  • MUST consist of lower case alphanumeric characters or '-', and MUST start and end with an alphanumeric character
  • MUST match the format of [\[a-z0-9\](\[-a-z0-9\]\*\[a-z0-9\])](<>)?

metadata

A workload can be provided with annotations and labels in the form of string key/values. Both can contain arbitrary values that may or may not influence the instances created in the workload.

annotations

Annotations provide a method to influence the behavior of a workload in a way which may not yet be available through a field on the specification.

Please see the table below for a list of the most commonly used annotations:

AnnotationDescription
anycast.platform.stackpath.net- This annotation is provided when the workload is created.
- When specified, an Anycast IP address will be allocated for the workload and will direct traffic to the appropriate instance of a workload for an incoming connection.
- The value format should be "true".
- After you create a workload, you cannot update, add, or remove this value.
workload.platform.stackpath.net/ssh-public-keys- This annotation is provided when the workload is created.
- This annotation is required for virtual machine-based workloads, which will configure a virtual machine to permit SSH access to clients with the appropriate corresponding private key.
- The value format should be a newline delimited set of public SSH keys.
- After you create a workload, you can still update the value; however, the update will only take place for newly created instances.
workload.platform.stackpath.net/remote-management- This annotation can be enabled or disabled on a workload at any time.
- When set to "true", the remote management capabilities for the instance will be enabled.
- To learn more, see Enable Remote Access and Connect to a Container or Enable Remote Access and Connect to a Virtual Machine.
- The value format should be either "true" or "false".
workload.platform.stackpath.net/exclude-unicast-nat- This annotation is provided when the workload is created.
- When specified, unicast IP will not be allocated to any instance in the workload.
- The value format should be "true".
- After you create a workload, you cannot update, add, or remove this value.
workload.platform.stackpath.net/ddos-service-class- This annotation is disabled by default when creating a workload using the StackPath API.
- This annotation can be enabled or disabled on a workload at any time.
- When set to "stackpath-edge/base", L3-L4 DDoS Protection will be enabled on a workload.
- To learn more, see L3-L4 DDoS Protection.

labels

Labels allow you to identify your instances, which can be useful when used with network policy instance selectors

With an instance selector, you can write a network policy that will only apply to certain instances. The instance selector is defined in the spec.

---
networkPolicy:
  name: Allow All SSH Access
  slug: allow-all-ssh
  spec:
    instanceSelectors:
    - key: workload.platform.stackpath.net/workload-slug
      operator: in
      values:
        - sp-networkpolicytest
    policyTypes:
    - INGRESS
    priority: 30000
    ingress:
    - action: ALLOW
      protocols:
        tcp:
          destinationPorts:
          - '22'

In the example above, the instance selector's key is workload.platform.stackpath.net/workload-slug and value is sp-networkpolicytest. This policy will only apply to instances in this workload. If more values were to the instance selector provided, a logical OR operation would be used for matching.

The instance selector can also apply as a source or a destination. For example, if you want to allow SSH connections from only devices with some other tag, you can use an instance selector to identify those devices.

---
networkPolicy:
  name: Allow All SSH Access
  slug: allow-all-ssh
  spec:
    policyTypes:
    - INGRESS
    priority: 30000
    ingress:
    - action: ALLOW
      from:
        instanceSelectors:
        - key: workload.platform.stackpath.net/workload-slug
          operator: in
          values:
            - sp-networkpolicytest
      protocols:
        tcp:
          destinationPorts:
          - '22'

In the example above, this policy will apply to all instances. It will only allow instances in the sp-networkpolicytest workload to connect via SSH to this instance.

version

A metadata entry's version number. Metadata versions start at 1 when they are created and increment by 1 every time they are updated.

spec

The specification for the desired state of a workload. A workload's spec describes what you want to run in the workload's instances.

networkInterfaces

An instance can have one or more network interfaces, each attached to a network. Each network interface will be seen as a discrete interface within the instance, and will have an IP address allocated to it for the attached network. Only the first network interface will have an external unicast IP address allocated to it.

Network interfaces cannot be changed after the creation of a workload.

If no network interface is provided during the creation of a workload, a single network interface will be added and attached to the default network within the stack the workload is being created in.

volumeClaimTemplates

A volume claim template is used to specify additional, persistent storage that should be attached to each instance.
Volumes can be sized between 1GiB and 1TiB. Each instance receives a volume, they are not shared. If instances are removed due to scaling events, their corresponding volumes will be removed as well.

phase

Defines the phase a volume claim is currently in. VOLUME_CLAIM_PHASE_UNSPECIFIED is the default phase if none is specified.

  • VOLUME_CLAIM_PHASE_UNSPECIFIED: StackPath is unable to determine the volume claim's state

  • PENDING: The volume claim is pending

  • UNBOUND: The volume claim is unbound

  • BOUND: The volume claim is bound to an instance

imagePullCredentials

If the image requires authentication to access, credentials can be provided via Image Pull Credentials on the workload. Images are pulled directly from their registries, are not held in an intermediate cache, and not guaranteed to be cached on any host in the fleet.

  • dockerRegistry: The authentication configuration that should be used to pull images from a docker registry.
    • server: The server that the credentials should be used with. This value will default to the docker hub registry when not set.
    • username: The username that should be used to authenticate the image pull.
    • password: The password that should be used to authenticate the image pull.
    • email: The email address to use for the docker registry account.

containers/virtualMachines

The table below contains the settings used by the containers and/or virtualMachines parameters:

NamecontainersvirtualMachinesDescription
imageyesyesContainer: An OCI compatible image such as those found on Docker Hub is required when creating a container.

VM: StackPath maintains a set of images that you can use to create your VMs.

NOTE: When updating the value of an image on a workload, only new instances will be impacted by the setting change.
commandyesnoCommands that start a container.
envyesnoExposed to containers as OS Environment Variables, enabling applications to be provided a configuration that may be workload specific.

Used to provide configuration values such as DNS Discovery addresses, log levels, and application specific values to containers when they start.

An environment variable can obtain its value from either a value field, or a secretValue field. When providing a value via the secretValue field, it will be encrypted on our platform up to the point of being provided to the container, and will be masked in API responses with the value of [REDACTED].
portsyesyesTo leverage SRV queries in the DNS Discovery feature, ports must be defined to provide a name to be used in the SRV query.

To learn more, see Edge Compute DNS Discovery.

Each port will define the network port number which it will listen on, and the protocol for which it will answer (TCP or UDP).
livenessProbeyesyesProbes are HTTP, TCP or exec actions which the platform will repeatedly execute against an instance.

If a liveness probe fails, the platform will restart the container or VM with the failing probe.

An HTTP probe will fail if the target returns a non-200 response (or is not available).

For more information on probes, please see this guide.
readinessProbeyesyesIf a readiness probe fails, the instance will not be considered ready, and will not be added to anycast announcements.
resourcesyesyesThere are 2 types of resources currently available, CPU and memory.

CPU is the number of cores to allocate per container or VM. Memory is the amount of memory to allocate per container or VM.

To learn more about available configurations, visit the Edge Compute section of the StackPath site.
volumeMountsyesyesVolume mounts reference a volume claim template by slug, and specify which path to mount the volume to within the container or virtual machine.
userDatanoyesUser Data is a mechanism to provide cloud-init configuration settings for instance initialization.

Enhanced Container Controls

Instance Level Settings

SettingDescription
initContainersList of initialization containers belonging to the instance which are executed in order prior to containers being started.
workload.spec.runtime.containers.terminationGracePeriodSecondsOptional duration in seconds the instance needs to terminate gracefully (ranging from 0-300 seconds).
workload.spec.runtime.containers.hostAliasesOptional list of hosts and IPs that will be injected into the instance's hosts file if specified. IPv4/v6 are supported.
workload.spec.runtime.containers.dnsConfigSpecifies the DNS parameters of a instance. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy. IPv4/v6 are supported.

NOTE: DNS configuration options (nameservers, search domains, etc) are not compatible with the DNS Discovery functionality.
workload.spec.runtime.containers.shareProcessNamespaceRuns all containers in a single process namespace, allowing interaction between applications.
workload.spec.runtime.containers.securityContext.runAsUserAllows adjusting the user that the container entrypoint executes as.
workload.spec.runtime.containers.securityContext.runAsNonRootForce to run container as non-root user.
workload.spec.runtime.containers.securityContext.runAsGroupAllows adjusting the user group that the container entrypoint executes as.
workload.spec.runtime.containers.securityContext.supplementalGroupsAdditional list of user groups applied to the first process run in each container, in addition to the container's primary GID, the fsGroup (if specified), and group memberships defined in the container image for the UID of the container process.
workload.spec.runtime.containers.securityContext.sysctlsKernel parameters to optimize the performance of a container.

Container Level Settings

SettingDescription
workload.spec.containers[*].nameName of the container.
workload.spec.containers[*].imageContainer image name.
workload.spec.containers[*].imagePullPolicyImage pull policy. One of Always, Never, IfNotPresent.
workload.spec.containers[*].commandCommand that starts the container.
workload.spec.containers[*].argsDefine arguments for your command.

If you define args, but do not define a command, the default command is used with your new arguments.
workload.spec.containers[*].workingDirContainer's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image.
workload.spec.containers[*].portsList of ports to expose from the container.
workload.spec.containers[*].envList of environment variables to set in the container.
workload.spec.containers[*].volumeMountsInstance volumes to mount into the container's filesystem.
workload.spec.containers[*].resourcesCompute Resources required by this container.
workload.spec.containers[*].lifecycleActions that the management system should take in response to container lifecycle events.

NOTE: httpGet/tcpSocket and exec actions are supported in all probes (startupProbe/livenessProbe/readinessProbe) and lifecycle actions (postStart/preStop) for container workloads.
workload.spec.containers[*].lifecycle.postStartPostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes.

postStart hooks with HTTP/TCP action handlers can only be used when it is expected that the container will be started immediately. Exec action handlers can be used in cases where the container does not start immediately.
workload.spec.containers[*].lifecycle.preStopPostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes.

Lifecycle's postStart hook can only be used when it is expected that the container will be started immediately.
workload.spec.containers[*].terminationMessagePathPath at which the file to which the container's termination message will be written is mounted into the container's filesystem.
workload.spec.containers[*].terminationMessagePolicyIndicate how the termination message should be populated.
workload.spec.containers[*].livenessProbePeriodic probe of container liveness.
workload.spec.containers[*].readinessProbePeriodic probe of container service readiness.
workload.spec.containers[*].startupProbeIndicates that the instance has successfully initialized. If specified, no other probes are executed until this completes successfully.
workload.spec.containers[*].securityContext.runAsUserAllows adjusting the user that the container entrypoint executes as.
workload.spec.containers[*].securityContext.runAsNonRootForce to run container as non-root user.
workload.spec.containers[*].securityContext.runAsGroupAllows adjusting the user group that the container entrypoint executes as.
workload.spec.containers[*].securityContext.readOnlyRootFilesystemSetup root filesystem as read-only.
workload.spec.containers[*].securityContext.allowPrivilegeEscalationControls whether a process can gain more privileges than its parent process.
workload.spec.containers[*].securityContext.capabilitiesLinux capabilities to add/drop when running containers.

targets

A target is used to express where deployments should exist, and how many instances should be within each deployment.

A workload can have one or more target definitions and you can use multiple targets to organize instances regionally. There are no advantages or disadvantages to creating a single workload with multiple targets or creating multiple workloads.

For example, you can create and define a target named "eu" to only deploy to cities in the European Union. Similarly, you can create and define a target named "na" to only deploy to cities in North America.

A target's name must be unique within the workload and be a valid DNS 1123 label; the name is used along with the workload slug and cityCode to generate an instance's name, which is then used in DNS Discovery.

deploymentScope

The deployment scope influences where individual deployments should be created by specifying the name of a label that exists on locations capable of deploying compute. For each location matched by the deployment selectors, a unique list of the specified label's values is recorded. For each unique value of the label, a deployment will be created and instances will be created on any location with that value.

Today, the only valid label for a deployment scope is cityCode.

deployments

A deployment's specification:

  • minReplicas: The minimum number of instances in a deployment.
  • maxReplicas: The maximum number of instances in a deployment.
  • scaleSettings: Workload deployments can be configured to automatically add and remove instances when the observed values of a metric exceeds or falls under a specified threshold. Today, the only metric available is cpu.
    • metrics: Metrics to observe for invoking scaling events.
      • metric: The metric to measure against.
      • averageValue: The target average value for the metric measured across all instances within a deployment, expressed as a quantity.
      • averageUtilization: The target average value for the metric measured across all instances within a deployment, expressed as a percentage of requested resources.
  • selectors: Selectors are filters that let the platform know where a workload's instances should exist by defining constraints on label values. For locations where workload instances can run, the platform exposes a cityCode label that can be used in a deployment's selectors by specifying the label values should contain certain strings such as DFW, LHR, HKG, or any cityCode value returned by the locations API call.
    • key: The name of the selector to perform a match against.
    • operator: The operation to perform to match a selector. Valid values are "In", "NotIn", "Exists", and "DoesNotExist".
    • values: The values to match in the selector.

status

Defines the status a workload is currently in. ACTIVE is the default status.

  • ACTIVE: The workload is active
  • SUSPENDED: The workload is suspended
  • BILLING_SUSPENDED: The workload is suspended due to non-payment
  • INACTIVE: The workload is inactive or has been deleted