api-resources.md

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)