AWS Provisioner API Documentation


BaseUrl
https://aws-provisioner.taskcluster.net/v1

The AWS Provisioner is responsible for provisioning instances on EC2 for use in Taskcluster. The provisioner maintains a set of worker configurations which can be managed with an API that is typically available at aws-provisioner.taskcluster.net/v1. This API can also perform basic instance management tasks in addition to maintaining the internal state of worker type configuration information.

The Provisioner runs at a configurable interval. Each iteration of the provisioner fetches a current copy the state that the AWS EC2 api reports. In each iteration, we ask the Queue how many tasks are pending for that worker type. Based on the number of tasks pending and the scaling ratio, we may submit requests for new instances. We use pricing information, capacity and utility factor information to decide which instance type in which region would be the optimal configuration.

Each EC2 instance type will declare a capacity and utility factor. Capacity is the number of tasks that a given machine is capable of running concurrently. Utility factor is a relative measure of performance between two instance types. We multiply the utility factor by the spot price to compare instance types and regions when making the bidding choices.

When a new EC2 instance is instantiated, its user data contains a token in securityToken that can be used with the getSecret method to retrieve the worker's credentials and any needed passwords or other restricted information. The worker is responsible for deleting the secret after retrieving it, to prevent dissemination of the secret to other proceses which can read the instance user data.

Functions

For more information on invoking the API methods described here, see Using the APIs in the manual.
SignatureSummary
listWorkerTypeSummaries() : resultList worker types with details
createWorkerType(workerType, payload) : resultCreate new Worker Type
updateWorkerType(workerType, payload) : resultUpdate Worker Type
workerTypeLastModified(workerType) : resultGet Worker Type Last Modified Time
workerType(workerType) : resultGet Worker Type
removeWorkerType(workerType) : voidDelete Worker Type
listWorkerTypes() : resultList Worker Types
createSecret(token, payload) : voidCreate new Secret
getSecret(token) : resultGet a Secret
instanceStarted(instanceId, token) : voidReport an instance starting
removeSecret(token) : voidRemove a Secret
getLaunchSpecs(workerType) : resultGet All Launch Specifications for WorkerType
state(workerType) : voidGet AWS State for a worker type
backendStatus() : resultBackend Status
ping() : voidPing Server

List worker types with details

Method
get
Route
/list-worker-type-summaries
Signature
listWorkerTypeSummaries() : result
Stability
stable

Return a list of worker types, including some summary information about current capacity for each. While this list includes all defined worker types, there may be running EC2 instances for deleted worker types that are not included here. The list is unordered.

Response

List Worker Type Summaries Response (source)

Array of

List Worker Type Summaries Response

workerTypestring

Worker type name

minCapacityinteger

Minimum capacity of the workerType

maxCapacityinteger

Maximum capacity of the workerType

requestedCapacityinteger

Total requested capacity

pendingCapacityinteger

Total pending capacity

runningCapacityinteger

Total running capacity



Create new Worker Type

Method
put
Route
/worker-type/<workerType>
Scopes
aws-provisioner:manage-worker-type:<workerType>
Signature
createWorkerType(workerType, payload) : result
Stability
stable

Create a worker type. A worker type contains all the configuration needed for the provisioner to manage the instances. Each worker type knows which regions and which instance types are allowed for that worker type. Remember that Capacity is the number of concurrent tasks that can be run on a given EC2 resource and that Utility is the relative performance rate between different instance types. There is no way to configure different regions to have different sets of instance types so ensure that all instance types are available in all regions. This function is idempotent.

Once a worker type is in the provisioner, a back ground process will begin creating instances for it based on its capacity bounds and its pending task count from the Queue. It is the worker's responsibility to shut itself down. The provisioner has a limit (currently 96hours) for all instances to prevent zombie instances from running indefinitely.

The provisioner will ensure that all instances created are tagged with aws resource tags containing the provisioner id and the worker type.

If provided, the secrets in the global, region and instance type sections are available using the secrets api. If specified, the scopes provided will be used to generate a set of temporary credentials available with the other secrets.

Request Payload

Create Worker Type Request (source)

