Clusters

The clusters endpoint allows you to retrieve information about clusters as well as provision new ones and delete existing clusters.

Prior to using any of these endpoints, take a look at the Getting Started section within the API reference to understand how to create your long lived API key and retrieve a short lived key to be able to execute operations against the API.

Listing clusters

Generic listing

By default, /clusters will list from the Personal team.

{
  "clusters": [
    {
      "id": "uan5fhajlzhjdnzmhgfp2d2umy",
      "team_id": "yqdhoxeognh67gby7wag7w5gem",
      "provider_id": "aws",
      "region_id": "us-east-1",
      "created_at": "2021-01-22T22:22:35.03991Z",
      "updated_at": "2021-01-22T22:22:35.03991Z",
      "name": "test-1",
      "major_version": 12,
      "minor_version": 5,
      "storage": 100,
      "cpu": 2,
      "memory": 8,
      "is_ha": true
    },
    ...
    {
      "id": "j7bbo2gbd5davhkcuchsmsz3s4",
      "team_id": "yqdhoxeognh67gby7wag7w5gem",
      "provider_id": "aws",
      "region_id": "us-east-1",
      "created_at": "2021-01-28T00:14:37.898092Z",
      "updated_at": "2021-01-28T00:14:37.898092Z",
      "name": "test-3",
      "major_version": 13,
      "minor_version": 1,
      "storage": 100,
      "cpu": 4,
      "memory": 16,
      "is_ha": false,
      "replicas": [
        {
          "id": "hw4j2fw33zgb3mx5lpoiosj3va",
          "team_id": "yqdhoxeognh67gby7wag7w5gem",
          "provider_id": "aws",
          "region_id": "us-east-1",
          "created_at": "2021-01-28T19:15:04.441902Z",
          "updated_at": "2021-01-28T19:15:04.441902Z",
          "name": "test-3-replica",
          "major_version": 13,
          "minor_version": 1,
          "storage": 100,
          "cpu": 2,
          "memory": 8,
          "is_ha": false
        }
      ]
    }
  ]
}

Clusters object

Attribute	Type	Description
`id`	string	Unique identifier for the cluster
`team_id`	string	Unique identifier for the team
`provider_id`	string	Unique identifier for provider
`region_id`	string	Unique identifier for region
`created_at`	string	Date/time of when the cluster was created, in RFC3339 format
`updated_at`	string	Date/time of when the cluster was last created, in RFC3339 format
`name`	string	Name of cluster
`major_version`	integer	PostgreSQL major version number
`minor_version`	integer	PostgreSQL minor version number
`storage`	integer	Storage in GB
`cpu`	integer	Number of vCores
`memory`	integer	Memory in GB
`is_ha`	boolean	Whether high availability is enabled for cluster
`replicas`	array of objects	Read replicas of cluster

Replicas object

The replicas object has the same attributes as the parent cluster object.

Team specific listing

To retrieve the list of clusters that exist for a specific team, you should hit the standard clusters endpoint followed by the team ID:

GET /clusters?team_id={team_id}

This will provide all clusters that exist within that team:

{
  "clusters": [
    {
      "id": "4ayzwodj6zh3nhkcere6u7byhe",
      "team_id": "roi5nqqoyvgt3k2ka3t5qmfvgy",
      "provider_id": "azure",
      "region_id": "westus",
      "created_at": "2021-01-28T19:51:02.646693Z",
      "updated_at": "2021-01-28T19:51:02.646693Z",
      "name": "team-cluster1",
      "major_version": 13,
      "minor_version": 1,
      "storage": 100,
      "cpu": 4,
      "memory": 16,
      "is_ha": false
    },
    {
      "id": "rvf73a77ozfsvcttryebfrnlem",
      "team_id": "roi5nqqoyvgt3k2ka3t5qmfvgy",
      "provider_id": "azure",
      "region_id": "eastus2",
      "created_at": "2021-02-08T14:03:54.772274Z",
      "updated_at": "2021-02-08T14:03:54.772274Z",
      "name": "team-cluster2",
      "major_version": 13,
      "minor_version": 1,
      "storage": 32,
      "cpu": 1,
      "memory": 4,
      "is_ha": false
    }
  ]
}

