Operations

Get cluster nodes

GET /clusters/{cluster}/nodes

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to query	string
Query	operation optional	If given, returns only the nodes for this operation id, and includes the operation attribute on the body	string
Query	request_id optional	If given, returns only the nodes for the operation identified by this request id, and includes the operation attribute on the body	string

Responses

HTTP Code	Description	Schema
200	OK	NodeList
400	Invalid specification	No Content
404	Not found	No Content

Example HTTP request

Request path

/clusters/CLUSTER_NAME/nodes

Example HTTP response

Response 200

{
  "nodes" : [ { } ],
  "operation" : {
    "action" : "string",
    "startTime" : "2020-01-01T12:34:56Z"
  }
}

Create cluster nodes

POST /clusters/{cluster}/nodes/create

Description

This operation adds new nodes from a nodearray to a cluster. It accepts multiple node definitions in a single call. It returns the URL to the operation that can be used to track the status of the operation.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to add nodes to	string
Body	nodes required	Sets of nodes to be created	NodeCreationRequest

Responses

HTTP Code	Description	Schema
202	Accepted Headers : Location (string) : The URL for the operation.	NodeCreationResult
409	Invalid input	No Content

Example HTTP request

Request path

/clusters/CLUSTER_NAME/nodes/create

Request body

{
  "requestId" : "00000000-0000-0000-0000-000000000000",
  "sets" : [ "object" ]
}

Example HTTP response

Response 202

{
  "operationId" : "00000000-0000-0000-0000-000000000000",
  "sets" : [ "object" ]
}

Deallocate cluster nodes

POST /clusters/{cluster}/nodes/deallocate

Description

This operation deallocates nodes in a cluster. The nodes can be identified in several ways, including node name, node id, or by filter.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to deallocate nodes in	string
Body	action required	Description of which nodes to deallocate	NodeManagementRequest

Responses

HTTP Code	Description	Schema
202	Accepted Headers : Location (string) : The URL for the operation.	NodeManagementResult
409	Invalid input	No Content

Example HTTP request

Request path

/clusters/CLUSTER_NAME/nodes/deallocate

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

Example HTTP response

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

Terminate and remove cluster nodes

POST /clusters/{cluster}/nodes/remove

Description

This operation removes nodes in a cluster. The nodes can be identified in several ways, including node name, node id, or by filter. Note that by default nodes are removed when terminated (unless the node has Fixed set to true), in which case this call is no different than terminate.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to remove nodes in	string
Body	action required	Description of which nodes to remove	NodeManagementRequest

Responses

HTTP Code	Description	Schema
202	Accepted Headers : Location (string) : The URL for the operation.	NodeManagementResult
409	Invalid input	No Content

Example HTTP request

Request path

/clusters/CLUSTER_NAME/nodes/remove

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

Example HTTP response

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

Terminate or deallocate cluster nodes

POST /clusters/{cluster}/nodes/shutdown

Description

This operation terminates or deallocates nodes in a cluster, depending on whether the ShutdownPolicy attribute on each node is Terminate (the default) or Deallocate, respectively.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to shutdown nodes in	string
Body	action required	Description of which nodes to shutdown	NodeManagementRequest

Responses

HTTP Code	Description	Schema
202	Accepted Headers : Location (string) : The URL for the operation.	NodeManagementResult
409	Invalid input	No Content

Example HTTP request

Request path

/clusters/CLUSTER_NAME/nodes/shutdown

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

Example HTTP response

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

Start deallocated or terminated cluster nodes

POST /clusters/{cluster}/nodes/start

Description

This operation starts nodes in a cluster. The nodes can be identified in several ways, including node name, node id, or by filter.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to start nodes in	string
Body	action required	Description of which nodes to start	NodeManagementRequest

Responses

HTTP Code	Description	Schema
202	Accepted Headers : Location (string) : The URL for the operation.	NodeManagementResult
409	Invalid input	No Content

Example HTTP request

Request path