A worker launchSpecification and required metadata

launchSpecObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
descriptionstring

A string which describes what this image is for and hints on using it

ownerstring

A string which identifies the owner of this worker type

secretsObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
userDataObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes to issue credentials to for all regions Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
minCapacitynumber

Minimum number of capacity units to be provisioned. A capacity unit is an abstract unit of capacity, where one capacity unit is roughly one task which should be taken off the queue

maxCapacitynumber

Maximum number of capacity units to be provisioned.

scalingRationumber

A scaling ratio of 0.2 means that the provisioner will attempt to keep the number of pending tasks around 20% of the provisioned capacity. This results in pending tasks waiting 20% of the average task execution time before starting to run. A higher scaling ratio often results in better utilization and longer waiting times. For workerTypes running long tasks a short scaling ratio may be preferred, but for workerTypes running quick tasks a higher scaling ratio may increase utilization without major delays. If using a scaling ratio of 0, the provisioner will attempt to keep the capacity of pending spot requests equal to the number of pending tasks.

minPricenumber

Minimum price to pay for an instance. A Price is considered to be the Amazon Spot Price multiplied by the utility factor of the InstantType as specified in the instanceTypes list. For example, if the minPrice is set to $0.5 and the utility factor is 2, the actual minimum bid used will be $0.25

maxPricenumber

Maximum price we'll pay. Like minPrice, this takes into account the utility factor when figuring out what the actual SpotPrice submitted to Amazon will be

canUseOndemandboolean

True if this worker type is allowed on demand instances. Currently ignored

canUseSpotboolean

True if this worker type is allowed spot instances. Currently ignored as all instances are Spot

instanceTypesArray of
instanceTypestring

InstanceType name for Amazon.

capacitynumber

This number represents the number of tasks that this instance type is capable of running concurrently. This is used by the provisioner to know how many pending tasks to offset a pending instance of this type by

utilitynumber

This number is a relative measure of performance between two instance types. It is multiplied by the spot price from Amazon to figure out which instance type is the cheapest one

launchSpecObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this InstanceType. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
regionsArray of
regionstring
  • us-west-2
  • us-east-1
  • us-east-2
  • us-west-1
  • eu-central-1

The Amazon AWS Region being configured. Example: us-west-1

launchSpecObject of

Region configuration

ImageIdstring

Per-region AMI ImageId

secretsObject of

Region configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Region configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this Region. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
availabilityZonesArray of
availabilityZonestring

The AWS availability zone being configured. Example: eu-central-1b

regionstring

The AWS region containing this availability zone. Example: eu-central-1

launchSpecObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯

Response

Get Worker Type Response (source)

A worker launchSpecification and required metadata

workerTypestring^[A-Za-z0-9+/=_-]{1,22}$

The ID of the workerType

launchSpecObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
descriptionstring

A string which describes what this image is for and hints on using it

ownerstring

A string which identifies the owner of this worker type

secretsObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
userDataObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes to issue credentials to for all regions. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
minCapacitynumber

Minimum number of capacity units to be provisioned. A capacity unit is an abstract unit of capacity, where one capacity unit is roughly one task which should be taken off the queue

maxCapacitynumber

Maximum number of capacity units to be provisioned.

scalingRationumber

A scaling ratio of 0.2 means that the provisioner will attempt to keep the number of pending tasks around 20% of the provisioned capacity. This results in pending tasks waiting 20% of the average task execution time before starting to run. A higher scaling ratio often results in better utilization and longer waiting times. For workerTypes running long tasks a short scaling ratio may be preferred, but for workerTypes running quick tasks a higher scaling ratio may increase utilization without major delays. If using a scaling ratio of 0, the provisioner will attempt to keep the capacity of pending spot requests equal to the number of pending tasks.

minPricenumber

Minimum price to pay for an instance. A Price is considered to be the Amazon Spot Price multiplied by the utility factor of the InstantType as specified in the instanceTypes list. For example, if the minPrice is set to $0.5 and the utility factor is 2, the actual minimum bid used will be $0.25

maxPricenumber