Cluster Detail Listing

Details about a specific cluster can be retrieved using the GET /clusters/{cluster_id} endpoint.

The resulting response will be the details as defined in the Cluster Object, with the following additional fields:

State - the current state of the cluster, eg. ‘creating’, ‘ready’
Oldest Backup - the time of oldest backup available.

Also included is the instance details about the cluster. This field is an array of all details for the primary and related read replica instances.

{
  "cluster": {
    "id": "azpiatrcn5eujmhncap73ujeqm",
    "team_id": "eaevtjiudzeq7bsqbbpiscund4",
    "provider_id": "aws",
    "region_id": "us-east-1",
    "created_at": "2021-02-12T19:51:35.414479Z",
    "updated_at": "2021-01-30T19:51:35.414479Z",
    "name": "example-cluster",
    "major_version": 13,
    "minor_version": 0,
    "storage": 1,
    "cpu": 1,
    "memory": 2,
    "is_ha": false,
    "state": "ready",
    "oldest_backup": "2021-01-15T19:55:08Z"
  },
  "instances": [
    {
      "id": "azpiatrcn5eujmhncap73ujeqm",
      "name": "example-cluster",
      "provider_id": "aws",
      "region_id": "us-east-1",
      "type": "primary",
      "url": "postgres://p.azpiatrcn5eujmhncap73ujeqm.crunchybridge.com:5432/postgres"
    }
  ]
}

Cluster Instance Objects

Attribute	Type	Description
`id`	string	Unique identifier for the cluster
`name`	string	the name of the cluster
`type`	string	the type of the instance (‘primary’ or ‘read_replica’)
`url`	string	the connection url for the instance
`provider_id`	string	the provider hosting the instance
`region_id`	string	the region the provider is hosting the instance

Provisioning a cluster

Clusters can be provisioned against the API. There are a number of required and a few optional fields when creating your cluster:

Name - text [required]
Team - Unique team identifier [required]
Plan - Unique plan identifier [required]
Storage - Integer in MB [required]
Provider - Unique provider identifier [required]
Region - Unique region identifier [required]
Version - Integer Postgres major version [required]
HA - Boolean to specify HA on or off (optional, default: false)

Refer to the Providers section for details on retrieving the unique identifiers for plans, providers, and regions.

An example post to create a cluster:

$ curl -X POST https://api.crunchybridge.com/clusters \
  -d '{
    "name": "staging",
    "team_id": "eaevtjiudzeq7bsqbbpiscund4",
    "plan_id": "hobby-2",
    "storage": 100,
    "provider_id": "aws",
    "region_id": "us-east-1",
    "major_version": 13
  }' -H "Authorization: Bearer lf6b76vzhzc2hhudyacj4aqlgy"

Forking a cluster

Clusters can be forked at point in time against the API. Required fields are the same for provisioning a new cluster with the addition of one optional field:

Target Time - the target point in time, in RFC3339 format [optional, default: now()]

The target time should be a time between the oldest_backup and now(). The oldest backup time can be obtained from the cluster details listing API endpoint. Note: If not oldest backup is listed, then a backup currently doesn’t not exist for the cluster. This is common shortly after a cluster is first created.

POST /clusters/{cluster_id}/forks

An example POST to fork a cluster:

$ curl -X POST https://api.crunchybridge.com/clusters \
  -d '{
    "name": "staging-fork",
    "team_id": "eaevtjiudzeq7bsqbbpiscund4",
    "plan_id": "hobby-2",
    "storage": 100,
    "provider_id": "aws",
    "region_id": "us-east-1",
    "major_version": 13,
    "target_time": "2009-11-10T23:00:00Z"
  }' -H "Authorization: Bearer lf6b76vzhzc2hhudyacj4aqlgy"

Deleting a cluster

DELETE /clusters/{cluster_id}

curl -X DELETE https://api.crunchybridge.com/clusters/rvf73a77ozfsvcttryebfrnlem -H "Authorization: Bearer lf6b76vzhzc2hhudyacj4aqlgy"