/clusters/CLUSTER_NAME/nodes/start

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

Example HTTP response

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

Terminate cluster nodes

POST /clusters/{cluster}/nodes/terminate

Description

This operation terminates nodes in a cluster. The nodes can be identified in several ways, including node name, node id, or by filter.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to terminate nodes in	string
Body	action required	Description of which nodes to terminate	NodeManagementRequest

Responses

HTTP Code	Description	Schema
202	Accepted Headers : Location (string) : The URL for the operation.	NodeManagementResult
409	Invalid input	No Content

Example HTTP request

Request path

/clusters/CLUSTER_NAME/nodes/terminate

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

Example HTTP response

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

Scale cluster to size

POST /clusters/{cluster}/scale/{nodearray}

Description

This operation adds nodes as needed to a nodearray to hit a total count. The request is processed one time, and does not re-add nodes later to maintain the given number. This scales by either total cores or total nodes, but not both. It returns the URL to the operation that can be used to track the status of the operation.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to add nodes to	string
Path	nodearray required	The nodearray to add nodes to	string
Query	totalCoreCount optional	The total number of cores to have in this nodearray, including nodes already created	integer
Query	totalNodeCount optional	The total number of machines to have in this nodearray, including nodes already created	integer

Responses

HTTP Code	Description	Schema
202	Accepted Headers : Location (string) : The URL for the operation.	NodeCreationResult
409	Invalid input	No Content

Example HTTP request

Request path

/clusters/CLUSTER_NAME/scale/NODEARRAY_NAME

Example HTTP response

Response 202

{
  "operationId" : "00000000-0000-0000-0000-000000000000",
  "sets" : [ "object" ]
}

Get cluster status

GET /clusters/{cluster}/status

Description

This operation contains information for the nodes and nodearrays in a given cluster. For each nodearray, it returns the status of each "bucket" of allocation that can be used, such as how many nodes are in the bucket, how many more can be added, etc. Each bucket is a set of possible VMs of a given hardware profile, that can be created in a given location, under a given customer account, etc. The valid buckets for a nodearray are determined by the user's cluster definition, but the limits are determined in part by the cloud provider.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to query	string
Query	nodes optional	If true, nodes and node references are returned in the response	boolean

Responses

HTTP Code	Description	Schema
200	OK	ClusterStatus

Example HTTP request

Request path

/clusters/CLUSTER_NAME/status

Example HTTP response

Response 200

{
  "maxCoreCount" : 16,
  "maxCount" : 4,
  "nodearrays" : [ "object" ],
  "nodes" : [ { } ],
  "state" : "Starting",
  "targetState" : "Started"
}

Get usage and optional cost information for a cluster

GET /clusters/{cluster}/usage

Description

This operation returns overall usage data (core hours) and cost data, if available, for the cluster, as well as a per-nodearray breakdown. By default it returns the current month's worth of usage.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to return usage data for	string
Query	timeframe optional	If given, this specifies the time range to use for the query. monthToDate returns the usage for the current month, and lastMonth returns the usage for the previous month. weekToDate returns the usage for the current week (starting Sunday). custom requires to 'from' and 'to' query parameters. The default is MonthToDate. All times are in UTC.	enum (monthToDate, lastMonth, weekToDate, custom)
Query	from optional	For custom timeframes, this is the start of the timeframe in ISO-8601 format. This is rounded down to the nearest hour or day.	string
Query	to optional	For custom timeframes, this is the end of the timeframe in ISO-8601 format. This is rounded up to the nearest hour or day.	string
Query	granularity optional	Specifies how to aggregate data: by hour, by daily, or as a single number. This default is daily.	enum (total, daily, hourly)

Responses

HTTP Code	Description	Schema
200	OK	ClusterUsage

Example HTTP request

Request path

/clusters/CLUSTER_NAME/usage

Example HTTP response

Response 200

{
  "usage" : [ "object" ]
}

Lists the status of operations

GET /operations/

Parameters

