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