Cluster Compatibility Version
Use the cluster compatibility version to perform a rolling upgrade of Sync Gateway 4.1 without downtime and with a safe rollback path.
Related Application Deployment topics: Release Notes | Compatibility Matrix
Overview
The cluster compatibility version is a cluster-wide value that Sync Gateway uses to coordinate behaviour across nodes running different versions during a rolling upgrade.
Introduced in Sync Gateway 4.1, the cluster compatibility version lets you:
-
Perform a rolling upgrade without downtime or reduction in cluster capacity.
-
Preserve a safe rollback path during the upgrade window.
-
Ensure that new cluster-wide features activate only after all nodes reach the new version.
| Downgrading after the full cluster has been upgraded is not supported. The cluster compatibility version mechanism provides an upgrade rollback path while at least one node is still on the previous version, or the compatibility version is still frozen at a previous version. |
How the Cluster Compatibility Version Works
Without a freeze, the cluster compatibility version is always the minimum version across all live nodes in the cluster. As you upgrade nodes one by one, the minimum advances when older nodes are replaced.
Sync Gateway uses the compatibility version to gate cluster-wide feature activation. Features that could cause incompatibilities with older nodes remain inactive until the compatibility version reaches the version that introduced them. New features that do not depend on metadata shared by other Sync Gateway nodes activate immediately on each upgraded node regardless of the compatibility version. These are considered node-local features, and include areas such as caching, read-only operations, general bug fixes, and performance improvements.
On a homogeneous cluster where all nodes run the same version, the compatibility version equals that version. The value is not present in the API response immediately after startup before any node has registered.
About the Freeze
Freezing pins the cluster compatibility version at its current value, regardless of which nodes you subsequently upgrade. While the version is frozen, upgrading a node does not advance the reported compatibility version.
This preserves the option to roll back any upgraded node to the previous version without data loss or invasive data operations such as bucket flushing or backup and restore.
Use the freeze when you want a safe rollback window during the upgrade. It is optional. If you do not need a rollback path, you can upgrade without freezing.
|
A freeze persists across node restarts. It is cluster-wide and stored in the cluster, not in node memory. You must unfreeze manually by calling the unfreeze endpoint. The freeze does not clear automatically when all nodes reach the new version. |
Upgrade with Cluster Compatibility Version (Safe Rollback Path)
Use this procedure when you want to preserve the option to roll back during the upgrade.
Prerequisites
-
All nodes are running Sync Gateway 4.1 or later.
-
You have Admin REST API access to the cluster.
-
See Rolling Upgrade for version requirements and the node upgrade procedure.
Procedure
Call GET /_cluster_compat_version to confirm the current state before starting.
GET /_cluster_compat_versionExample response on a homogeneous 4.1 cluster:
{
"cluster_compat_version": "4.1",
"nodes": {
"node1-uid": "4.1",
"node2-uid": "4.1",
"node3-uid": "4.1"
}
}Call POST /_cluster_compat_version/freeze to pin the version before upgrading any node.
POST /_cluster_compat_version/freezeExample response:
{
"cluster_compat_version": "4.1",
"nodes": {
"node1-uid": "4.1",
"node2-uid": "4.1",
"node3-uid": "4.1"
},
"frozen_cluster_compat_version": "4.1"
}The presence of frozen_cluster_compat_version in the response confirms the freeze is active.
For each node in the cluster, follow the steps in Rolling Upgrade.
While the freeze is in effect, cluster_compat_version remains pinned at the frozen value even as nodes come online at the new version.
Call GET /_cluster_compat_version at any time to confirm the freeze is still active and to check the individual version of each node.
Call GET /_cluster_compat_version and confirm all nodes in the nodes map show the new version.
{
"cluster_compat_version": "4.1",
"nodes": {
"node1-uid": "4.2",
"node2-uid": "4.2",
"node3-uid": "4.2"
},
"frozen_cluster_compat_version": "4.1"
}Call POST /_cluster_compat_version/unfreeze to clear the freeze.
POST /_cluster_compat_version/unfreezeExample response after a successful unfreeze:
{
"cluster_compat_version": "4.2",
"nodes": {
"node1-uid": "4.2",
"node2-uid": "4.2",
"node3-uid": "4.2"
}
}The absence of frozen_cluster_compat_version confirms the freeze has cleared.
The cluster_compat_version advances to 4.2 and new cluster-wide features introduced in 4.2 become active.
|
If the unfreeze does not fully apply, the endpoint returns a 503 with the current state.
The |
Rolling Back During an Upgrade
If you discover an issue after upgrading some nodes and the freeze is in effect, you can roll back the upgraded nodes to the previous version.
-
Downgrade the affected nodes to the previous Sync Gateway version using the same rolling process: remove from load balancer, downgrade, restart, verify, re-add.
-
The
cluster_compat_versionremains pinned at the frozen value throughout. -
Once all nodes are back on the previous version, call POST /_cluster_compat_version/unfreeze to clear the freeze.
|
Rollback is only possible while the freeze is in effect and at least one node is still on the previous version. Downgrading after calling unfreeze and completing the full cluster upgrade is not supported. |
API Reference
| Endpoint | Description |
|---|---|
Returns the current cluster compatibility version, the version of each registered node, and the frozen value if a freeze is active. |
|
Pins the cluster compatibility version at its current value. The freeze persists across node restarts. |
|
Clears the pinned version. The compatibility version resumes tracking the minimum across live nodes. Returns 503 if the unfreeze did not fully apply; retry the request. |
Required Sync Gateway RBAC role: Sync Gateway Dev Ops.