Note
We are no longer onboarding new users to Citus Cloud on AWS. However, existing customers can continue to use Citus Cloud as they do today.
Formation API
Note
Cloud API access is available upon request. Open a support ticket to enable it for your account.
Citus Cloud provides an API to list, delete, and create formations within an organization. This is a convenient way to manage frequent formation changes.
Authentication
All formation API requests must include an authentication token. To get one, visit the tokens page, accessible through the Cloud menu bar in Org > API Tokens
:
Create a token with a name that’s meaningful to you. The name does not affect the API, it exists so you can revoke the token later if desired. Tokens last for one year.
After generating the token, its value will be displayed just once. Copy it to a secure place because it will never be visible again from the Cloud console.
In the examples below, we will assume that the token is assigned to an environment variable in the shell:
# save to an environment variable for convenience
export API_TOKEN=<token>
The token is in JWT format, and should be added to HTTPS requests using the Authorization
header:
Authorization: Token API_TOKEN
For security, all requests must be issued over https. Additionally, API requests are limited to five per minute.
Create Formation
Endpoint: POST https://console.citusdata.com/api/v1/formations/
Sample request payload:
{ "name": "my-formation", "region": "us-east-1", "tune_attributes": { "coordinator_tune": "t2.small", "worker_tune": "t2.small", "coordinator_ha": false, "worker_ha": false, "worker_count": "2", "coordinator_disk_size": "100", "worker_disk_size": "100" } }
Parameters:
(mandatory) name: a non-empty string of your choice
(mandatory) region: any of our Supported Regions
(mandatory) coordinator_tune, worker_tune: a tune is any of these AWS machine types: t2.small, t2.medium, t2.large, r3.large, r3.xlarge, r3.2xlarge, r3.4xlarge, r3.8xlarge r4.large, r4.xlarge, r4.2xlarge, r4.4xlarge, r4.8xlarge, r4.16xlarge, r5.large, r5.xlarge, r5.2xlarge, r5.4xlarge, r5.12xlarge, r5.24xlarge, c4.xlarge, c4.2xlarge, c4.4xlarge, c4.8xlarge, c5.xlarge, c5.2xlarge, c5.4xlarge, c5.9xlarge. (If you choose a tune from the t2.* series, both the coordinator_tune and worker_tune must be same.)
(mandatory) coordinator_disk_size, worker_disk_size: size in gigabytes. May be any of the values 100, 512, 1024, 1536, 2048, or 2560. (If you choose a tune from the t2.* series, the disk size must be 100.)
(mandatory) worker_count: numeric value less than or equal to 40
coordinator_ha, worker_ha: whether to enable High Availability. Default is false.
Example:
curl -H "Authorization: Token $API_TOKEN" \ -H "Content-Type: application/json" \ --request POST \ -d '{"tune_attributes": { "coordinator_tune": "t2.small", "worker_tune": "t2.small", "worker_count": "2", "coordinator_disk_size": "100", "worker_disk_size": "100"}, "name": "my-formation", "region": "us-east-1"}' \ https://console.citusdata.com/api/v1/formations/
Response:
{ "id": "0123456789abcdef0123456789a" }
List Formations
Endpoint: GET https://console.citusdata.com/api/v1/formations/
Example:
curl -H "Authorization: Token $API_TOKEN" \ https://console.citusdata.com/api/v1/formations/
Response:
{ "formations": [ { "id": "0123456789abcdef0123456789a", "name": "my-formation", "region": "us-east-1", "created_at": "2019-01-01T00:00:00Z" } ] }
The id attribute identifies the formation and is required to destroy a formation or get its details.
Formation Details
Endpoint: GET https://console.citusdata.com/api/v1/formations/:formation_id
Example:
curl -H "Authorization: Token $API_TOKEN" \ https://console.citusdata.com/api/v1/formations/0123456789abcdef0123456789a
Response:
{ "id": "0123456789abcdef0123456789a", "name": "my-formation", "state": "steady", "region": "us-east-1", "created_at": "2019-01-01T00:00:00Z", "tune_attributes": { "is_mx": false, "is_zfs": false, "worker_ha": false, "worker_tune": "t2.small", "worker_disk_size": "100", "worker_count": 2, "coordinator_ha": false, "coordinator_tune": "t2.small", "coordinator_disk_size": "100" }, "database_url": "postgres://foo:bar@host:5432/db?sslmode=require" }
Possible states include: steady, creating, converging, ready, archiving, and archived.
Destroy Formation
Endpoint: DELETE https://console.citusdata.com/api/v1/formations/:formation_id
Example:
curl -H "Authorization: Token $API_TOKEN" --request DELETE \ https://console.citusdata.com/api/v1/formations/0123456789abcdef0123456789a
Response:
{ "success": true }