Maximum price we'll pay. Like minPrice, this takes into account the utility factor when figuring out what the actual SpotPrice submitted to Amazon will be

canUseOndemandboolean

True if this worker type is allowed on demand instances. Currently ignored

canUseSpotboolean

True if this worker type is allowed spot instances. Currently ignored as all instances are Spot

lastModifiedstringdate-time

ISO Date string (e.g. new Date().toISOString()) which represents the time when this worker type definition was last altered (inclusive of creation)

instanceTypesArray of
instanceTypestring

InstanceType name for Amazon.

capacitynumber

This number represents the number of tasks that this instance type is capable of running concurrently. This is used by the provisioner to know how many pending tasks to offset a pending instance of this type by

utilitynumber

This number is a relative measure of performance between two instance types. It is multiplied by the spot price from Amazon to figure out which instance type is the cheapest one

launchSpecObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this InstanceType. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
regionsArray of
regionstring

The Amazon AWS Region being configured. Example: us-west-1

launchSpecObject of

Region configuration

ImageIdstring

Per-region AMI ImageId

secretsObject of

Region configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Region configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this Region. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
availabilityZonesArray of
availabilityZonestring

The AWS availability zone being configured. Example: eu-central-1b

regionstring

The AWS region containing this availability zone. Example: eu-central-1

launchSpecObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯


Update Worker Type

Method
post
Route
/worker-type/<workerType>/update
Scopes
aws-provisioner:manage-worker-type:<workerType>
Signature
updateWorkerType(workerType, payload) : result
Stability
stable

Provide a new copy of a worker type to replace the existing one. This will overwrite the existing worker type definition if there is already a worker type of that name. This method will return a 200 response along with a copy of the worker type definition created Note that if you are using the result of a GET on the worker-type end point that you will need to delete the lastModified and workerType keys from the object returned, since those fields are not allowed the request body for this method

Otherwise, all input requirements and actions are the same as the create method.

Request Payload

Create Worker Type Request (source)

A worker launchSpecification and required metadata

launchSpecObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
descriptionstring

A string which describes what this image is for and hints on using it

ownerstring

A string which identifies the owner of this worker type

secretsObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
userDataObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes to issue credentials to for all regions Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
minCapacitynumber

Minimum number of capacity units to be provisioned. A capacity unit is an abstract unit of capacity, where one capacity unit is roughly one task which should be taken off the queue

maxCapacitynumber

Maximum number of capacity units to be provisioned.

scalingRationumber

A scaling ratio of 0.2 means that the provisioner will attempt to keep the number of pending tasks around 20% of the provisioned capacity. This results in pending tasks waiting 20% of the average task execution time before starting to run. A higher scaling ratio often results in better utilization and longer waiting times. For workerTypes running long tasks a short scaling ratio may be preferred, but for workerTypes running quick tasks a higher scaling ratio may increase utilization without major delays. If using a scaling ratio of 0, the provisioner will attempt to keep the capacity of pending spot requests equal to the number of pending tasks.

minPricenumber

Minimum price to pay for an instance. A Price is considered to be the Amazon Spot Price multiplied by the utility factor of the InstantType as specified in the instanceTypes list. For example, if the minPrice is set to $0.5 and the utility factor is 2, the actual minimum bid used will be $0.25

maxPricenumber

Maximum price we'll pay. Like minPrice, this takes into account the utility factor when figuring out what the actual SpotPrice submitted to Amazon will be

canUseOndemandboolean

True if this worker type is allowed on demand instances. Currently ignored

canUseSpotboolean

True if this worker type is allowed spot instances. Currently ignored as all instances are Spot

instanceTypesArray of
instanceTypestring

InstanceType name for Amazon.

capacitynumber

This number represents the number of tasks that this instance type is capable of running concurrently. This is used by the provisioner to know how many pending tasks to offset a pending instance of this type by

utilitynumber

This number is a relative measure of performance between two instance types. It is multiplied by the spot price from Amazon to figure out which instance type is the cheapest one

launchSpecObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this InstanceType. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
regionsArray of
regionstring
  • us-west-2
  • us-east-1
  • us-east-2
  • us-west-1
  • eu-central-1

