The StackPath Developer Portal

Integrate our platform directly into your products and dynamically protect your edge.

Get Started    API Reference

Create a Container Workload

Overview

You can use this guide to better understand how to create a container-based workload via the StackPath API. This guide complements the corresponding API reference for the Create a workload API call.

📘

Note

Before you begin, you must have an existing stack.

📘

Note

StackPath supports any OCI compatible image (Docker v2, etc). To learn more, see Container image formats.

Understand the request

To create a workload, there are three types of specifications to configure.

  • Use containers to define container specifications.
  • Use resources to define the amount of CPUs and memory for each container of your workload.
  • Use targets to define where to run your containers and how many containers to run in each location.

Review sample request

Review the following sample request for a workload that:

  • Runs nginx
  • Contains a single instance in Dallas, Chicago, Frankfurt, and Amsterdam

This example also provisions an anycast IP with the workload, shared across all containers in the workload.

📘

Note

IATA airport codes are used to define the value of the city code.

To view a full list of supported cities, you can query the API for a list of valid locations.

curl -s -X POST https://gateway.stackpath.com/workload/v1/stacks/STACK_ID/workloads \
-H "Authorization: bearer BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
   "workload": {
      "name": "test workload",
      "metadata": {
        "version": "1",
        "annotations": {
          "anycast.platform.stackpath.net": "true"
        }
      },
      "spec": {
        "networkInterfaces": [
          {
            "network": "default"
          }
        ],
        "containers": {
          "webserver": {
            "image": "nginx:latest",
            "command": [],
            "ports": {
              "http": {
                "port": 80
              },
              "https": {
                "port": 443
              }
            },
            "resources": {
              "requests": {
                "cpu": "1",
                "memory": "2Gi"
              }
            }
          }
        }
      },
      "targets": {
        "north-america": {
          "spec": {
            "deploymentScope": "cityCode",
            "deployments": {
              "minReplicas": 1,
              "selectors": [
                {
                  "key": "cityCode",
                  "operator": "in",
                  "values": [
                    "DFW","ORD"
                  ]
                }
              ]
            }
          }
        },
        "europe": {
          "spec": {
            "deploymentScope": "cityCode",
            "deployments": {
              "minReplicas": 1,
              "selectors": [
                {
                  "key": "cityCode",
                  "operator": "in",
                  "values": [
                    "FRA","AMS"
                  ]
                }
              ]
            }
          }
        }
      },
      "slug": "test-workload"
    }
}'

Review sample return

Review the following sample return for the above request.

The request will return a JSON object.

📘

Note

In the sample return below, id refers to the workload ID.

{
  "workload": {
    "stackId": "9sample6-51d1-4377-b019-e01f65810804",
    "id": "9sample1-4efc-49c8-a32d-18add7e5b301",
    "name": "test workload",
    "metadata": {
      "annotations": {
        "anycast.platform.stackpath.net": "true",
        "anycast.platform.stackpath.net/subnets": "185.sample.data.here/32"
      },
      "createdAt": "2019-02-13T03:39:37.861372191Z",
      "version": "1"
    },
    "spec": {
      "networkInterfaces": [
        {
          "network": "default"
        }
      ],
      "containers": {
        "webserver": {
          "image": "nginx:latest",
          "command": [],
          "ports": {
            "http": {
              "port": 80
            },
            "https": {
              "port": 443
            }
          },
          "resources": {
            "requests": {
              "cpu": "1",
              "memory": "2Gi"
            }
          }
        }
      }
    },
    "targets": {
      "north-america": {
        "spec": {
          "deploymentScope": "cityCode",
          "deployments": {
            "minReplicas": 1,
            "selectors": [
              {
                "key": "cityCode",
                "operator": "in",
                "values": [
                  "DFW",
                  "ORD"
                ]
              }
            ]
          }
        }
      },
      "europe": {
        "spec": {
          "deploymentScope": "cityCode",
          "deployments": {
            "minReplicas": 1,
            "selectors": [
              {
                "key": "cityCode",
                "operator": "in",
                "values": [
                  "FRA",
                  "AMS"
                ]
              }
            ]
          }
        }
      }
    },
    "slug": "test-workload"
  }
}

Review the following sample request to obtain details for your workflow.

curl -X GET https://gateway.stackpath.com/workload/v1/stacks/STACKID/workloads/WORKLOAD_ID/instances \
-H "Authorization: bearer BEARER_TOKEN" \
-H "Content-Type: application/json"

