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