Operations

  • Article

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

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

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
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

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)

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)