The Amazon AWS Region being configured. Example: us-west-1

launchSpecObject of

Region configuration

ImageIdstring

Per-region AMI ImageId

secretsObject of

Region configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Region configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this Region. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
availabilityZonesArray of
availabilityZonestring

The AWS availability zone being configured. Example: eu-central-1b

regionstring

The AWS region containing this availability zone. Example: eu-central-1

launchSpecObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯

Response

Get Worker Type Response (source)

A worker launchSpecification and required metadata

workerTypestring^[A-Za-z0-9+/=_-]{1,22}$

The ID of the workerType

launchSpecObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
descriptionstring

A string which describes what this image is for and hints on using it

ownerstring

A string which identifies the owner of this worker type

secretsObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
userDataObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes to issue credentials to for all regions. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
minCapacitynumber

Minimum number of capacity units to be provisioned. A capacity unit is an abstract unit of capacity, where one capacity unit is roughly one task which should be taken off the queue

maxCapacitynumber

Maximum number of capacity units to be provisioned.

scalingRationumber

A scaling ratio of 0.2 means that the provisioner will attempt to keep the number of pending tasks around 20% of the provisioned capacity. This results in pending tasks waiting 20% of the average task execution time before starting to run. A higher scaling ratio often results in better utilization and longer waiting times. For workerTypes running long tasks a short scaling ratio may be preferred, but for workerTypes running quick tasks a higher scaling ratio may increase utilization without major delays. If using a scaling ratio of 0, the provisioner will attempt to keep the capacity of pending spot requests equal to the number of pending tasks.

minPricenumber

Minimum price to pay for an instance. A Price is considered to be the Amazon Spot Price multiplied by the utility factor of the InstantType as specified in the instanceTypes list. For example, if the minPrice is set to $0.5 and the utility factor is 2, the actual minimum bid used will be $0.25

maxPricenumber

Maximum price we'll pay. Like minPrice, this takes into account the utility factor when figuring out what the actual SpotPrice submitted to Amazon will be

canUseOndemandboolean

True if this worker type is allowed on demand instances. Currently ignored

canUseSpotboolean

True if this worker type is allowed spot instances. Currently ignored as all instances are Spot

lastModifiedstringdate-time

ISO Date string (e.g. new Date().toISOString()) which represents the time when this worker type definition was last altered (inclusive of creation)

instanceTypesArray of
instanceTypestring

InstanceType name for Amazon.

capacitynumber

This number represents the number of tasks that this instance type is capable of running concurrently. This is used by the provisioner to know how many pending tasks to offset a pending instance of this type by

utilitynumber

This number is a relative measure of performance between two instance types. It is multiplied by the spot price from Amazon to figure out which instance type is the cheapest one

launchSpecObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this InstanceType. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
regionsArray of
regionstring

The Amazon AWS Region being configured. Example: us-west-1

launchSpecObject of

Region configuration

ImageIdstring

Per-region AMI ImageId

secretsObject of

Region configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Region configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this Region. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
availabilityZonesArray of
availabilityZonestring

The AWS availability zone being configured. Example: eu-central-1b

regionstring

The AWS region containing this availability zone. Example: eu-central-1

launchSpecObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯


Get Worker Type Last Modified Time

Method
get
Route
/worker-type-last-modified/<workerType>
Signature
workerTypeLastModified(workerType) : result
Stability
stable

This method is provided to allow workers to see when they were last modified. The value provided through UserData can be compared against this value to see if changes have been made If the worker type definition has not been changed, the date should be identical as it is the same stored value.

Response

Get Worker Type Response (source)

Get the last modified date of a workerType

workerTypestring^[A-Za-z0-9+/=_-]{1,22}$

The ID of the workerType

lastModifiedstringdate-time

ISO Date string (e.g. new Date().toISOString()) which represents the time when this worker type definition was last altered (inclusive of creation)



Get Worker Type

Method
get
Route
/worker-type/<workerType>
Scopes
aws-provisioner:view-worker-type:<workerType>
or
aws-provisioner:manage-worker-type:<workerType>
Signature
workerType(workerType) : result
Stability
stable

