From 0074959c2b0d0f43417bf7101e5aee4118ff4ba4 Mon Sep 17 00:00:00 2001 From: Fortune Ikechi Date: Wed, 27 May 2026 17:49:08 +0100 Subject: [PATCH 1/2] DOC-14380-cluster-compat-upgrade-restructure --- modules/ROOT/nav.adoc | 5 +- .../pages/cluster-compatibility-version.adoc | 221 +++++++++++++ modules/ROOT/pages/rolling-upgrade.adoc | 161 ++++++++++ modules/ROOT/pages/upgrading.adoc | 299 +++--------------- 4 files changed, 436 insertions(+), 250 deletions(-) create mode 100644 modules/ROOT/pages/cluster-compatibility-version.adoc create mode 100644 modules/ROOT/pages/rolling-upgrade.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e41525e9..ae08f9e3 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -118,7 +118,10 @@ // - * xref:ROOT:upgrading.adoc[Upgrade] +.Upgrade + * xref:ROOT:upgrading.adoc[Overview] + * xref:ROOT:rolling-upgrade.adoc[Rolling Upgrade] + * xref:ROOT:cluster-compatibility-version.adoc[Cluster Compatibility Version] // diff --git a/modules/ROOT/pages/cluster-compatibility-version.adoc b/modules/ROOT/pages/cluster-compatibility-version.adoc new file mode 100644 index 00000000..bee3bf58 --- /dev/null +++ b/modules/ROOT/pages/cluster-compatibility-version.adoc @@ -0,0 +1,221 @@ += Cluster Compatibility Version +ifdef::show_edition[:page-edition: {release}] +ifdef::prerelease[:page-status: {prerelease}] +:page-role: +:page-content: procedural +:description: Use the cluster compatibility version to perform a rolling upgrade of Sync Gateway 4.1 without downtime and with a safe rollback path. + +include::ROOT:partial$_set_page_context.adoc[] + +:param-abstract: +:topic-group: Application Deployment +:param-related: {release-notes--xref} | {compatibility--xref} +include::ROOT:partial$_show_page_header_block.adoc[] + + +== Overview + +The cluster compatibility version is a cluster-wide value that {sgw} 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. + +NOTE: Downgrading after the full cluster has been upgraded is not supported. +The cluster compatibility version mechanism provides a rollback path only while at least one node is still on the 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. + +{sgw} 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. +Node-local features, such as revision caching and import processing, activate immediately on each upgraded node regardless of the compatibility version. + +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. + +[IMPORTANT] +==== +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 {sgw} 4.0 or later. +* You have Admin REST API access to the cluster. +* See xref:ROOT:rolling-upgrade.adoc[Rolling Upgrade] for version requirements and the node upgrade procedure. + +=== Procedure + +.Step 1: Check the current cluster compatibility version + +Call xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/get__cluster_compat_version[GET /_cluster_compat_version] to confirm the current state before starting. + +[source,bash] +---- +GET /_cluster_compat_version +---- + +Example response on a homogeneous 4.0 cluster: + +[source,json] +---- +{ + "cluster_compat_version": "4.0", + "nodes": { + "node1-uid": "4.0", + "node2-uid": "4.0", + "node3-uid": "4.0" + } +} +---- + +.Step 2: Freeze the cluster compatibility version + +Call xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/post__cluster_compat_version_freeze[POST /_cluster_compat_version/freeze] to pin the version before upgrading any node. + +[source,bash] +---- +POST /_cluster_compat_version/freeze +---- + +Example response: + +[source,json] +---- +{ + "cluster_compat_version": "4.0", + "nodes": { + "node1-uid": "4.0", + "node2-uid": "4.0", + "node3-uid": "4.0" + }, + "frozen_cluster_compat_version": "4.0" +} +---- + +The presence of `frozen_cluster_compat_version` in the response confirms the freeze is active. + +.Step 3: Upgrade each node + +For each node in the cluster, follow the steps in xref:ROOT:rolling-upgrade.adoc[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 xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/get__cluster_compat_version[GET /_cluster_compat_version] at any time to confirm the freeze is still active and to check the individual version of each node. + +.Step 4: Verify all nodes are on the new version + +Call xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/get__cluster_compat_version[GET /_cluster_compat_version] and confirm all nodes in the `nodes` map show the new version. + +[source,json] +---- +{ + "cluster_compat_version": "4.0", + "nodes": { + "node1-uid": "4.1", + "node2-uid": "4.1", + "node3-uid": "4.1" + }, + "frozen_cluster_compat_version": "4.0" +} +---- + +.Step 5: Unfreeze to commit the upgrade + +Call xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/post__cluster_compat_version_unfreeze[POST /_cluster_compat_version/unfreeze] to clear the freeze. + +[source,bash] +---- +POST /_cluster_compat_version/unfreeze +---- + +Example response after a successful unfreeze: + +[source,json] +---- +{ + "cluster_compat_version": "4.1", + "nodes": { + "node1-uid": "4.1", + "node2-uid": "4.1", + "node3-uid": "4.1" + } +} +---- + +The absence of `frozen_cluster_compat_version` confirms the freeze has cleared. +The `cluster_compat_version` advances to `4.1` and new cluster-wide features introduced in 4.1 become active. + +[NOTE] +==== +If the unfreeze does not fully apply, the endpoint returns a 503 with the current state. +The `cluster_compat_version` may still be held back. +Retry the unfreeze request. +==== + + +== 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 {sgw} version using the same rolling process: remove from load balancer, downgrade, restart, verify, re-add. +. The `cluster_compat_version` remains pinned at the frozen value throughout. +. Once all nodes are back on the previous version, call xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/post__cluster_compat_version_unfreeze[POST /_cluster_compat_version/unfreeze] to clear the freeze. + +[IMPORTANT] +==== +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 + +[cols="1,3"] +|=== +| Endpoint | Description + +| xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/get__cluster_compat_version[GET /_cluster_compat_version] +| Returns the current cluster compatibility version, the version of each registered node, and the frozen value if a freeze is active. + +| xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/post__cluster_compat_version_freeze[POST /_cluster_compat_version/freeze] +| Pins the cluster compatibility version at its current value. +The freeze persists across node restarts. + +| xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/post__cluster_compat_version_unfreeze[POST /_cluster_compat_version/unfreeze] +| 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 {sgw} RBAC role: Sync Gateway Dev Ops. + + +include::ROOT:partial$block-related-content-deploy.adoc[] + +// END -- PAGE -- cluster-compatibility-version.adoc \ No newline at end of file diff --git a/modules/ROOT/pages/rolling-upgrade.adoc b/modules/ROOT/pages/rolling-upgrade.adoc new file mode 100644 index 00000000..e4bab3a4 --- /dev/null +++ b/modules/ROOT/pages/rolling-upgrade.adoc @@ -0,0 +1,161 @@ += Rolling Upgrade +ifdef::show_edition[:page-edition: {release}] +ifdef::prerelease[:page-status: {prerelease}] +:page-role: +:page-content: procedural +:description: Step-by-step procedures for performing a rolling upgrade of a Sync Gateway cluster for each supported version. + +include::ROOT:partial$_set_page_context.adoc[] + +:param-abstract: +:topic-group: Application Deployment +:param-related: {get-started-prepare--xref} | {release-notes--xref} +include::ROOT:partial$_show_page_header_block.adoc[] + + +== About Rolling Upgrades + +A rolling upgrade is the recommended method to upgrade a {sgw} cluster. +You upgrade nodes one at a time while the cluster continues serving traffic, avoiding downtime. + +At a high level, a rolling upgrade consists of the following steps: + +. Remove the node from the load balancer or stop HTTP traffic to the node. +. Run the upgrade on that node. +. Re-add the node to the load balancer or resume traffic to the node. + +Repeat these steps for each node in the {sgw} cluster. + +[NOTE] +==== +{sgw} 4.1 introduces cluster compatibility version, which lets you perform a rolling upgrade with a safe rollback path and without reducing cluster capacity. +See xref:ROOT:cluster-compatibility-version.adoc[Cluster Compatibility Version]. +==== + + +== Upgrade to {sgw} 4.1 + +=== Prerequisites + +. Verify your Couchbase Server cluster is running 7.6.0 or later. +Bi-directional XDCR features require 7.6.6 or later. +. Verify all Couchbase Server nodes are operational before starting the {sgw} upgrade. +. Check your existing {sgw} configuration files and remove any unsupported settings: ++ +-- +* `shared_bucket_access=false` +* `allow_conflicts=true` +* `enable_star_channel=false` +-- ++ +Databases configured with these settings do not start on {sgw} 4.1. + +=== Procedure + +For each node in the cluster, repeat the following steps: + +. Remove the node from the load balancer or stop HTTP traffic to the node. +. Install {sgw} 4.1 on the node. +. Start the {sgw} service. +. Verify the node is healthy using the xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/get_-[GET /] endpoint on the Admin REST API. +. Verify all databases on the node are online. +. Re-add the node to the load balancer or resume HTTP traffic to the node. + +NOTE: Downgrading from {sgw} 4.1 to an earlier version is not supported after the full cluster has been upgraded. +If you require a rollback path during the upgrade window, use xref:ROOT:cluster-compatibility-version.adoc[Cluster Compatibility Version] before starting. + + +== Upgrade to {sgw} 4.0 + +=== Prerequisites + +. Verify your Couchbase Server cluster is running 7.6.0 or later. +Bi-directional XDCR features require 7.6.6 or later. +. Verify all Couchbase Server nodes are operational before starting the {sgw} upgrade. +. Check your existing {sgw} configuration files and remove any unsupported settings: ++ +-- +* `shared_bucket_access=false` +* `allow_conflicts=true` +* `enable_star_channel=false` +-- ++ +Databases configured with these settings do not start on {sgw} 4.0. + +=== Procedure + +For each node in the cluster, repeat the following steps: + +. Remove the node from the load balancer or stop HTTP traffic to the node. +. Update the configuration file if it contains any unsupported settings listed in the prerequisites. +. Install {sgw} 4.0 on the node. +. Start the {sgw} service. +. Verify the node is healthy using the xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/get_-[GET /] endpoint on the Admin REST API. +. Verify all databases on the node are online. +. Re-add the node to the load balancer or resume HTTP traffic to the node. + +NOTE: Downgrading from {sgw} 4.0 to earlier versions is not supported. + + +== Upgrade to {sgw} 3.1 + +=== About Persistent Configuration + +{sgw} 3.1 uses Persistent Configuration as its default operational mode. +When you start a {sgw} 3.1 node with an existing configuration file, {sgw-t} automatically converts the configuration to the persistent format. + +[CAUTION] +==== +Migration to the 3.x Persistent Configuration is a one-way process. +You cannot downgrade to a previous version after upgrading to 3.1. +==== + +Before starting the upgrade, confirm the following: + +* {sgw-t} has write access to the directory containing the existing configuration file. +{sgw-t} creates a backup of the existing configuration before writing the upgraded version. +* If your configuration file contains multiple databases, all `server` fields used to connect to Couchbase Server must match. +{sgw-t} uses the first set of credentials for the bootstrap configuration. ++ +NOTE: {sgw-t} cannot automatically upgrade configurations with multiple distinct `server` fields. +You must create the bootstrap configuration manually in this case. + +Consider the following before starting: + +* Configuration groups: most deployments use the default group. +If you require custom node groupings, add the `bootstrap_group_id` value to your configuration file before startup. +See {bootstrap-schema--xref--bootstrap-group-id}. +* TLS: {sgw} 3.0 and later enables secure TLS connections to Couchbase Server by default. +To use a non-secure connection in a test environment, set {bootstrap-schema--xref--bootstrap-use-tls-server} to `false`. +See {secure-sgw-access--xref}. +* Admin API authentication: Secure Administration requires Couchbase Server RBAC users for Admin and Metrics API access. +Configure the appropriate users before upgrading. +See {rest-api-access--xref}. + +=== Procedure + +. Start a {sgw} 3.1 node using your existing configuration properties file. ++ +{sgw-t} takes the appropriate upgrade path based on the current configuration state: ++ +[cols="1a,2a,2a", options="header"] +|=== +| Configuration status | Inference | Outcome + +| No configuration exists +| This is the first node in the default group, or with this group ID, to start. +| {sgw-s} uses the configuration file to derive and persist a configuration for this node. + +| Configuration exists in the server bucket +| A node in the default group, or with this group ID, has already started. +| {sgw-s} ignores the configuration file and uses the configuration associated with the default group or group ID provided. +|=== + +. Verify the node is healthy using the xref:ROOT:rest_api_admin_static.adoc#tag/Server/operation/get_-[GET /] endpoint on the Admin REST API. +. Re-add the node to the load balancer or resume traffic to the node. +. Repeat for each remaining node in the cluster. + + +include::ROOT:partial$block-related-content-deploy.adoc[] + +// END -- PAGE -- rolling-upgrade.adoc \ No newline at end of file diff --git a/modules/ROOT/pages/upgrading.adoc b/modules/ROOT/pages/upgrading.adoc index d6e6c3f2..a68dfaad 100644 --- a/modules/ROOT/pages/upgrading.adoc +++ b/modules/ROOT/pages/upgrading.adoc @@ -2,300 +2,101 @@ // BEGIN PAGE DEFINITION // LOCATION modules/ROOT/pages/ // PURPOSE: -// This is a standard content presentations page. -// Its name/title identify the content/topic -// PARAMETERS: -// None -// INCLUSION USAGE -- -// This module uses attributes from: -// - /modules/ROOT/pages/_partials/_define_page_index.adoc -- xref page links -// -// This module uses these inclusions: -// - /modules/ROOT/pages/_partials/_set_page_context.adoc -- std attribute environment -// - /modules/ROOT/pages/_partials/_show_page_header_block.adoc -- std text block for page header content -// - /modules/ROOT/pages/_partials/block-related-content-deploy.adoc -- std text block for page footer content -// - modules/ROOT/assets/images -- .png/.jpeg images -// INCLUSION USAGE +// Overview page for the Upgrade section. +// Summarises upgrade paths and requirements for each supported version. +// Detailed procedures are in rolling-upgrade.adoc. +// Cluster compatibility version feature is in cluster-compatibility-version.adoc. // END PAGE DEFINITION -= Upgrading Sync Gateway += Upgrade Sync Gateway :page-aliases: advance/deploy/upgrade.adoc, upgrade.adoc ifdef::show_edition[:page-edition: {release}] ifdef::prerelease[:page-status: {prerelease}] :page-role: :page-content: procedural -:page-status: Sync Gateway 4.0 -:description: This page documents various implementation details and functionalities to consider when performing an upgrade to Sync Gateway {page-component-version}. +:description: Overview of upgrade paths, version requirements, and supported approaches for upgrading Sync Gateway. include::ROOT:partial$_set_page_context.adoc[] -:sc1title: Continue with SG Replicate (no conflict resolution) -:sc2title: Continue with SG Replicate (custom conflict resolution) -:sc3title: Change to SGR-Replicate 2.0 (default conflict resolution) -:sc4title: Change to SGR-Replicate 2.0 (custom conflict resolution) - -:xref-sgw-bmk-get-started-prepare-cfg-svr: xref:{get-started-prepare--page}#configure-server.html[Configure Server for Sync Gateway] - :param-abstract: :topic-group: Application Deployment :param-related: {get-started-prepare--xref} | {get-started-install--xref} | {release-notes--xref} include::ROOT:partial$_show_page_header_block.adoc[] -== Upgrade Approaches - - -A rolling upgrade is the recommended method to upgrade a Sync Gateway cluster. -At a high level, a rolling upgrade consists of the following steps: - -. The load balancer configuration stops any HTTP traffic to the node you're upgrading. - -. The upgrade runs on the given node. - -. The load balancer configuration resumes traffic to the upgraded node. - -Those steps are then repeated for each node in the {sgw} cluster. - - -== Upgrade to 4.0 - -=== Upgrade Requirements - -. Couchbase Server 7.6.6 or later for bi-directional XDCR features. -. `shared_bucket_access=false` is no longer supported - databases do not start with `shared_bucket_access=false`. -. `allow_conflicts=true` no longer supported - databases do not start with this setting. -. `enable_star_channel=false` is no longer supported - databases do not start with this setting. - -NOTE: As with all major version upgrades, downgrading from 4.0 to earlier versions is not supported. - -==== Process - -.Prerequisites - -. Upgrade Couchbase Server cluster to 7.6.0 or later and verify all server nodes are operational. -. Test Sync Gateway connectivity with existing version to verify compatibility. - -.Step 1 - -. Remove a node from the load balancer or stop traffic to the node. -. Update the configuration file, if using unsupported settings: -- Remove `shared_bucket_access=false`. -- Remove `allow_conflicts=true`. -- Remove `enable_star_channel=false`. -. Install Sync Gateway 4.0 -. Start the Sync Gateway service. -. Verify node health via xref:rest-api:rest_api_public.adoc#tag/Server/operation/get_-[REST API]. +== Overview -.Step 2 +This section covers upgrading {sgw} to a new version. +Use the pages in this section based on what you need to do: -. Verify all databases are online. -. Re-add the node to the load balancer or resume traffic to the node. +* xref:ROOT:rolling-upgrade.adoc[Rolling Upgrade] -- Step-by-step procedures for upgrading a {sgw} cluster node by node, including version-specific requirements. +* xref:ROOT:cluster-compatibility-version.adoc[Cluster Compatibility Version] -- How to use the cluster compatibility version mechanism introduced in {sgw} 4.1 to upgrade without downtime and with a safe rollback path. -== Upgrade to 3.1 +For compatibility information, see the {compatibility--xref}. -=== Use Persistent Configuration +== Upgrade Requirements by Version -The use of 3.x's Persistent Configuration feature is strongly recommended. -It's the default operational mode when starting {sgw}. +=== {sgw} 4.1 -The feature provides a smooth upgrade path for existing users by automatically converting their existing configuration files to the new persistent configuration format. - -.One Way Upgrade -[CAUTION] --- -The migration to 3.x configuration is a ONE WAY process. -You cannot downgrade to previous versions after upgrading to 3.1. -To continue using legacy-mode configuration see: <> --- - -==== Considerations - -Before commencing your upgrade consider your requirements for -<> although most users find the default group sufficient, -<> and -<>. - -You should also: - -* Ensure {Sgw-t} has write access to the directory containing the existing configuration (the one you want to convert). -It backups the existing configuration and write the upgraded configuration. - -* Verify that, if your existing configuration has multiple databases, all of the *server* fields used to connect to *Couchbase Server* match. + -Although the connection credentials used may differ between databases, {sgw-t} only uses the *first* set of credentials for the bootstrap configuration file. -+ - -NOTE: Sync Gateway cannot automatically upgrade configurations that have multiple distinct server fields within the configuration file, and you'll need to manually create their own bootstrap configuration. - - -==== Process - -Just start a {sgw} node using your existing configuration properties file. - -On starting, {sgw-t} takes the appropriate upgrade path as shown in <>. - - -.Upgrade Paths -[#tbl-enhancedcfg,cols="1a,2a,2a", options="header"] +[cols="1,2"] |=== +| Requirement | Detail -.>| Configuration Status .>| Inference .>| Outcome - -| No configuration exists - -| This is first node in the default group or with this *group ID* to start - -| {sgw-s} uses the configuration file to derive and persist a configuration for this node. - -| Configuration exists in the Server bucket + - -| A node in the default group, or with this *group ID*, has already started - -| {sgw-s} ignores the configuration file and uses the configuration associated with the default group, or *group ID* provided. - +| Couchbase Server +| 7.6.0 or later. 7.6.6 or later required for bi-directional XDCR features. +| Unsupported settings +| The following settings are not supported and must be removed from your configuration before upgrading: + +`shared_bucket_access=false` + +`allow_conflicts=true` + +`enable_star_channel=false` |=== +NOTE: Downgrading from {sgw} 4.1 to an earlier version is not supported after the full cluster has been upgraded. +To preserve a rollback path during the upgrade window, use xref:ROOT:cluster-compatibility-version.adoc[Cluster Compatibility Version]. -[#lbl-3-0-config-grps] -==== Configuration Groups - -Whilst the provided default group suffices for most deployments {sgw} does allow for the configuration of more complex node groupings. - -Before commencing your upgrade consider your requirements for grouping {sgw} nodes within your {sgw} cluster -- see: {configuration-overview--xref--groups} - -If you want the {sgw} to associate with a specific configuration group Id, you must add the `bootstrap_group_id` value to the configuration file prior to startup -- see: {bootstrap-schema--xref--bootstrap-group-id} - -Failing to do so may result in the configuration being overridden by one configured on a different {sgw} node that has already started and registered its own configuration. - -[#lbl-3-0-config-tls] -=== Secure Server Connection - -Sync Gateway 3.0 enables secure TLS connection to Couchbase Server out-of-the-box. - -If you wish to use non-secure connection, perhaps in a test environment, you need to run {sgw} with -{bootstrap-schema--xref--bootstrap-use-tls-server} set to `false` -- see: {secure-sgw-access--xref} +=== {sgw} 4.0 -[#lbl-3-0-config-adm] -==== Secure Administration - -Secure Administration is under-pinned by the use of Couchbase Server RBAC-users to authenticate and authorize access to Admin and Metrics API feature. -This requires you set-up and configure appropriate users -- see: {rest-api-access--xref}. - -To opt-out of this, you can configure {bootstrap-schema--xref--api-admin-interface-authentication} and-or {bootstrap-schema--xref--api-metrics-interface-authentication} as `false` - - -== Couchbase Server Upgrade Paths - -NOTE: When upgrading your Couchbase Server from 4.x to 5.x, remember to create a Sync Gateway RBAC user on the server -- see: {xref-sgw-bmk-get-started-prepare-cfg-svr} -- and to include the user's credentials username/password in you Sync-Gateway-Config.json file. - -All of the different upgrade paths mentioned above assume that you're running a compatible Couchbase Server version -- see {compatibility--xref}. - -Three commonly used upgrade approaches exist for Couchbase Server. -Depending on the one you choose, there may be additional consideration to keep in mind when using Sync Gateway: - -[cols="2,1,1,5a"] +[cols="1,2"] |=== -|Approach|Downtime |Additional Machine Requirements |Impact when using Sync Gateway - -|Rolling Online Upgrade -|None -|Low -|*Potential transient connection errors:* The Couchbase Server re-balance operations can result in transient connection errors between Couchbase Server and Sync Gateway, which could result in Sync Gateway performance degradation. +| Requirement | Detail -*Potential for unexpected server errors during re-balance:* In-flight ops are lost during a fail-over due to increased potential for errors. +| Couchbase Server +| 7.6.0 or later. 7.6.6 or later required for bi-directional XDCR features. -|Upgrade Using Inter-Sync Gateway Replication -|Small amount during switchover -|High - duplicate entire cluster -|Using an XDCR (Cross Data Center Replication) approach incurs some Sync Gateway downtime, but less than other approaches where Sync Gateway is shutdown during the entire Couchbase Server upgrade. - -|Offline Upgrade -|During entire upgrade -|None -| -* Take Sync Gateway offline -* Upgrade Couchbase Server using any of the options mentioned in the xref:server:install:upgrade.adoc[Upgrading Couchbase Server] documentation. -* Bring Sync Gateway online +| Unsupported settings +| The following settings are not supported and must be removed from your configuration before upgrading: + +`shared_bucket_access=false` + +`allow_conflicts=true` + +`enable_star_channel=false` |=== -The XDCR replication must be a *one way* replication from the existing (source) Couchbase Server cluster to the new (target) Couchbase Server cluster. -No other writes can happen on the new (target) Couchbase Server cluster other than the writes from the XDCR replication. -Do not configure any Sync Gateway instances to use the new (target) Couchbase Server cluster until the last step in the process. - -. Start XDCR to do a one way replication from the existing (source) Couchbase Server cluster to the new (target) Couchbase Server cluster running the earlier version. -. Wait until the target Couchbase Server has caught up to all the writes in the source Couchbase Server cluster. -. Shutdown Sync Gateway to prevent any new writes from coming in. -. Wait until the target Couchbase Server has caught up to all the writes in the source Couchbase Server cluster -- this should happen quickly, since it will only be the residual writes in transit before the Sync Gateway shutdown. -. Reconfigure Sync Gateway to point to the target cluster. -. Restart Sync Gateway. - -Caveats: - -* *Small amount of downtime during switchover:* Since there may be writes still in transit after Sync Gateway has been shutdown, there will need to be some downtime until the target Couchbase Server cluster is caught up. -* *XDCR should be monitored:* Make sure to monitor the XDCR relationship as per xref:server:xdcr:xdcr-intro.adoc[XDCR docs]. - -== Upgrade to Shared Bucket - -=== Implementation notes for XATTRs: - -Mobile applications require additional metadata to manage security and replication. -Sync Gateway has always stored this information in the document body in previous versions. -Sync Gateway 1.5 utilizes a new feature of Couchbase Server 5.0 called XATTRs (x-attributes) to store that metadata into an external document fragment. - -Couchbase documents can have associated JSON objects called extended attributes (xattrs). -You can associate each document with zero or more extended attributes. -Three types currently exist (user, system, virtual). -Mobile Convergence uses a system extended attribute, which has the following characteristics central to convergence: - -- System xattrs share lifetime with the document metadata - when you delete a document, the system preserves system xattrs with the tombstone. -- The system allocates 1MB of storage, independent of the 20MB available for the document +NOTE: Downgrading from {sgw} 4.0 to earlier versions is not supported. -Couchbase Server stores extended attributes as part of the document and replicates them with the document (both intra-cluster replication and XDCR). -You can access extended attributes via the SDKs using the sub-document API, via command-line tools, and via views. - -They're also accessible from {sqlpp} in Couchbase Server 5.5 or above with the `().xattrs` property. -For example, `SELECT meta().xattrs._sync from travel-sample where Meta().id = "user::demo";`. - -WARNING: Sync Gateway maintains the sync metadata internally and its structure can change at any time. -Applications should not use it to drive business logic. -Sync Gateway does not support the direct {sqlpp} query in production environments. - -The xref:rest-api:rest_api_admin.adoc#tag/Document/operation/get_keyspace-_raw-docid[raw] - endpoint on Sync Gateway's Admin REST API returns both the document and its associated mobile metadata. - - -=== Configuration Changes +=== {sgw} 3.1 +[cols="1,2"] |=== -| Before | After +| Requirement | Detail -| *Sync Gateway 1.5 or above* -`shared_bucket_access: false` -| *Sync Gateway 1.5 or above* -`shared_bucket_access: true` -2+a| -After you restart Sync Gateway with the updated configuration file, Sync Gateway automatically migrates the mobile metadata for existing documents when you set `import_docs` to `true`. -To enable shared bucket access on incoming documents, set the `import_docs`: `true` property on at least one Sync Gateway node in the cluster. +| Couchbase Server +| See {compatibility--xref} for the minimum supported Couchbase Server version for {sgw} 3.1. -Enabling shared bucket access on your existing deployment is *not* reversible. -We recommend testing the upgrade on a staging environment before upgrading the production environment. +| Configuration +| {sgw} 3.1 uses Persistent Configuration by default. +Upgrading to 3.1 converts existing configuration files to the persistent format automatically. +This migration is a one-way process. +|=== -The known issue xref:product-notes:release-notes.adoc#2-5-0[CBG-394], means that the upgrade will *require downtime* when enabling shared bucket access on an existing deployment that is running with GSI indexing. This is to allow all documents to migrate, using index-based data requests whilst migration is in progress could result in an incomplete data set being returned (containing only those docs migrated at the time of the request). You are advised to schedule a maintenance window to allow time for migration to complete. -| *Sync Gateway 2.1 to 3.2* -`num_index_replicas: 2` (or n) -| *Sync Gateway 3.3 or later* -`index.num_replicas: 2` (or n) -2+| -After you restart Sync Gateway with the updated configuration file, Sync Gateway automatically updates the number of Index Replicas in the Couchbase Server cluster. +== Upgrading Couchbase Server -As of Sync Gateway 3.3, `num_index_replicas` still works, but this option has been deprecated in favor of `index.num_replicas`. -|=== +If you also need to upgrade Couchbase Server, refer to the xref:server:install:upgrade.adoc[Upgrading Couchbase Server] documentation for supported approaches. +When running a Couchbase Server rolling upgrade alongside {sgw}, Server rebalance operations can cause transient connection errors between {sgw} and Couchbase Server. include::ROOT:partial$block-related-content-deploy.adoc[] -// END -- PAGE -- upgrading.adoc - +// END -- PAGE -- upgrading.adoc \ No newline at end of file From 13e4978c7967c82c959e6876308fa9c3b03d7be7 Mon Sep 17 00:00:00 2001 From: Fortune Ikechi Date: Tue, 12 May 2026 13:40:18 +0100 Subject: [PATCH 2/2] DOC-14280-add docker for sgw (#968) * add docker for sgw * Update modules/start-here/pages/get-started-install-docker.adoc Co-authored-by: Ben Brooks * Update modules/start-here/pages/get-started-install-docker.adoc Co-authored-by: Ben Brooks * update the text * update text to style guide --------- Co-authored-by: Ben Brooks (cherry picked from commit 561bb67a53eb09814bd2d349efe60584c3d5ff04) --- modules/ROOT/nav.adoc | 3 + .../pages/get-started-configure.adoc | 3 +- .../pages/get-started-install-docker.adoc | 204 ++++++++++++++++++ .../start-here/pages/get-started-install.adoc | 5 +- 4 files changed, 212 insertions(+), 3 deletions(-) create mode 100644 modules/start-here/pages/get-started-install-docker.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index ae08f9e3..eeb21bdc 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -12,7 +12,10 @@ .Start Here! // * xref:ROOT:index.adoc[Quick Links] + +.Start Here! * xref:start-here:get-started-prepare.adoc[Prepare] +* xref:start-here:get-started-install-docker.adoc[Deploy with Docker] * xref:start-here:get-started-install.adoc[Install] * xref:start-here:get-started-configure.adoc[Configure] * xref:start-here:get-started-explore.adoc[Explore] diff --git a/modules/start-here/pages/get-started-configure.adoc b/modules/start-here/pages/get-started-configure.adoc index 84b1f5c6..f7d4954d 100644 --- a/modules/start-here/pages/get-started-configure.adoc +++ b/modules/start-here/pages/get-started-configure.adoc @@ -29,8 +29,7 @@ include::ROOT:partial$_show_page_header_block.adoc[] NOTE: Make sure you have read and acted-upon the information and steps in {get-started-prepare--xref} and {get-started-install--xref} before proceeding. These instructions are for local or server based deployments. -If you're using a container such as Docker, see this -https://blog.couchbase.com/using-docker-with-couchbase-mobile/[blog post on using Docker with Couchbase Mobile] for additional details. +If you're using Docker, see xref:start-here:get-started-install-docker.adoc[Deploy Sync Gateway with Docker] instead. :param-page: {page-relative-src-path} diff --git a/modules/start-here/pages/get-started-install-docker.adoc b/modules/start-here/pages/get-started-install-docker.adoc new file mode 100644 index 00000000..26508354 --- /dev/null +++ b/modules/start-here/pages/get-started-install-docker.adoc @@ -0,0 +1,204 @@ += Deploy Sync Gateway with Docker +ifdef::show_edition[:page-edition: {release}] +ifdef::prerelease[:page-status: {prerelease}] +:page-role: +:Description: pass:q[Deploy _Sync Gateway_ using Docker; securely sync enterprise data from cloud to edge.] +:page-type: procedural + + +include::ROOT:partial$_set_page_context.adoc[] + + +// BEGIN -- Page Attributes +:xref-pfx: {sgw--xref}: +:xref-sgw-bmk-logging-console: xref:{sgw-pg-logging}#lbl-console-logs[Console Logs] +// END -- Page Attributes + + +// BEGIN -- Page Heading +:topic-group: Start Here! +:param-abstract: pass:q[This is an alternative to the *Install* and *Configure* steps in the _Start Here!_ topic group. It deploys _{sgw}_ and _{cbs}_ using Docker containers.] + +include::ROOT:partial$_show_page_header_block.adoc[] +// END -- Page Heading + +.Preparatory Steps +NOTE: Make sure you have read and acted-upon the information in {get-started-prepare--xref} before proceeding. + +:param-page: {page-relative-src-path} +include::ROOT:partial$topic-group-get-started.adoc[] + + +== Before You Begin + +Make sure you have: + +* Docker installed on your machine. +See the https://docs.docker.com/get-docker/[Docker installation guide, window=_blank] for instructions. +* The bucket name and RBAC credentials from {get-started-prepare--xref}. + + +== Deploy Couchbase Server + +=== Create a Docker Network + +Create a Docker bridge network so that {cbs-te} and {sgw-te} containers can communicate. + +[{snippet-header}] +---- +docker network create --driver bridge couchbase +---- + +=== Run Couchbase Server + +Run {cbs} in a Docker container on the `couchbase` network. + +[{snippet-header}] +---- +docker run -d --name cb-server \ + --network couchbase \ + -p 8091-8097:8091-8097 \ + -p 11210-11211:11210-11211 \ + couchbase/server +---- + +=== Configure Couchbase Server + +Once {cbs} is running, open the Admin UI at `+http://localhost:8091+` and complete the setup described in {get-started-prepare--xref}, including: + +* Creating a cluster +* Creating a bucket +* Creating an RBAC user for {sgw} + +NOTE: Note the bucket name and RBAC credentials. You will need them in the next step. + + +== Deploy Sync Gateway + +=== Create a Configuration File + +Create a configuration file named `sync-gateway-config.json` on your local machine. + +Replace `` and `` with the credentials you set up in {cbs}. + +[#sample-cfg] +.Sync Gateway Bootstrap Config for Docker +==== + +[source, json] +---- +{ + "bootstrap": { + "server": "couchbase://cb-server", // <.> + "username": "", // <.> + "password": "", + "use_tls_server": false // <.> + }, + "logging": { + "console": { + "enabled": true, + "log_level": "info", + "log_keys": ["*"] + } + } +} +---- + +<.> Use the {cbs} container name `cb-server` as the hostname. +Docker resolves this name within the `couchbase` network. + +<.> Use the RBAC credentials you created when you configured {cbs}. + +<.> TLS is disabled for local development. +For production deployments, enable TLS and use `couchbases://cb-server` instead. + +==== + +=== Run Sync Gateway + +Run {sgw} in a Docker container, mounting the configuration file you created. + +Replace `/path/to/sync-gateway-config.json` with the absolute path to the file on your local machine. + +[{snippet-header}] +---- +docker run -d --name sync-gateway \ + --network couchbase \ + -p 4984-4985:4984-4985 \ + -v /path/to/sync-gateway-config.json:/etc/sync_gateway/config.json \ + couchbase/sync-gateway \ + /etc/sync_gateway/config.json +---- + +NOTE: Port 4985 is the {sgw} Admin port. By default it is only accessible from within the container. Do not expose port 4985 to external traffic in production environments. + + +== Verify the Connection + +. Point your browser to the {sgw} public port: ++ +[{snippet-header}] +---- +http://localhost:4984 +---- + +. Confirm that you receive a response similar to this: ++ +[{snippet-header}] +---- +{"couchdb":"Welcome","vendor":{"name":"Couchbase Sync Gateway","version":"{version}"},"version":"Couchbase {sgw}/{version-full} EE"} +---- ++ +If there are issues, select the {xref-sgw-bmk-logging-console} for more information. + + +== Manage Your Containers + +=== Stop Containers + +[{snippet-header}] +---- +docker stop sync-gateway +docker stop cb-server +---- + +=== Start Containers + +Start {cbs} before {sgw}. + +[{snippet-header}] +---- +docker start cb-server +docker start sync-gateway +---- + +NOTE: If {cbs} is stopped for an extended period, {sgw} loses the connection. +Restart {sgw} after restarting {cbs}. + +=== Update the Sync Gateway Configuration + +To update the {sgw} configuration, stop and remove the container, then re-run it with the updated configuration file. + +[{snippet-header}] +---- +docker stop sync-gateway +docker rm sync-gateway +---- + +Then repeat <>. + + +== Next Steps + +Now that you have {sgw} running in Docker, continue to {get-started-explore--xref} to add a database configuration, create users, and run a CRUD cycle to confirm sync is working end-to-end. + +From there, you can explore more complex scenarios: + +* Learn more about {sgw}'s {configuration-schema-bootstrap--xref} +* Learn how to {sync-with-couchbase-server--xref} +* Implement access controls -- see: {users--xref}, {roles--xref}, and the {sync-function--xref} + + +// BEGIN -- Page Footer +include::ROOT:partial$block-related-content-deploy.adoc[] +// END -- Page Footer \ No newline at end of file diff --git a/modules/start-here/pages/get-started-install.adoc b/modules/start-here/pages/get-started-install.adoc index 9cc15915..3dd01aad 100644 --- a/modules/start-here/pages/get-started-install.adoc +++ b/modules/start-here/pages/get-started-install.adoc @@ -61,6 +61,9 @@ include::ROOT:partial$_show_page_header_block.adoc[] .Preparatory Steps NOTE: Make sure you have read and acted-upon the information in {get-started-prepare--xref} before proceeding. +These instructions are for local or server based deployments. +If you're using Docker, see xref:start-here:get-started-install-docker.adoc[Deploy Sync Gateway with Docker] instead. + :param-page: {page-relative-src-path} include::ROOT:partial$topic-group-get-started.adoc[] @@ -597,7 +600,7 @@ To change the default configuration file path of an existing Sync Gateway servic For Mac OS this will be the `.plist` file `com.couchbase.mobile.sync_gateway.plist`. .One way to do this would be: -. Ensure the new file path includes a useable Sync Gateway configuration file +. Make sure the new file path includes a useable Sync Gateway configuration file . Within a terminal, stop the service -- see: <> . Copy the existing `com.couchbase.mobile.sync_gateway.plist` file to a safe location as a back-up . Open the `com.couchbase.mobile.sync_gateway.plist` file in an editor. You'll need to use `sudo`