The above request will return a JSON object that contains your workflow's details, such as:

  • The number of instances created in total
  • The status of each instance (Starting, Running, etc.)
  • The city location for each instance
  • The private IP address, public IP address, and gateway IP address for each instance
{
  "pageInfo": {
    "totalCount": "4",
    "hasPreviousPage": false,
    "hasNextPage": false,
    "endCursor": "3"
  },
  "results": [
    {
      "stackId": "9sample6-51d1-4377-b019-e01f65810804",
      "id": "0sample5-2f41-11e9-a490-0cc47a18ec26",
      "name": "test-workload-north-america-ord-0",
      "location": {
        "city": "Chicago",
        "cityCode": "ORD",
        "subdivision": "Illinois",
        "subdivisionCode": "IL",
        "country": "United States",
        "countryCode": "US",
        "continent": "North America",
        "latitude": 41.878113,
        "longitude": -87.629799
      },
      "phase": "RUNNING",
      "ipAddress": "10.x.x.x",
      "externalIpAddress": "151.x.x.x",
      "createdAt": "2019-02-13T03:39:48Z",
      "startedAt": "2019-02-13T03:39:48Z",
      "networkInterfaces": [
        {
          "network": "default",
          "ipAddress": "10.x.x.x",
          "ipAddressAliases": [
            "151.x.x.x"
          ],
          "gateway": "10.x.x.x"
        }
      ],
      "resources": {
        "limits": {
          "cpu": "1",
          "memory": "2Gi",
          "ephemeral-storage": "5Gi"
        }
      },
      "containerStatuses": [],
      "reason": "",
      "message": ""
    },
    {
      "stackId": "9sample6-51d1-4377-b019-e01f65810804",
      "id": "5samplec-2f41-11e9-a945-0cc47a18eade",
      "name": "test-workload-europe-ams-0",
      "location": {
        "city": "Amsterdam",
        "cityCode": "AMS",
        "subdivision": "Noord-Holland",
        "subdivisionCode": "NH",
        "country": "Netherlands",
        "countryCode": "NL",
        "continent": "Europe",
        "latitude": 52.370216,
        "longitude": 4.895168
      },
      "phase": "RUNNING",
      "ipAddress": "10.x.x.x",
      "externalIpAddress": "151.139.83.6",
      "createdAt": "2019-02-13T03:42:20Z",
      "startedAt": "2019-02-13T03:42:20Z",
      "networkInterfaces": [
        {
          "network": "default",
          "ipAddress": "10.x.x.x",
          "ipAddressAliases": [
            "151.x.x.x"
          ],
          "gateway": "10.x.x.x"
        }
      ],
      "resources": {
        "limits": {
          "cpu": "1",
          "memory": "2Gi",
          "ephemeral-storage": "5Gi"
        }
      },
      "containerStatuses": [],
      "reason": "",
      "message": ""
    },
    {
      "stackId": "9sample6-51d1-4377-b019-e01f65810804",
      "id": "0sampleb-2f41-11e9-85d0-0cc47a81b1be",
      "name": "test-workload-north-america-dfw-0",
      "location": {
        "city": "Dallas",
        "cityCode": "DFW",
        "subdivision": "Texas",
        "subdivisionCode": "TX",
        "country": "United States",
        "countryCode": "US",
        "continent": "North America",
        "latitude": 32.78014,
        "longitude": -96.800453
      },
      "phase": "RUNNING",
      "ipAddress": "10.x.x.x",
      "externalIpAddress": "151.x.x.x",
      "createdAt": "2019-02-13T03:39:55Z",
      "startedAt": "2019-02-13T03:39:56Z",
      "networkInterfaces": [
        {
          "network": "default",
          "ipAddress": "10.x.x.x",
          "ipAddressAliases": [
            "151.x.x.x"
          ],
          "gateway": "10.x.x.x"
        }
      ],
      "resources": {
        "limits": {
          "cpu": "1",
          "memory": "2Gi",
          "ephemeral-storage": "5Gi"
        }
      },
      "containerStatuses": [],
      "reason": "",
      "message": ""
    },
    {
      "stackId": "9sample6-51d1-4377-b019-e01f65810804",
      "id": "fsample0-2f40-11e9-9bab-002590ec105c",
      "name": "test-workload-europe-fra-0",
      "location": {
        "city": "Frankfurt",
        "cityCode": "FRA",
        "subdivision": "Hessen",
        "subdivisionCode": "HE",
        "country": "Germany",
        "countryCode": "DE",
        "continent": "Europe",
        "latitude": 50.110924,
        "longitude": 8.682127
      },
      "phase": "STARTING",
      "ipAddress": "10.x.x.x",
      "externalIpAddress": "151.x.x.x",
      "createdAt": "2019-02-13T03:39:38Z",
      "networkInterfaces": [
        {
          "network": "default",
          "ipAddress": "10.x.x.x",
          "ipAddressAliases": [
            "151.x.x.x"
          ],
          "gateway": "10.x.x.x"
        }
      ],
      "resources": {
        "limits": {
          "cpu": "1",
          "memory": "2Gi",
          "ephemeral-storage": "5Gi"
        }
      },
      "containerStatuses": [],
      "reason": "",
      "message": ""
    }
  ]
}

Related documentation

To view all workload-related API calls, see Workloads.

Updated about a month ago

Create a Container Workload


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.