Retrieve a copy of the requested worker type definition. This copy contains a lastModified field as well as the worker type name. As such, it will require manipulation to be able to use the results of this method to submit date to the update method.

Response

Get Worker Type Response (source)

A worker launchSpecification and required metadata

workerTypestring^[A-Za-z0-9+/=_-]{1,22}$

The ID of the workerType

launchSpecObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
descriptionstring

A string which describes what this image is for and hints on using it

ownerstring

A string which identifies the owner of this worker type

secretsObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
userDataObject of

A worker launchSpecification and required metadata

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes to issue credentials to for all regions. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
minCapacitynumber

Minimum number of capacity units to be provisioned. A capacity unit is an abstract unit of capacity, where one capacity unit is roughly one task which should be taken off the queue

maxCapacitynumber

Maximum number of capacity units to be provisioned.

scalingRationumber

A scaling ratio of 0.2 means that the provisioner will attempt to keep the number of pending tasks around 20% of the provisioned capacity. This results in pending tasks waiting 20% of the average task execution time before starting to run. A higher scaling ratio often results in better utilization and longer waiting times. For workerTypes running long tasks a short scaling ratio may be preferred, but for workerTypes running quick tasks a higher scaling ratio may increase utilization without major delays. If using a scaling ratio of 0, the provisioner will attempt to keep the capacity of pending spot requests equal to the number of pending tasks.

minPricenumber

Minimum price to pay for an instance. A Price is considered to be the Amazon Spot Price multiplied by the utility factor of the InstantType as specified in the instanceTypes list. For example, if the minPrice is set to $0.5 and the utility factor is 2, the actual minimum bid used will be $0.25

maxPricenumber

Maximum price we'll pay. Like minPrice, this takes into account the utility factor when figuring out what the actual SpotPrice submitted to Amazon will be

canUseOndemandboolean

True if this worker type is allowed on demand instances. Currently ignored

canUseSpotboolean

True if this worker type is allowed spot instances. Currently ignored as all instances are Spot

lastModifiedstringdate-time

ISO Date string (e.g. new Date().toISOString()) which represents the time when this worker type definition was last altered (inclusive of creation)

instanceTypesArray of
instanceTypestring

InstanceType name for Amazon.

capacitynumber

This number represents the number of tasks that this instance type is capable of running concurrently. This is used by the provisioner to know how many pending tasks to offset a pending instance of this type by

utilitynumber

This number is a relative measure of performance between two instance types. It is multiplied by the spot price from Amazon to figure out which instance type is the cheapest one

launchSpecObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Instance Type configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this InstanceType. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
regionsArray of
regionstring

The Amazon AWS Region being configured. Example: us-west-1

launchSpecObject of

Region configuration

ImageIdstring

Per-region AMI ImageId

secretsObject of

Region configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Region configuration

Anything ¯\_(ツ)_/¯
scopesArray of

Scopes which should be included for this Region. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
availabilityZonesArray of
availabilityZonestring

The AWS availability zone being configured. Example: eu-central-1b

regionstring

The AWS region containing this availability zone. Example: eu-central-1

launchSpecObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
secretsObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯
userDataObject of

Availability zone configuration

Anything ¯\_(ツ)_/¯


Delete Worker Type

Method
delete
Route
/worker-type/<workerType>
Scopes
aws-provisioner:manage-worker-type:<workerType>
Signature
removeWorkerType(workerType) : void
Stability
stable

Delete a worker type definition. This method will only delete the worker type definition from the storage table. The actual deletion will be handled by a background worker. As soon as this method is called for a worker type, the background worker will immediately submit requests to cancel all spot requests for this worker type as well as killing all instances regardless of their state. If you want to gracefully remove a worker type, you must either ensure that no tasks are created with that worker type name or you could theoretically set maxCapacity to 0, though, this is not a supported or tested action



List Worker Types

Method
get
Route
/list-worker-types
Signature
listWorkerTypes() : result
Stability
stable

