Cluster

Clusters are a core primitive that represent a hosted Crunchy Bridge Postgres database along with all associated resources required to operate it, including the cloud server that it runs on.

Clusters are named such because the internal replica needed to maintain a cluster with high availability is considered to be part of same cluster as its primary, thereby making it a “cluster” of multiple servers. Public-facing replicas and forks on the other hand, are represented in the API as separate clusters with their own uniquely addressable IDs.

See also upgrading clusters to change a cluster’s disk size, high availability configuration, or Postgres major version.

The Cluster API resource

A database cluster.

Content type: application/json

Example

{
    "cluster_id": null,
    "cpu": 16,
    "created_at": "2021-07-11T01:02:03Z",
    "disk_usage": {
        "disk_available_mb": 95000,
        "disk_total_size_mb": 100000,
        "disk_used_mb": 5000
    },
    "environment": null,
    "host": "p.rvf73a77ozfsvcttryebfrnlem.crunchybridge.com",
    "id": "rvf73a77ozfsvcttryebfrnlem",
    "is_ha": false,
    "is_protected": false,
    "is_suspended": false,
    "maintenance_window_start": 21,
    "major_version": 13,
    "memory": 64,
    "name": "crunchy-production",
    "network_id": "p56biajnfvgjhftvqs7lqymspe",
    "plan_id": "standard-64",
    "postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
    "provider_id": "aws",
    "region_id": "us-west-2",
    "replicas": [
        {
            "cluster_id": null,
            "cpu": 16,
            "created_at": "2021-07-11T01:02:03Z",
            "disk_usage": null,
            "environment": null,
            "host": "",
            "id": "drsve2t4f5e5znkmef6hmchy2e",
            "is_ha": false,
            "is_protected": false,
            "is_suspended": false,
            "maintenance_window_start": null,
            "major_version": 13,
            "memory": 64,
            "name": "crunchy-production-replica",
            "network_id": "p56biajnfvgjhftvqs7lqymspe",
            "plan_id": "standard-64",
            "postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
            "provider_id": "aws",
            "region_id": "us-west-2",
            "replicas": null,
            "storage": 100,
            "tailscale_active": false,
            "team_id": "eaevtjiudzeq7bsqbbpiscund4",
            "updated_at": "2021-07-11T01:02:03Z"
        }
    ],
    "storage": 100,
    "tailscale_active": false,
    "team_id": "eaevtjiudzeq7bsqbbpiscund4",
    "updated_at": "2021-07-11T01:02:03Z"
}

The ClusterDiskUsage object

Contains information about a cluster's disk usage.

List clusters

List clusters for a specific team.

This endpoint’s pagination may be ordered through the order_field parameter by id or name. Defaults to being ordered by name.

GET /clusters

Request

Query parameters

cURL example

curl -X GET https://api.crunchybridge.com/clusters
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Response for listing clusters.

Content type: application/json

Example

{
    "clusters": [
        {
            "cluster_id": null,
            "cpu": 16,
            "created_at": "2021-07-11T01:02:03Z",
            "disk_usage": {
                "disk_available_mb": 95000,
                "disk_total_size_mb": 100000,
                "disk_used_mb": 5000
            },
            "environment": null,
            "host": "p.rvf73a77ozfsvcttryebfrnlem.crunchybridge.com",
            "id": "rvf73a77ozfsvcttryebfrnlem",
            "is_ha": false,
            "is_protected": false,
            "is_suspended": false,
            "maintenance_window_start": 21,
            "major_version": 13,
            "memory": 64,
            "name": "crunchy-production",
            "network_id": "p56biajnfvgjhftvqs7lqymspe",
            "plan_id": "standard-64",
            "postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
            "provider_id": "aws",
            "region_id": "us-west-2",
            "replicas": [
                {
                    "cluster_id": null,
                    "cpu": 16,
                    "created_at": "2021-07-11T01:02:03Z",
                    "disk_usage": null,
                    "environment": null,
                    "host": "",
                    "id": "drsve2t4f5e5znkmef6hmchy2e",
                    "is_ha": false,
                    "is_protected": false,
                    "is_suspended": false,
                    "maintenance_window_start": null,
                    "major_version": 13,
                    "memory": 64,
                    "name": "crunchy-production-replica",
                    "network_id": "p56biajnfvgjhftvqs7lqymspe",
                    "plan_id": "standard-64",
                    "postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
                    "provider_id": "aws",
                    "region_id": "us-west-2",
                    "replicas": null,
                    "storage": 100,
                    "tailscale_active": false,
                    "team_id": "eaevtjiudzeq7bsqbbpiscund4",
                    "updated_at": "2021-07-11T01:02:03Z"
                }
            ],
            "storage": 100,
            "tailscale_active": false,
            "team_id": "eaevtjiudzeq7bsqbbpiscund4",
            "updated_at": "2021-07-11T01:02:03Z"
        }
    ],
    "has_more": false,
    "next_cursor": null
}

