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.
Before you begin, consider the following statements:
- To use this document, you must have an existing Stack.
- StackPath supports any OCI compatible image (Docker v2, etc). To learn more, see Container image formats.
- Each PoP in StackPath has been assigned with a 64-bit ranged address. Any StackPath customer can use 64-bits for host addressing.
- When you create a workload, the API does not require SSH keys.
- You cannot update an existing instance to add SSH keys.
Understand the request
To create a workload, there are three types of specifications to configure.
- Use
containersto define container specifications. - Use
resourcesto define the amount of CPUs and memory for each container of your workload. - Use
targetsto 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
-
Provisions an anycast IP with the workload, shared across all containers in the workload.
-
Possesses a network interface that has Dual-Stack (IPv4/IPv6) capabilities.
-
Dual-Stack (IPv4/IPv6) allows your Workload to provide both IPv4 and IPv6 support to your users around the globe in parallel. If you do not configure the Dual-Stack (IPv4/IPv6) option, then IPv4 will be used by default. If you need to change between IPv4 and Dual-Stack (IPv4/IPv6), you will have to recreate your Workload.
-
The Dual-Stack (IPv4/IPv6) parameter is a string type (
ipFamilies).
-
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.
- To learn more, see Get 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",
"ipFamilies": ["IPv4", "IPv6"]
}
],
"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",
"ipFamilies": ["IPv4", "IPv6"]
}
],
"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",
"ipFamilies": [
"IPv4",
"IPv6"
],
"subnet": "",
"ipv6 Subnet": "",
"enableOneToOneNat": true
],
}
],
"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 8 months ago
