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 node array to a cluster. It accepts multiple node definitions in a single call. It returns the URL to the operation that you can use 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 create	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. You can identify the nodes by using several methods, including node name, node ID, or a filter.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster where you want to deallocate nodes	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. You can identify the nodes in several ways, including node name, node ID, or by using a filter. By default, nodes are removed when terminated unless the node has the Fixed property set to true. In that case, this call acts the same as terminate.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster where you want to remove nodes	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. The operation uses the ShutdownPolicy attribute on each node to determine the action. If the attribute is set to Terminate (the default), the operation terminates the node. If the attribute is set to Deallocate, the operation deallocates the node.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster where you want to shut down nodes	string
Body	action required	Description of which nodes to shut down	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. You can identify the nodes by node name, node ID, or by using a 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. You can identify the nodes in several ways, including node name, node ID, or by using a filter.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster where you want to terminate nodes	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 node array to reach a total count. The cluster processes the request one time. It doesn't re-add nodes later to maintain the number. You can scale by either total cores or total nodes, but not both. The operation returns the URL to use for tracking the status of the operation.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to add nodes to	string
Path	nodearray required	The node array to add nodes to	string
Query	totalCoreCount optional	The total number of cores in this node array, including nodes you already created	integer
Query	totalNodeCount optional	The total number of machines in this node array, including nodes you 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 returns information for the nodes and node arrays in a cluster. For each node array, it returns the status of each "bucket" of allocation that you can use. The status shows how many nodes are in the bucket and how many more nodes you can add. Each bucket is a set of possible VMs with a specific hardware profile. You can create these VMs in a specific location under a customer account. The user's cluster definition determines the valid buckets for a node array. The cloud provider determines the limits.

Parameters

Type	Name	Description	Schema
Path	cluster required	The cluster to query	string
Query	nodes optional	If true, the response includes nodes and node references	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	The time range 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, the start of the timeframe in ISO-8601 format. The value is rounded down to the nearest hour or day.	string
Query	to optional	For custom timeframes, use the end of the timeframe in ISO-8601 format. The value rounds 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. The 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 you provide this ID, the list contains either zero or one element.	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"
}

ClusterStatus

Status of the cluster.

Name	Description	Schema
maxCoreCount required	The maximum number of cores that you can add to this cluster. Example : 16	integer
maxCount required	The maximum number of nodes that you can add to this cluster. Example : 4	integer
nodearrays required	Example : [ "object" ]	< nodearrays > array
nodes optional	An optional list of nodes in this cluster. The response includes this list only if you set nodes=true in the query. Example : [ "[node](#node)" ]	< Node > array
state optional	The current state of the cluster, if the cluster started at least once Example : "Starting"	string
targetState optional	The desired state of the cluster (for example, Started or Terminated) Example : "Started"	string

nodearrays

Name	Description	Schema
buckets required	Each bucket of allocation for this node array. 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 in this node array Example : 16	integer
maxCount required	The maximum number of nodes in this node array Example : 4	integer
name required	The node array name Example : "execute"	string
nodearray required	The attributes of this node array Example : "[node](#node)"	Node

buckets

Name	Description	Schema
activeCoreCount required	The number of cores in use for this bucket, in this node array Example : 40	integer
activeCount required	The number of nodes in use for this bucket, in this node array. This count includes nodes that are still acquiring a VM. Example : 10	integer
activeNodes optional	The node names in use for this bucket, in this node array. This list includes nodes that are still acquiring a VM. The response includes this property only if the query contains nodes=true. Example : [ "string" ]	< string > array
availableCoreCount required	How many extra cores you can create in this bucket and node array. This value is always a multiple of availableCount. Example : 8	integer
availableCount required	How many extra nodes you can create in this bucket and node array. This value might be less than the number you get when you subtract usedCount from maxCount, because maxCount might have a global limit. Example : 2	integer
bucketId required	The identifier for this bucket. This value stays the same for a given bucket in a node array as long as you don't delete the cluster. 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 you can start for this family in this region. This number might not be an integer multiple of quotaCount. Example : 16	integer
familyQuotaCount optional	The number of total instances that you can start when you set familyQuotaCoreCount. Example : 4	integer
invalidReason required	If valid is false, the field contains 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 can 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 can be in this bucket, including global and nodearray limits Example : 4	integer
maxPlacementGroupCoreSize required	The maximum total number of cores in a placement group for this bucket. Always a multiple of maxPlacementGroupSize. Example : 64	integer
maxPlacementGroupSize required	The maximum total number of instances in a placement group for this bucket. Example : 16	integer
placementGroups required	The placement groups in use for this node array, if any. Example : [ "object" ]	< placementGroups > array
quotaCoreCount required	The number of total cores that you can start for this family in this region. This number also takes into account the regional quota core count. This value might not be an integer multiple of quotaCount. Example : 16	integer
quotaCount required	The number of total instances that you can start, given the 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 you can start in this region. This number might not be an integer multiple of regionalQuotaCount. Example : 16	integer
regionalQuotaCount optional	The number of total instances that you can start (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 that you launch 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	The number of cores in this scale set Example : 16	integer
activeCount required	The number of nodes in this scale set 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 for this machine type 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 to charge for this usage, in US dollars and at retail rates. Note: all cost amounts are estimates and don't reflect the actual bill! Example : 0.0	number
details optional	Details of the 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 node array 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 where you instantiate the VM size 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 the server receives a request with a requestId that matches an earlier request, it ignores the 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. The cluster status API call provides this definition. If the definition is missing some items given in the status call or the entire bucket property, the first bucket that matches the given items is used. Example : "object"	definition
nameFormat optional	If you provide this value, nodes use this naming convention instead of the standard nodearray-%d format Example : "custom-name-%d"	string
nameOffset optional	If you provide this property with nameFormat, the property offsets nodeindex for new nodes. Example : 1	integer
nodeAttributes optional	Extra attributes to set on each node in this set Example : "[node](#node)"	Node
nodearray required	The name of the nodearray to start nodes from Example : "execute"	string
placementGroupId optional	If you provide this property, nodes with the same value for groupId all start 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 the 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	The number of nodes to add in the set Example : 1	integer
message optional	Explains why the system can't add all requested nodes, if present Example : "string"	string

NodeList

Results of a node search

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

NodeManagementRequest

Specifies how to perform actions on nodes in a cluster. You can specify nodes in multiple ways. If you include more than one way, the request treats the specification 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 the server receives a request with a requestId that matches an earlier request ID, it ignores the 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 matches the filter in the management request. Each node's status indicates if the request affects it. 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, 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 the node operation.

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