Create cluster

Create a database cluster.

POST /clusters

Request

Request body schema

Content type: application/json

Example request body

{
    "name": "crunchy-production",
    "plan_id": "hobby-2",
    "postgres_version_id": 13,
    "provider_id": "aws",
    "region_id": "us-west-2",
    "storage": 100,
    "team_id": "eaevtjiudzeq7bsqbbpiscund4"
}

cURL example

curl -X POST https://api.crunchybridge.com/clusters
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"name":"crunchy-production","plan_id":"hobby-2","postgres_version_id":13,"provider_id":"aws","region_id":"us-west-2","storage":100,"team_id":"eaevtjiudzeq7bsqbbpiscund4"}'

Response

Status: 201

Responds with the standard Cluster API resource.

Get cluster

Get a cluster by ID.

GET /clusters/{cluster_id}

Request

Path parameters

• cluster_id: The ID of the cluster to retrieve.

cURL example

curl -X GET https://api.crunchybridge.com/clusters/{cluster_id}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard Cluster API resource.

Update cluster

Update various properties of an existing cluster.

PATCH /clusters/{cluster_id}

Request

Path parameters

• cluster_id: The ID of the cluster to update.

Request body schema

Content type: application/json

Example request body

{
    "maintenance_window_start": 3,
    "name": "new-cluster-name"
}

cURL example

curl -X PATCH https://api.crunchybridge.com/clusters/{cluster_id}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"maintenance_window_start":3,"name":"new-cluster-name"}'

Response

Status: 200

Responds with the standard Cluster API resource.

Destroy cluster

Delete a database cluster.

DELETE /clusters/{cluster_id}

Request

Path parameters

• cluster_id: The ID of the cluster to delete.

cURL example

curl -X DELETE https://api.crunchybridge.com/clusters/{cluster_id}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard Cluster API resource.

Get cluster status

Gets the online status for a cluster. This differs from the standard get endpoint in that it contains information that’s retrieved directly from the cluster itself, rather than information about the cluster that’s stored out of band and which may not be as current.

GET /clusters/{cluster_id}/status

Request

Path parameters

• cluster_id: The ID of the cluster to get status for.

cURL example

curl -X GET https://api.crunchybridge.com/clusters/{cluster_id}/status
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Response for getting a cluster’s online status.

Content type: application/json

Example

{
    "disk_available_mb": 0,
    "disk_total_size_mb": 0,
    "disk_usage": {
        "disk_available_mb": 94948,
        "disk_total_size_mb": 100213,
        "disk_used_mb": 133
    },
    "disk_used_mb": 0,
    "oldest_backup_at": "2021-07-11T01:02:03Z",
    "ongoing_upgrade": {
        "operations": [
            {
                "flavor": "ha_change",
                "state": "waiting_for_ha_standby"
            },
            {
                "flavor": "resize",
                "state": "in_progress"
            }
        ]
    },
    "state": "ready"
}

The ClusterUpgrade object

Response for the status of a cluster upgrade.

Example

{
    "operations": [
        {
            "flavor": "ha_change",
            "state": "waiting_for_ha_standby"
        },
        {
            "flavor": "resize",
            "state": "in_progress"
        }
    ]
}

The ClusterUpgradeOperation object

An ongoing upgrade operation (like a version upgrade or resize) within a database cluster.

Create cluster fork

Create a fork of an existing database cluster.

Note that target_time must be between the cluster’s oldest backup (see oldest_backup_at under cluster status) and the current time. Clusters can’t be forked until an initial backup has been captured for them. This will occur shortly after they’re created, but a brand new cluster may not be available for forking right away.

