The StackPath Developer Portal

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

Get Started    API Reference

Create a Container Workload

This guide describes the process of creating a computing workload with containers using the API. At this point a stack should already be created and workloads need to be enabled on the stack. We support any OCI compatible image (Docker v2, etc).

Create a Workload

More details on what the API expects can be found here within the API documentation for workloads. The call to create a workload requires a name as well as spec. The specification describes what to deploy, and where. In the spec:

  • containers : Defines what container specification you want to use.
  • resources : How many CPUs and how much memory you want on each container of your workload.
  • targets : Where you want your containers to run and how many you want to run in each location.

In this example, a workload is created running nginx with a single instance each in four cities: Dallas, Chicago, Frankfurt and Amsterdam. This example also provisions an anycast IP with the workload, shared across all containers in the workload. IATA airport codes are used to define the value of the city code. A full list of supported cities can be found by quering our 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"
    }
}'

This request will return a JSON object that looks something like this:

{
  "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"
  }
}

The ID in the above JSON object is your new workload ID. It is represented by WORKLOAD_ID below. Getting all the instanced tied to this workflow is easy.

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"

This request will return a JSON object that looks something like this and contains all the details you need to know about your workflow:

  • How many container instances were created in total
  • The status of each instance (Starting, Running, etc)
  • The cities each instance is in
  • The private and public IP of each instance as well as the gateway IP.
{
  "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": ""
    }
  ]
}

If you have a request, comment, or just want to say hi please send an email. If you need immediate assistance our 24/7 support is here to help.

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.