Type	Name	Description	Schema
Query	request_id optional	The request ID for the operation. If this is given, the list will only have 0 or 1 element in it.	string

Responses

HTTP Code	Description	Schema
200	OK	< OperationStatus > array
400	Invalid request	No Content
404	Not found	No Content

Example HTTP request

Request path

/operations/

Example HTTP response

Response 200

[ {
  "action" : "string",
  "startTime" : "2020-01-01T12:34:56Z"
} ]

Gets operation status by id

GET /operations/{id}

Parameters

Type	Name	Description	Schema
Path	id required	The operation ID	string

Responses

HTTP Code	Description	Schema
200	OK	OperationStatus
404	Not found	No Content

Example HTTP request

Request path

/operations/00000000-0000-0000-0000-000000000000

Example HTTP response

Response 200

{
  "action" : "string",
  "startTime" : "2020-01-01T12:34:56Z"
}

Resources

ClusterStatus

Status of the cluster

Name	Description	Schema
maxCoreCount required	The maximum number of cores that may be added to this cluster Example : 16	integer
maxCount required	The maximum number of nodes that may be added to this cluster Example : 4	integer
nodearrays required	Example : [ "object" ]	< nodearrays > array
nodes optional	An optional list of nodes in this cluster, only included if nodes=true is in the query Example : [ "[node](#node)" ]	< Node > array
state optional	The current state of the cluster, if it has been started at least once Example : "Starting"	string
targetState optional	The desired state of the cluster (eg Started or Terminated) Example : "Started"	string

nodearrays

Name	Description	Schema
buckets required	Each bucket of allocation for this nodearray. The "core count" settings are always a multiple of the core count for this bucket. Example : [ "object" ]	< buckets > array
maxCoreCount required	The maximum number of cores that may be in this nodearray Example : 16	integer
maxCount required	The maximum number of nodes that may be in this nodearray Example : 4	integer
name required	The nodearray this is describing Example : "execute"	string
nodearray required	The attributes of this nodearray Example : "[node](#node)"	Node

buckets

Name	Description	Schema
activeCoreCount required	The number of cores in use for this bucket, in this nodearray Example : 40	integer
activeCount required	The number of nodes in use for this bucket, in this nodearray. This includes nodes which are still acquiring a VM. Example : 10	integer
activeNodes optional	The node names in use for this bucket, in this nodearray. This includes nodes which are still acquiring a VM. This is only included if nodes=true is in the query. Example : [ "string" ]	< string > array
availableCoreCount required	How many extra cores may be created in this bucket, in this nodearray. Always a multiple of availableCount. Example : 8	integer
availableCount required	How many extra nodes may be created in this bucket, in this nodearray. Note this may be less than implied by maxCount and usedCount, since maxCount may be limited globally. Example : 2	integer
bucketId required	The identifier for this bucket. This will always have the same value for a given bucket in a nodearray, as long as the cluster is not deleted. Example : "00000000-0000-0000-0000-000000000000"	string
consumedCoreCount required	The number of cores for this family that are already in use across the entire region. Example : 2	integer
definition optional	The properties of this bucket, used to create nodes from this bucket. The create-nodes API takes this definition in its bucket property. Example : "object"	definition
familyConsumedCoreCount optional	The number of cores for this family that are already in use across the entire region. Example : 2	integer
familyQuotaCoreCount optional	The number of total cores that can be started for this family in this region. This might not be an integer multiple of quotaCount. Example : 16	integer
familyQuotaCount optional	The number of total instances that can be started (given familyQuotaCoreCount) Example : 4	integer
invalidReason required	If valid is false, this will contain the reason the bucket is invalid. Currently NotActivated and DisabledMachineType are the only reasons. Example : "DisabledMachineType"	string
lastCapacityFailure required	How long, in seconds, since the last time this bucket experienced a capacity failure. Any negative value is treated as never. Example : 180.0	number
maxCoreCount required	The maximum number of cores that may be in this bucket, including global and nodearray limits. Always a multiple of maxCount. Example : 16	integer
maxCount required	The maximum number of nodes that may be in this bucket, including global and nodearray limits Example : 4	integer
maxPlacementGroupCoreSize required	The maximum total number of cores that can be in a placement group in this bucket. Always a multiple of maxPlacementGroupSize. Example : 64	integer
maxPlacementGroupSize required	The maximum total number of instances that can be in a placement group in this bucket Example : 16	integer
placementGroups required	The placement groups in use for this nodearray, if any. Example : [ "object" ]	< placementGroups > array
quotaCoreCount required	The number of total cores that can be started for this family in this region, taking into account the regional quota core count as well. This might not be an integer multiple of quotaCount. Example : 16	integer
quotaCount required	The number of total instances that can be started (given quotaCoreCount) Example : 4	integer
regionalConsumedCoreCount optional	The number of cores that are already in use across the entire region. Example : 2	integer
regionalQuotaCoreCount optional	The number of total cores that can be started in this region. This might not be an integer multiple of regionalQuotaCount. Example : 16	integer
regionalQuotaCount optional	The number of total instances that can be started (given regionalQuotaCoreCount) Example : 4	integer
valid required	If true, this bucket represents a currently valid bucket to use for new nodes. If false, this bucket represents existing nodes only. Example : true	boolean
virtualMachine required	The properties of the virtual machines launched from this bucket Example : "object"	virtualMachine