POST /clusters/{cluster_id}/forks

Request

Path parameters

• cluster_id: The ID of the cluster to fork.

Request body schema

Content type: application/json

Example request body

{
    "name": "crunchy-production-fork",
    "plan_id": "standard-64",
    "provider_id": "aws",
    "region_id": "us-west-2",
    "storage": 100,
    "target_time": "2021-07-11T01:02:03Z"
}

cURL example

curl -X POST https://api.crunchybridge.com/clusters/{cluster_id}/forks
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"name":"crunchy-production-fork","plan_id":"standard-64","provider_id":"aws","region_id":"us-west-2","storage":100,"target_time":"2021-07-11T01:02:03Z"}'

Response

Status: 201

Responds with the standard Cluster API resource.

Schedule maintenance

Explicitly schedule maintenance for a cluster. Even if there’s no pending maintenance to be done, using this endpoint will always spin up new servers and execute a failover.

Specify now to start maintenance immediately, a timestamp in starting_from to start maintenance approximately after a target time, or neither to have it occur during the cluster’s normal maintenance window. starting_from cannot be more than one week in the future.

This endpoint has a few different uses:

• It allows maintenance to be scheduled at a very specific time rather than just as some point during a cluster’s three-hour maintenance window.

• Allows a cluster to be manually upgraded to a new Postgres minor release (major versions need an explicit upgrade, but minor releases can activate automatically on a failover).

• Lets users test, observe, and time a failover to get a feel for what an automatic one caused by a production problem roughly looks like.

If called multiple times in quick succession, a new call will override the scheduled behavior of the last call (i.e. specifying a new starting_from would supersede the old one), but only up to the time where the maintenance failover succeeds, after which another maintenance will be scheduled.

PUT /clusters/{cluster_id}/actions/schedule-maintenance

Request

Path parameters

• cluster_id: The ID of the cluster to schedule maintenance for.

Request body schema

Content type: application/json

Example request body

{
    "now": true,
    "starting_from": null
}

cURL example

curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/schedule-maintenance
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"now":true,"starting_from":null}'

Response

Status: 200

A simple message response.

These responses tend to come from endpoints that affect some kind of change but do not return the target API resource. e.g. creating a backup, etc.

Content type: application/json

Example

{
    "message": "Server will restart momentarily."
}

Suspend cluster

Suspends a cluster, which deactivates the virtual machine it’s running on but keeps its disk image around so that it can later be resumed. Normal billing for the cluster is suspended, but storage costs will continue to accrue.

Currently this feature is only supported on AWS and Azure, and the target cluster must be a primary.

PUT /clusters/{cluster_id}/actions/suspend

Request

Path parameters

• cluster_id: The ID of the cluster to suspend.

cURL example

curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/suspend
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard Cluster API resource.

Start backup

Request to start a new backup capture on a cluster.

Backups occur asynchronously, and will be visible from the list backups endpoint when completed. A request to this endpoint might be a no-op in case a backup is already in progress, or a backup was requested recently.

Existing backups are available via the list backups endpoint.

PUT /clusters/{cluster_id}/actions/start-backup

Request

Path parameters

• cluster_id:

cURL example

curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/start-backup
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

A simple message response.

These responses tend to come from endpoints that affect some kind of change but do not return the target API resource. e.g. creating a backup, etc.

Content type: application/json

Example

{
    "message": "Server will restart momentarily."
}

Resume cluster

Resumes normal operation of a suspended cluster. Normal billing is resumed as well.

PUT /clusters/{cluster_id}/actions/resume

Request

Path parameters

• cluster_id: The ID of the cluster to resume.

cURL example

curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/resume
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard Cluster API resource.

Restart cluster

Restart the underlying server of a cluster, or a specific service on it.

The restart occurs asynchronously and calling this endpoint multiple times will idempotently queue up a only single restart until that restart occurs, at which point a new restart can be queued.

PUT /clusters/{cluster_id}/actions/restart

Request

Path parameters

• cluster_id: The ID of the cluster.

Request body schema

Content type: application/json

cURL example

curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/restart
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard Cluster API resource.