REST Methods

Note: all requests are access controlled using the HTTP basic authentication scheme. In addition, unless otherwise noted, all requests return 200 OK in case of success, 409 Conflict in case of user error, and 500 Internal Server Error in case of failure.

GET /cloud/api/clusters GET /cloud/api/clusters/{clustername}

Returns the current list of clusters as JSON. Each cluster is a dictionary whose contents are the Cloud.Cluster record, with two additional keys:

  • Nodes: the list of records in this cluster
  • Instances: the list of records in this cluster

If clustername is specified, the list only contains the named cluster.

POST /cloud/api/import_cluster/{clustername}

Parses and stores the embedded cluster as the given name. The body can be encoded as either application/x-www-form-urlencoded or multipart/form-data.

formparameter cluster:
The contents of the cluster.
formparameter parameters:
Optional. If specified, this contains the cluster parameters to use when creating this cluster.
formparameter parameters_format:
Optional. If parameters are given, this indicates the format of the cluster parameters. “json” is currently supported.
formparameter force:
Optional. If “true”, the existing cluster is updated to match.
formparameter template:
Optional. If the cluster parameter is specified, this is the name of the cluster to import from the cluster definition,
which can contain more than one cluster definition. (It defaults to clustername.)
If the cluster parameter is not specified, it is the name of the existing stored cluster template to use.
formparameter as_template:
Optional. If “true”, the cluster is stored as a template, meaning it can be used to create other clusters.

POST /cloud/actions/startcluster/{clustername}

Starts the named cluster.

query wait_time:
Optional. How long to wait for the orchestration process to begin

POST /cloud/actions/add_node/{clustername}/{nodetemplate} POST /cloud/actions/add_node/{clustername}

Adds nodes to a cluster. If the cluster is already started, then the nodes will also be started. If nodetemplate is given, copies of that node are added. If not given, the nodearray node is used. If there is more than one, a status of 409 is returned.

query count: Optional. If specified, how many copies of the nodes to start
query fixed: Optional. If “true”, these nodes will be recreated when a cluster is terminated and started again.
If not specified or “false”, the nodes will be deleted when the cluster is terminated.
query source_cluster:
Optional. If given, this will use the matching node in source_cluster as the source rather than the node in clustername.
query wait_time:
Optional. How long to wait for the orchestration process to begin

POST /cloud/actions/terminate_node/{clustername}/{nodename} POST /cloud/actions/terminate_node/{clustername}

Terminates and optionally removes nodes from a cluster. You can specify either nodename or a filter that matches nodes.

query wait_time:

Optional. How long to wait for the orchestration process to begin

query filter:

Optional. If given, this is a filter expression that matches nodes that should be terminated. For example, to delete a set of nodes:

Name in { "name1", "name2", "name3" }
query instance-filter:

Optional. If given, this is a filter expression that matches running instances whose nodes should be terminated. For example, to terminate all nodes in a single availability zone:

Zone == "us-east-1a"
query remove:

Optional. If “true”, the nodes are deleted after they are terminated.

query force:

Optional. If “true”, and remove is “true”, nodes are deleted as long as the termination process has started, even if it has not completed. This is primarily intended for “stuck” termination processes that cannot complete (for instance, due to an unhandled cloud provider error).

Warning

Use of the force parameter can leave instances running in the cloud!

POST /cloud/actions/terminatecluster/{clustername}

Terminates the named cluster

query wait_time:
Optional. How long to wait for the orchestration process to begin

POST /cloud/actions/removecluster/{clustername}

Deletes the cluster. The cluster must be terminated already.

query force: Optional. If “true”, the cluster is deleted as long as the termination process has started, even if it has not completed.
This is primarily intended for “stuck” termination processes that cannot complete (for instance, due to an unhandled cloud provider error).

Warning

Use of the force parameter can leave instances running in the cloud!

Example

Click to view an example of how you might use the RESTful API to automate the creation and management of clusters within CycleCloud.