Cluster upgrade

Cluster upgrades are an asynchronous operation that can change a cluster's disk size, high availability configuration, Postgres major version, or just perform a scheduled failover. In most cases a cluster upgrade involves spinning up a new server with new configuration, waiting for it to catch up to the original, then failing over so that the replacement takes the place of the original.

The standard upgrade process involves POSTing to a cluster's /upgrade endpoint, observing the upgrade's process using the GET endpoint, and optionally cancelling the operation using upgrade DELETE.

Part of the API reference collection

This page is part of the Crunchy Bridge API reference, and primarily meant to act as an exhaustive guide for technical integrations which are already in progress. To understand the basics of using the API, see API concepts and getting started.

The `ClusterUpgrade` API resource

Response for the status of a cluster upgrade.

Content type: application/json

Name	Type	Description
`cluster_id`	`string` in EID format	ID of the cluster being upgraded.
`operations`	`array` of `array`	Contains ongoing upgrade operations. Empty if there are no ongoing upgrade operations.
`team_id`	`string` in EID format	ID of the team which the cluster being upraded belongs to.

Example

{
    "cluster_id": "rvf73a77ozfsvcttryebfrnlem",
    "operations": [
        {
            "flavor": "ha_change",
            "starting_from": null,
            "state": "waiting_for_ha_standby"
        },
        {
            "flavor": "resize",
            "starting_from": null,
            "state": "in_progress"
        }
    ],
    "team_id": "eaevtjiudzeq7bsqbbpiscund4"
}

Get upgrade status

Get the status of an ongoing cluster resize.

GET /clusters/{cluster_id}/upgrade

Request

Path parameters

cluster_id: The ID of the cluster.

cURL example

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

Response

Status: 200

Responds with the standard ClusterUpgrade API resource.

Upgrade cluster

Start a cluster upgrade which may include changing its plan, upgrading its major version, increasing its storage size, changing its high availability status, or just performing a scheduled failover.

POST /clusters/{cluster_id}/upgrade

Request

Path parameters

cluster_id: The ID of the cluster.

Request body schema

Content type: application/json

Name	Type	Description
`plan_id`	`string`	The new ID of the plan to change the cluster to.
`postgres_version_id`	`integer`, or string``undefined	An identifier for the Postgres version to retrieve. May be either the primary ID of a Postgres version or a major version number like "14".
`starting_from`	`string` of date/time formatted as RFC 3339	The time to start the upgrade. Should be a timestamp formatted as RFC3339 like `2023-01-01T00:00:00Z`. Must be less than 72 hours in the future. If omitted, this value will default to the cluster's maintenance window.
`storage`	`integer`	The new storage size for the cluster in GB.
`major_version`	`integer`	The Postgres major version number to upgrade the cluster to. Deprecated Prefer sending a value to `postgres_version_id` instead which will also accept a major version number value.

Example request body

{
    "plan_id": "standard-64",
    "postgres_version_id": null,
    "storage": 100
}

cURL example

curl -X POST https://api.crunchybridge.com/clusters/{cluster_id}/upgrade
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"plan_id":"standard-64","postgres_version_id":null,"storage":100}'

Response

Status: 201

Responds with the standard ClusterUpgrade API resource.

Update upgrade cluster

Update an ongoing or scheduled upgrade. Only some target properties can be updated like plan, storage, or failover window. Updating an upgrade is only possible if a failover has not yet occurred. If it has, this endpoint will return an error.

When upgrading properties inherent to the new cluster (like plan or storage) a new server is spun up to be failed over to, and any original server associated with the upgrade is abandoned. Updating the failover window does no additional work beyond rescheduling the upgrade.

Common uses for this endpoint are to reschedule an already scheduled upgrade to a different time.

PUT /clusters/{cluster_id}/upgrade

Request

Path parameters

cluster_id: The ID of the cluster.

Request body schema

Content type: application/json

Name	Type	Description
`plan_id`	`string`	The new ID of the plan to change the cluster to.
`postgres_version_id`	`integer`, or string``undefined	An identifier for the Postgres version to retrieve. May be either the primary ID of a Postgres version or a major version number like "14".
`starting_from`	`string` of date/time formatted as RFC 3339	The new time to start the upgrade. Should be a timestamp formatted as RFC3339 like `2023-01-01T00:00:00Z`. Must be less than 72 hours in the future. If omitted, the upgrade failover window is not updated. Mutually exclusive with `use_cluster_maintenance_window`.
`storage`	`integer`	The new storage size for the cluster in GB.
`use_cluster_maintenance_window`	`boolean`	Set the upgrade to occur during the cluster's maintenance window. If omitted, the upgrade failover window is not updated. Mutually exclusive with `starting_from`.

cURL example

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

Response

Status: 201

Responds with the standard ClusterUpgrade API resource.

Cancel upgrade

Cancel a cluster resize.

DELETE /clusters/{cluster_id}/upgrade

Request

Path parameters

cluster_id: The ID of the cluster.

cURL example

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

Response

Status: 200

Responds with the standard ClusterUpgrade API resource.