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

NameNullableTypeDescription
cluster_idstring in EID format

ID of the cluster being upgraded.

operationsarray of array

Contains ongoing upgrade operations. Empty if there are no ongoing upgrade operations.

team_idstring 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

NameRequiredTypeDescription
plan_idstring

The new ID of the plan to change the cluster to.

postgres_version_idinteger, 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_fromstring 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.

storageinteger

The new storage size for the cluster in GB.

major_versioninteger

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

NameRequiredTypeDescription
plan_idstring

The new ID of the plan to change the cluster to.

postgres_version_idinteger, 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_fromstring 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.

storageinteger

The new storage size for the cluster in GB.

use_cluster_maintenance_windowboolean

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.