definition

Name	Description	Schema
machineType required	The VM size of the virtual machine Example : "A2"	string

placementGroups

Name	Description	Schema
activeCoreCount required	How many cores are in this scaleset Example : 16	integer
activeCount required	How many nodes are in this scaleset Example : 4	integer
name required	The unique identifier of this placement group Example : "my-placement-group"	string

virtualMachine

Name	Description	Schema
gpuCount required	The number of GPUs this machine type has Example : 2	integer
infiniband required	If this virtual machine supports InfiniBand connectivity Example : true	boolean
memory required	The RAM in this virtual machine, in GB Example : 7.5	number
pcpuCount required	The number of physical CPUs this machine type has Example : 16	integer
vcpuCount required	The number of virtual CPUs this machine type has Example : 32	integer
vcpuQuotaCount optional	The number of vCPUs that this machine uses from quota Example : 2	integer

ClusterUsage

Usage and optional cost information for the cluster

Name	Description	Schema
usage required	A list of usages by time interval Example : [ "object" ]	< usage > array

usage

Name	Description	Schema
breakdown required	The breakdown of usage in this interval, by category of "node" and "nodearray" Example : [ "[clusterusageitem](#clusterusageitem)" ]	< ClusterUsageItem > array
end required	The end of the interval (exclusive) Example : "string"	string
start required	The beginning of the interval (inclusive) Example : "string"	string
total required	The overall usage for this cluster in this interval, with a category of "cluster" Example : "[clusterusageitem](#clusterusageitem)"	ClusterUsageItem

ClusterUsageItem

Name	Description	Schema
category required	"cluster" for the overall usage; "node" for a single non-array head node; "nodearray" for a whole nodearray Example : "string"	enum (cluster, node, nodearray)
cost optional	The amount that would be charged for this usage, in US dollars and at retail rates. Note: all cost amounts are estimates and are not reflective of the actual bill! Example : 0.0	number
details optional	Details of VM size used by a nodearray including hours, core_count, region priority and operating system. Example : [ "object" ]	< details > array
hours required	The number of core-hours of usage for this category Example : 0.0	number
node optional	The name of the node or nodearray the usage is for (absent for cluster-level data) Example : "string"	string

details

Name	Description	Schema
core_count optional	The number of cores in this VM size Example : 0.0	number
cost optional	Cost of this VM size Example : 0.0	number
hours optional	The number of core-hours of usage for this VM size Example : 0.0	number
os optional	Type of operating system Example : "string"	enum (Windows, Linux)
priority optional	Priority of the VM Sku Example : "string"	enum (Regular, Spot)
region optional	The region the VM size is instantiated in Example : "string"	string
vm_size optional	VM Sku size Example : "string"	string