Return a list of string worker type names. These are the names of all managed worker types known to the provisioner. This does not include worker types which are left overs from a deleted worker type definition but are still running in AWS.

Response

List Worker Types (source)

Array of

List Worker Types

string


Create new Secret

Method
put
Route
/secret/<token>
Scopes
aws-provisioner:create-secret:<workerType>
Signature
createSecret(token, payload) : void
Stability
stable

Insert a secret into the secret storage. The supplied secrets will be provided verbatime via getSecret, while the supplied scopes will be converted into credentials by getSecret.

This method is not ordinarily used in production; instead, the provisioner creates a new secret directly for each spot bid.

Request Payload

Get Secret Request (source)

A Secret

workerTypestring

A string describing what the secret will be used for

secretsObject of

A Secret

Anything ¯\_(ツ)_/¯
scopesArray of

List of strings which are scopes for temporary credentials to give to the worker through the secret system. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
tokenstring

A Slug ID which is the uniquely addressable token to access this set of secrets

expirationstringdate-time

The date at which the secret is no longer guaranteed to exist



Get a Secret

Method
get
Route
/secret/<token>
Signature
getSecret(token) : result
Stability
stable

Retrieve a secret from storage. The result contains any passwords or other restricted information verbatim as well as a temporary credential based on the scopes specified when the secret was created.

It is important that this secret is deleted by the consumer (removeSecret), or else the secrets will be visible to any process which can access the user data associated with the instance.

Response

Get Secret Response (source)

Secrets from the provisioner

dataObject of

Secrets from the provisioner

Anything ¯\_(ツ)_/¯
credentialsObject of

Secrets from the provisioner

clientIdstring
accessTokenstring
certificatestring


Report an instance starting

Method
get
Route
/instance-started/<instanceId>/<token>
Signature
instanceStarted(instanceId, token) : void
Stability
stable

An instance will report in by giving its instance id as well as its security token. The token is given and checked to ensure that it matches a real token that exists to ensure that random machines do not check in. We could generate a different token but that seems like overkill



Remove a Secret

Method
delete
Route
/secret/<token>
Signature
removeSecret(token) : void
Stability
stable

Remove a secret. After this call, a call to getSecret with the given token will return no information.

It is very important that the consumer of a secret delete the secret from storage before handing over control to untrusted processes to prevent credential and/or secret leakage.



Get All Launch Specifications for WorkerType

(experimental)

Method
get
Route
/worker-type/<workerType>/launch-specifications
Scopes
aws-provisioner:view-worker-type:<workerType>
or
aws-provisioner:manage-worker-type:<workerType>
Signature
getLaunchSpecs(workerType) : result
Stability
experimental

This method returns a preview of all possible launch specifications that this worker type definition could submit to EC2. It is used to test worker types, nothing more

This API end-point is experimental and may be subject to change without warning.

Response

Get All Launch Specs Response (source)

All of the launch specifications for a worker type

Anything ¯\_(ツ)_/¯


Get AWS State for a worker type

Method
get
Route
/state/<workerType>
Signature
state(workerType) : void
Stability
stable

Return the state of a given workertype as stored by the provisioner. This state is stored as three lists: 1 for running instances, 1 for pending requests. The summary property contains an updated summary similar to that returned from listWorkerTypeSummaries.



Backend Status

(experimental)

Method
get
Route
/backend-status
Signature
backendStatus() : result
Stability
experimental

This endpoint is used to show when the last time the provisioner has checked in. A check in is done through the deadman's snitch api. It is done at the conclusion of a provisioning iteration and used to tell if the background provisioning process is still running.

Warning this api end-point is not stable.

Response

Backend Status Response (source)

Backend Status Response

statusstring

A string from Deadman's Snitch which describes the status. See https://deadmanssnitch.com/docs/api/v1#listing-your-snitches for an explanation of this value

lastCheckedInstringdate-time

A date when the provisioner backend process last completed an iteration. This does not imply success, rather it is to make sure that the process is alive



Ping Server

Method
get
Route
/ping
Signature
ping() : void
Stability
stable

Respond without doing anything. This endpoint is used to check that the service is up.