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:

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:

Enhanced Container Controls

Instance Level Settings

Container Level Settings

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