Node

A node record

Type : object

NodeCreationRequest

Specifies how to add nodes to a cluster

Name	Description	Schema
requestId optional	Optional user-supplied unique token to prevent duplicate operations in case of network communication errors. If this is included and matches an earlier request id, the server ignores this request and returns a 409 error. Example : "00000000-0000-0000-0000-000000000000"	string
sets required	A list of node definitions to create. The request must contain at least one set. Each set can specify a different set of properties. Example : [ "object" ]	< sets > array

sets

Name	Description	Schema
count required	The number of nodes to create Example : 1	integer
definition optional	The definition of the bucket to use. This is provided by the cluster status API call. If some of the items given in the status call are missing, or the entire bucket property is missing, the first bucket that matches the given items is used. Example : "object"	definition
nameFormat optional	If given, nodes will use this naming convention instead of the standard "nodearray-%d" format Example : "custom-name-%d"	string
nameOffset optional	If given, along with nameFormat, offsets nodeindex for new nodes. Example : 1	integer
nodeAttributes optional	Additional attributes to be set on each node from this set Example : "[node](#node)"	Node
nodearray required	The name of the nodearray to start nodes from Example : "execute"	string
placementGroupId optional	If given, nodes with the same value for groupId will all be started in the same placement group. Example : "string"	string

definition

Name	Description	Schema
machineType optional	Example : "A2"	string

NodeCreationResult

Name	Description	Schema
operationId required	The id of this operation Example : "00000000-0000-0000-0000-000000000000"	string
sets required	An array of sets, in the same order as in the request Example : [ "object" ]	< sets > array

sets

Name	Description	Schema
added required	How many nodes were started in this set Example : 1	integer
message optional	Indicates why not all requested nodes could be added, if present Example : "string"	string

NodeList

Results of a node search

Name	Description	Schema
nodes required	The nodes returned Example : [ "[node](#node)" ]	< Node > array
operation optional	If the query includes an operation id, this is the status of that operation Example : "[operationstatus](#operationstatus)"	OperationStatus

NodeManagementRequest

Specifies how to perform actions on nodes in a cluster. There are multiple ways to specify nodes, and if more than one way is included, it is treated as a union.

Name	Description	Schema
filter optional	A filter expression that matches nodes. Note that strings in the expression must be quoted properly. Example : "State === \"Started\""	string
hostnames optional	A list of short hostnames (with no domain) to manage Example : [ "hostname1", "hostname2" ]	< string > array
ids optional	A list of node ids to manage Example : [ "id1", "id2" ]	< string > array
ip_addresses optional	A list of IP addresses to manage Example : [ "10.0.1.1", "10.1.1.2" ]	< string > array
names optional	A list of node names to manage Example : [ "name1", "name2" ]	< string > array
requestId optional	Optional user-supplied unique token to prevent duplicate operations in case of network communication errors. If this is included and matches an earlier request id, the server ignores this request and returns a 409 error. Example : "00000000-0000-0000-0000-000000000000"	string

NodeManagementResult

Name	Description	Schema
nodes required	An array of information about each node that matched the filter in the management request. Each node's status indicates if it was affected by the request. Example : [ "object" ]	< nodes > array
operationId required	The id of this operation Example : "00000000-0000-0000-0000-000000000000"	string

nodes

Name	Description	Schema
error optional	If the status is Error, this contains the error message Example : "This node must be terminated before it can be removed"	string
id required	The id of the node Example : "id1"	string
name required	The name of the node Example : "name1"	string
status optional	One of OK or Error Example : "Error"	enum (OK, Error)

OperationStatus

The status of this node operation

Name	Description	Schema
action required	Example : "string"	enum (create)
startTime required	When this operation was submitted Example : "2020-01-01T12:34:56Z"	string (date-time)