From bee27720e97cc9414c063d090c1e71982ecaffb2 Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Mon, 15 Dec 2025 20:17:25 +0530 Subject: [PATCH 01/10] Updated the concept-upgrade adoc file --- modules/ROOT/pages/concept-upgrade.adoc | 378 ++++++------------------ 1 file changed, 93 insertions(+), 285 deletions(-) diff --git a/modules/ROOT/pages/concept-upgrade.adoc b/modules/ROOT/pages/concept-upgrade.adoc index 2358c4d3..6ff04a6b 100644 --- a/modules/ROOT/pages/concept-upgrade.adoc +++ b/modules/ROOT/pages/concept-upgrade.adoc @@ -7,340 +7,148 @@ This includes upgrading the Couchbase Server version and also related Kubernetes == Upgrading Couchbase Server The Couchbase Server version can be xref:howto-couchbase-upgrade.adoc[upgraded] by the Operator. +To upgrade a Couchbase Server cluster, in the CouchbaseCluster manifest, change the `couchbasecluster.spec.image` field to the upgrade version you want. +The Operator upgrades the pods that run Couchbase Server in the Couchbase cluster. +If necessary, you can roll back the cluster to the previous version by reverting changes made to the image field. +The Operator then performs the rollback by reversing the upgrade process and applying the configured upgrade controls to the pods running the earlier cluster version. -Upgrades may be performed using one of a number of different strategies as specified by xref:resource/couchbasecluster.adoc#couchbaseclusters-spec-upgradestrategy[`couchbaseclusters.spec.upgradeStrategy`] in the `CouchbaseCluster` resource: +For more granular control, use `spec.upgrade` in the CouchbaseCluster manifest resource to manage the upgrade process. -* InPlaceUpgrade performs an in-place upgrade on one, or more, pods at a time -* Rolling upgrades upgrade one, or more, pods at a time -* Immediate upgrades upgrade all pods at the same time +[#spec-upgrade-example] +=== spec.upgrade Example -For rolling and immediate upgrades, the process is as follows: - -* One or more candidate pods are selected -* New pods are created for each of the candidates with the same Couchbase configuration as the existing ones -* Data is rebalanced from the old pods to the new ones -* The candidate pods are deleted - -For in place upgrades, the process is as follows: - -* One or more candidate pods are selected -* Each candidate is failed over and updated with the new version -* Each PVC associated with the candidate is updated with the new version -* Operator performs an in place upgrade on the candidate - -When using rolling upgrades, performing the operation one pod at a time, risk is limited in the event of an issue, and can be rolled back. -A rolling upgrade requires the least network and compute overhead, so will affect client operation less. - -When using immediate upgrades, there is a greater risk, and requires greater resource during the upgrade, however the operation itself is significantly faster. -Immediate upgrades may have an undesired effect on client performance as all pods in the cluster are undergoing upgrade at the same time. - -When using in-place upgrade, the pods and PVCs are updated to use the new version. This is quicker than a rolling upgrade and will retain the same PVCs (data retained). -In-place upgrade cannot be used in conjunction with immediate upgrades. The validator will fail the request if immediate upgrade strategy and in-place upgrade process are both specified. -The same pod names and networking settings will be retained when the pod is restarted by the operator. - -You can balance time against risk by tailoring rolling updates with the xref:resource/couchbasecluster.adoc#couchbaseclusters-spec-rollingupgrade[`couchbaseclusters.spec.rollingUpgrade`] configuration parameter. -This allows rolling upgrades to upgrade 2 pods at a time, or 20% of the cluster at a time, for example. - -[NOTE] -==== -In-place upgrades are a volatile process that can lead to interruptions in service. It should not be used when there are less than 2 data nodes defined or data loss -may occur. -==== - -=== How to Upgrade a cluster - -To upgrade a cluster, you need to modify the CouchbaseCluster resource to specify the new version of Couchbase Server that you want to upgrade to. -This can be done by updating the `spec.image` field in the CouchbaseCluster manifest to the new version. - -For example, if you were upgrading from version 7.2.4 to 7.6.0 then the CouchbaseCluster resource needs to be updated as follows: +The following is a `spec.upgrade` example in the CouchbaseCluster manifest for an upgrade process: [source,yaml] ---- -apiVersion: couchbase.com/v2 -kind: CouchbaseCluster -metadata: - name: my-couchbase-cluster -spec: - image: couchbase/server:7.6.0 +upgrade: + upgradeProcess: SwapRebalance + upgradeStrategy: RollingUpgrade + rollingUpgrade: + maxUpgradable: 1 + maxUpgradablePercent: 100% + stabilizationPeriod: 10s + previousVersionPodCount: 0 + upgradeOrderType: Nodes + upgradeOrder: + - node-1 + - node-2 ---- -=== Couchbase Server Upgrade Constraints - -Not all upgrade paths are supported by Couchbase Server. -The Operator enforces the following constraints on Couchbase Server version upgrades. +The upgrade example explanation is as follows: -* Upgrades must be an upgrade, downgrades are not supported due to potential protocol incompatibility, for example: -** 5.5.0 to 5.5.3 is allowed -** 5.5.3 to 5.5.0 is not allowed -* Upgrades must not cross multiple major version boundaries, for example: -** 5.x.x to 6.x.x is allowed -** 5.x.x to 7.x.x is not allowed -* Couchbase Server versions cannot be changed during an upgrade +* `upgradeProcess` supports `SwapRebalance` or `InPlaceUpgrade`, and defaults to `SwapRebalance` when you don't specify a value. +The selected `upgradeStrategy` determines how `SwapRebalance` creates pods running the upgraded version. +To use `InPlaceUpgrade`, set the strategy to `rollingUpgrade`. -Refer to the Couchbase Server xref:server:install:upgrade.adoc[upgrade documentation] for more information about direct upgrade paths. +** During a `SwapRebalance`, the Operator selects one or more candidate pods and creates new pods for each candidate. +The Operator rebalances data from the existing pods to the new pods and then deletes the candidate pods. -[NOTE] -==== -Modifying the Couchbase Server version during an upgrade is permitted only if the end result is a roll-back to the previous version. -==== +** During an `InPlaceUpgrade`, the Operator selects one or more candidate pods and fails them over. +The Operator detaches the volumes from those pods, replaces them with pods running the new cluster version, and rebinds the existing volumes to the new pods. +This process completes faster than a `rollingUpgrade`, and the Operator retains the pod names and network settings for the updated pods. -=== Rollback +* `upgradeStrategy` determines how `SwapRebalance` creates new pods by using either `RollingUpgrade` or `ImmediateUpgrade`. +To use `InPlaceUpgrade`, set the strategy to `rollingUpgrade`. -The Couchbase Operator provides the capability to roll back while it is in progress. A rollback can only be performed if the upgrade is in progress and has not yet completed. Once a cluster has fully upgraded to the new version the cluster can no longer be downgraded to a previous version. A rollback will simply replace the nodes on the new version and replace them with nodes with the version they had before an upgrade was started. +** `rollingUpgrade` upgrades a predetermined number of pods at a time, which limits risk and simplifies rollback. +Because this strategy uses the least network and compute resources, it minimizes impact on client operations. -==== How to Roll Back an Upgrade +** `ImmediateUpgrade` increases risk and resource utilization during the upgrade but completes the operation faster. +Because the strategy upgrades all pods at the same time, it can cause an adverse impact on client performance. -To initiate a rollback, you need to modify the CouchbaseCluster resource to specify the previous version of Couchbase Server that was running before the upgrade started. This can be done by updating the `spec.image` field in the CouchbaseCluster manifest to the previous version. +* `StabilizationPeriod` lets you control how long the Operator waits between upgrade cycles and gives you time to check cluster health and service availability. -For example, if you were upgrading from version 7.2.4 to 7.6.0 and encountered issues, you can roll back to version 7.2.4 by updating the manifest as follows: - -[source,yaml] ----- -apiVersion: couchbase.com/v2 -kind: CouchbaseCluster -metadata: - name: my-couchbase-cluster -spec: - image: couchbase/server:7.2.4 ----- - -After applying this change, the operator will begin the rollback process. - -=== Controlled Upgrades - -The Operator provides the capability to control the upgrade process by upgrading specific server classes at a time, this gives the ability to control the upgrade process and ensure that the upgrade process is controlled. For example, it is possible to upgrade the data nodes first, then the query nodes, and finally the index nodes. - -Whilst performing a controlled upgrade the cluster will be in a mixed state with different versions of Couchbase Server running at the same time. This time should be kept to a minimum to avoid potential issues with the cluster. - -==== How to Perform a Controlled Upgrade -To perform a controlled upgrade you need to first modify the CouchbaseCluster Image to specify the image that you want to upgrade to. This can be done by updating the `spec.image` field in the CouchbaseCluster manifest. You can then specify the server classes that you want to upgrade first by updating the `spec.servers.image` to the older image for the server classes you do not want to be upgraded first. You can explicitly update `spec.servers.image` for the server classes that you want to upgrade first, alternatively if the image is not specified for a server class then the image specified in `spec.image` will be used. - -.Example `CouchbaseCluster` Resource with three Server Classes -[source,yaml] ----- -apiVersion: couchbase.com/v2 -kind: CouchbaseCluster -metadata: - name: cb-example -spec: - image: couchbase/server:7.2.4 - ... - servers: - - size: 3 - name: data - services: - - data - - size: 3 - name: index - services: - - index - - size: 3 - name: query - services: - - query ----- +* `PreviousVersionPodCount` instructs the Operator to keep a fixed number of pods running the previous cluster version. +This setting supports rollbacks or an extended `StabilizationPeriod` for the final pods during a cluster upgrade. +Couchbase Server considers the upgrade process complete only when all pods run the new cluster version. +During this time, the Operator marks the cluster as Mixed Mode, which may restrict some features. -For the example above if you want to upgrade the data nodes first, then the query nodes, and finally the index nodes you can update the `CouchbaseCluster` resource as follows: +* `UpgradeOrderType` defines the sequence the Operator uses to upgrade pods to the new cluster version. +It determines how the Operator interprets `UpgradeOrder` and must be set to Nodes, ServerGroups, ServerClasses, or Services. +The Operator follows the sequence specified in `UpgradeOrder` and applies the default ordering to any items not listed. -.Example `CouchbaseCluster` Resource with Controlled Upgrade data nodes first -[source,yaml] ----- -apiVersion: couchbase.com/v2 -kind: CouchbaseCluster -metadata: - name: cb-example -spec: - image: couchbase/server:7.6.0 # <.> - ... - servers: - - size: 3 - name: data - services: - - data - - size: 3 - name: index - image: couchbase/server:7.2.4 # <.> - services: - - index - - size: 3 - image: couchbase/server:7.2.4 # <.> - name: query - services: - - query ----- +NOTE: `InPlaceUpgrade` can interrupt service and increase the risk of data loss. +Use this process only when the cluster has at least two nodes running the Data Service. -<.> The cluster image needs to be the latest version that you want to upgrade to. +=== How to Upgrade a Cluster -<.> The image for the index server class is set to the older version to ensure that the index nodes are not upgraded yet. +To upgrade a cluster, modify the CouchbaseCluster manifest by setting the `spec.image` field to the Couchbase Server version you want. -<.> The image for the query server class is set to the older version to ensure that the query nodes are not upgraded yet. +For example, if you are upgrading Couchbase Server version from 7.6.7 to 8.0.0, then update the manifest resource as follows: -.Example `CouchbaseCluster` Resource with Controlled Upgrade Upgrading query nodes second [source,yaml] ----- +--- apiVersion: couchbase.com/v2 kind: CouchbaseCluster metadata: - name: cb-example + name: my-couchbase-cluster spec: - image: couchbase/server:7.6.0 - ... - servers: - - size: 3 - name: data - services: - - data - - size: 3 - name: index - image: couchbase/server:7.2.4 # <.> - services: - - index - - size: 3 - name: query - services: - - query ----- + image: couchbase/server:8.0.0 +--- -<.> The image for the index server class is set to the older version to ensure that the index nodes are not upgraded yet. +During an upgrade or when the cluster runs in Mixed Mode through `PreviousVersionPodCount`, Couchbase Server disables bucket storage backend migrations. +Couchbase Server also disables changes to sidecar containers such as Cloud Native Gateway and Fluent Bit. -.Example `CouchbaseCluster` Resource with Controlled Upgrade Upgrading index nodes last -[source,yaml] ----- -apiVersion: couchbase.com/v2 -kind: CouchbaseCluster -metadata: - name: cb-example -spec: - image: couchbase/server:7.6.0 - ... - servers: - - size: 3 - name: data - services: - - data - - size: 3 - name: index - services: - - index - - size: 3 - name: query - services: - - query ----- +See xref:server:install/upgrade.adoc#supported-upgrade-paths[Upgrade Paths] for more information about the permitted upgrade paths in Couchbase Server. -==== How to Perform a Controlled Rollback +NOTE: You can modify the Couchbase Server version during an upgrade only to roll back to the previous cluster version. -The Operator also allows you to perform a controlled rollback. To perform a controlled rollback you would performed the controlled rollback steps in reverse. The following examples shows how to perform a controlled rollback on a example cluster where all the server classes but one have upgraded to the new version. Note that once a cluster is fully upgraded to the new version a rollback is no longer possible. +=== Rollback -.Example Starting `CouchbaseCluster` Resource for Controlled Rollback -[source,yaml] ----- -apiVersion: couchbase.com/v2 -kind: CouchbaseCluster -metadata: - name: cb-example -spec: - image: couchbase/server:7.6.0 # <.> - ... - servers: - - size: 3 - name: data - services: - - data - - size: 3 - name: index - image: couchbase/server:7.2.4 # <.> - services: - - index - - size: 3 - name: query - services: - - query ----- +The Operator supports rolling back an upgrade that's in progress. +You can perform a rollback only while some pods still run the previous cluster version, which occurs only during an upgrade or when the cluster runs in mixed mode. +After the cluster upgrade to new version is complete, it cannot be rolled back to its old version. +To roll back, the Operator replaces the newly created pods with pods running the previous version and follows the strategy, process, and ordering defined in the <<#spec-upgrade-example,spec.upgrade example>>. -<.> The cluster image is the latest version that is being upgraded to. +==== How to Rollback a Cluster -<.> The image for the index server class is set to the older version indicating that the index nodes are not upgraded yet. +To initiate a rollback, modify the CouchbaseCluster manifest by setting the `spec.image` field to the Couchbase Server version that was running before the upgrade started. +For example, you were upgrading Couchbase Server version from 7.6.7 to 8.0.0, and encountered issues. +If these issues require rollback, update the `spec.image` field to change the version back to 7.6.7 in the manifest as follows: -.Example `CouchbaseCluster` Resource Controlled Rollback Query Nodes [source,yaml] ----- +--- apiVersion: couchbase.com/v2 kind: CouchbaseCluster metadata: - name: cb-example + name: my-couchbase-cluster spec: - image: couchbase/server:7.6.0 # <.> - ... - servers: - - size: 3 - name: data - services: - - data - - size: 3 - name: index - image: couchbase/server:7.2.4 - services: - - index - - size: 3 - name: query - image: couchbase/server:7.2.4 # <.> - services: - - query ----- + image: couchbase/server:7.6.7 +--- -<.> During a controlled rollback the cluster image should stay as the version that was being upgraded to. If this is changed to the older version then the cluster will all be rolled back to the older version without control over the server class order. - -<.> The image for the query server class is set to the older version indicating that the query nodes should be rolled back next. +=== Controlled Upgrades -.Example `CouchbaseCluster` Resource Controlled Rollback Remaining Data Nodes -[source,yaml] ----- -apiVersion: couchbase.com/v2 -kind: CouchbaseCluster -metadata: - name: cb-example -spec: - image: couchbase/server:7.2.4 # <.> - ... - servers: - - size: 3 - name: data - services: - - data - - size: 3 - name: index - services: - - index - - size: 3 - name: query - services: - - query ----- +The Operator lets you control the upgrade process by using the fields in `couchbasecluster.spec.upgrade`. +For example, as an Administrator, you can use these fields to upgrade pods based on their availability region or the Couchbase Server services they run. +Also, you can upgrade pods running the Data Service before those running the Query Service, or upgrade specific pods in a defined order. -<.> As there is only one server class left to rollback the cluster image can be set to the older version and the remaining server nodes in the data class will be rolled back. +NOTE: While the cluster runs pods on two versions, the Operator marks the cluster as Mixed Mode and restricts features such as bucket migration and sidecar changes. +Keep the time spent in this mode to a minimum. -== Upgrading Pods +=== Upgrading Pods -In Kubernetes pods are immutable -- they cannot be modified once they are created. -If a `CouchbaseCluster` configuration value is modified that would also modify the underlying pod, then the Operator must create a new pod to replace the old one that does not match the required specification. -Pod upgrades work in exactly the same way as an upgrade to the Couchbase Server version; in fact upgrading the Couchbase Server image is just a subset of modifying any other pod specification parameter. +Kubernetes pods are immutable. +When you modify the CouchbaseCluster manifest in a way that requires pod replacement, the Operator creates new pods by using the same process that of the upgrade to replace pods running the previous version. +Upgrading Couchbase Server is only a subset of modifying any other pod specification parameter. -The Operator compares the required pod specification with the one used to create the original pod, a candidate is selected if the specifications differ. -The Operator therefore can perform the following tasks: +The Operator builds pod specifications from the manifest and compares them with the existing pods in the cluster. +The Operator selects candidate pods when their specifications differ and can then perform the following tasks: +* Modification of scheduling constraints * Modification of environment variables -* xref:concept-scheduling.adoc[Modification of scheduling constraints] -* xref:concept-memory-allocation.adoc[Modification of memory constraints] -* xref:concept-tls.adoc[Enabling and disabling of TLS] -* xref:concept-persistent-volumes.adoc[Enabling and disabling of persistent storage] +* Modification of memory constraints +* Modification of Couchbase services +* Enabling and disabling of TLS +* Enabling and disabling of persistent storage -This mechanism allows a cluster to be used from evaluation right up to production, with features enabled as they are required, without service disruption. +This mechanism lets you use a cluster from evaluation through production and enable features as needed without service disruption. -== Upgrading Persistent Volumes +=== Upgrading Persistent Volumes -Online persistent volume resizing support is not yet available in all supported versions of Kubernetes. -As a result the Operator supports xref:howto-persistent-volume-resize.adoc[persistent volume resizing] using a similar mechanism to <>. -The Operator will detect a modification to the specification of a persistent volume template and schedule a pod upgrade in order to satisfy the request. +The Operator supports volume modifications by using the same mechanism as pod upgrades. +When you change the manifest in a way that requires updates to persistent volumes, the Operator upgrades the affected pods to apply those changes. +If the storage class and Kubernetes cluster support persistent volume resizing, you can expand in-use persistent volumes in place by setting `couchbasecluster.spec.enableOnlineVolumeExpansion` without upgrading the pods. -During an in-place upgrade, the PVC will be updated to include the updated image and couchbase server versions. The size of the PVC and data within it will not be edited. +During an `InPlaceUpgrade`, the Operator updates the PVCs to reflect the new image and Couchbase Server version. +The Operator changes the PVC size or stored data only when the cluster manifest requires those updates. \ No newline at end of file From ffe4ea39fa99f037216c22b7485dcf0750a2af54 Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Tue, 16 Dec 2025 15:55:28 +0530 Subject: [PATCH 02/10] Started working on howto --- .../ROOT/pages/howto-couchbase-upgrade.adoc | 184 ++++++++++++++++-- 1 file changed, 165 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/howto-couchbase-upgrade.adoc b/modules/ROOT/pages/howto-couchbase-upgrade.adoc index bfe39fb1..4877acc1 100644 --- a/modules/ROOT/pages/howto-couchbase-upgrade.adoc +++ b/modules/ROOT/pages/howto-couchbase-upgrade.adoc @@ -3,52 +3,198 @@ include::partial$constants.adoc[] [abstract] -How-to upgrade Couchbase Server to a newer version. +How-to upgrade Couchbase Server to a later version. -Given the existing configuration: +You can upgrade Couchbase Server by changing the `spec.image` field in the cluster manifest to a new version. +While the upgrade is in progress and some pods still run the previous version, you can roll back the cluster to that previous version. +The `spec.upgrade` section of the cluster manifest provides controls for granular management of the upgrade process. +Before you upgrade, review the upgrade xref:concept-upgrade.adoc[concepts] and the available controls. -[source,yaml,subs="attributes,verbatim"] +NOTE: During an upgrade or rollback, when the cluster runs 2 Couchbase Server versions, the Operator marks the cluster as Mixed Mode. +In this state, the Operator disables sidecar pod modifications and bucket storage backend migrations. + +== Upgrading a Cluster + +The following is the existing configuration: + +[source,yaml] ---- apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:{couchbase-version-upgrade-from} # <.> + image: couchbase/server:7.6.8 +---- + +<.> The image can be modified to any valid Couchbase Server image. + +[source,yaml] ---- +apiVersion: couchbase.com/v2 +kind: CouchbaseCluster +spec: + image: couchbase/server:8.0.0 # <.> +---- + +<.> The modification will trigger the Operator to compare existing pod specifications, which use the old image, to new pod specifications, which will use the new image. Since they don't match, by default the Operator will begin a SwapRebalance upgrade process using the RollingUpgrade strategy. This creates new pods and rebalances them into the cluster before ejecting the old pods. -<.> xref:resource/couchbasecluster.adoc#couchbaseclusters-spec-image[`couchbaseclusters.spec.image`] can be modified to any valid Couchbase Server image, in this example we want to upgrade the version only. +=== In Place Upgrade +Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: -[source,yaml,subs="attributes,verbatim"] +[source,yaml] ---- apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:{couchbase-version} # <.> + image: couchbase/server:8.0.0 # <.> + upgrade: + upgradeProcess: InPlaceUpgrade # <.> ---- -<.> The modification will trigger the Operator to detect that existing pod specifications do not match the new pod specifications. -This will perform a xref:concept-upgrade.adoc#upgrading-couchbase-server[rolling upgrade] of Couchbase Server. +<.> The version we want to upgrade to. +<.> Inform the Operator we want to perform in-place upgrades of the existing pods. This re-creates pods in-place using the same name and the same persistent volume. + +=== Rolling Upgrade Controls + +Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: + +[source,yaml] +---- +apiVersion: couchbase.com/v2 +kind: CouchbaseCluster +spec: + image: couchbase/server:8.0.0 <.> + upgrade: + upgradeProcess: SwapRebalance + upgradeStrategy: RollingUpgrade + rollingUpgrade: <.> + maxUpgradable: 3 <.> + maxUpgradablePercent: 10 <.> +---- + +<.> The version we want to upgrade to. +<.> couchbasecluster.spec.upgrade.rollingUpgrade has two options. Either or both can be configured and the Operator will upgrade the lower number of pods per cycle. +<.> Configure Operator to only upgrade 3 pods at a time. +<.> Configure Operator to upgrade at most 10% of pods at a time relative to the total cluster size, rounded down. +If the above couchbasecluster.spec.upgrade.rollingUpgrade was used on a cluster with 10 pods, only 1 would be upgraded at a time, as the percentage value of the total is lower than the fixed number and therefore takes precedence. If however we had a cluster with 60 pods, the Operator would upgrade 3 at a time as the fixed number is now lower than the percentage. + +=== Granular Controls -== In Place Upgrade -Given the existing configuration: +Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: -[source,yaml,subs="attributes,verbatim"] +[source,yaml] ---- apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:{couchbase-version-upgrade-from} - upgradeProcess: InPlaceUpgrade # <.> + image: couchbase/server:8.0.0 <.> + upgrade: + upgradeProcess: SwapRebalance + upgradeStrategy: RollingUpgrade + rollingUpgrade: + maxUpgradable: 1 + maxUpgradablePercent: 20 + stabilizationPeriod: 5m <.> + previousVersionPodCount: 4 <.> + upgradeOrderType: Nodes <.> + upgradeOrder: <.> + - cb-instance-3 + - cb-instance-1 + - cb-instance-2 ---- -<.> This field will inform the operator that we want to perform an in-place upgrade of the existing pods. +<.> The version we want to upgrade to. +<.> The Operator will wait for this period of time between each upgrade cycle. In this instance, every time an upgrade cycle occurs, there will be a 5 minute wait until the next one. During this period, normal Operator functions, other than those that are disabled during upgrades will continue to run. +<.> The Operator will leave 4 pods on the previous version and not upgrade them. This might be useful if you want an extended stabilization period for a set number of nodes. Couchbase Server and Operator will not consider an upgrade complete until all pods are running on the new/same version. Features only available on the upgraded version will not be available until this is the case. +<.> Determine the order that the Operator will upgrade pods, either by pod (Couchbase node) name, server group, server class or by the Couchbase services running on a pod. You might want to upgrade pods in a specific availability zone first before others, or perhaps your pods running the data service should be upgraded before those with the index service. +<.> Depending on the upgradeOrderType, this field is a non-exhaustive list of the order Operator should upgrade pods by that type. In this case, the Operator will upgrade pods by Node name, meaning cb-instance-3 will be upgraded first, followed by cb-instance-1 and finally cb-instance-2. Any remaining pods that aren’t selected by the list will be upgraded in alphabetical order. + +=== Order Upgrades by Server Group + +Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: + +[source,yaml] +---- +apiVersion: couchbase.com/v2 +kind: CouchbaseCluster +spec: + serverGroups: + - zone-1 + - zone-2 + - zone-3 + image: couchbase/server:8.0.0 <.> + upgrade: + upgradeOrderType: ServerGroups <.> + upgradeOrder <.> + - zone-3 +---- + +<.> The version we want to upgrade to. +<.> The order type we want the Operator to use. +<.> Upgrade pods running in server group zone-3 first. Pods running on server groups not in this list, zone-1 and zone-2, will be upgraded in the order given in the couchbasecluster.spec.serverGroups list. + +=== Order Upgrades by Server Class + +Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: + +[source,yaml] +---- +apiVersion: couchbase.com/v2 +kind: CouchbaseCluster +spec: + servers: + - name: data_only + services: + - data + size: 2 + - name: idx_query + services: + - index + - query + size: 6 + image: couchbase/server:8.0.0 <.> + upgrade: + upgradeOrderType: ServerClasses <.> + upgradeOrder: <.> + - idx_query + - data_only +---- + +<.> The version we want to upgrade to. +<.> The order type we want the Operator to use. +<.> Upgrade pods running in server class idx_query first, followed by pods running in data_only. The maximum number of pods that will be upgraded on each cycle will be limited by either the `spec.upgrade.rollingUpgrade.maxUpgradable` field or the number of pods in the server class being upgraded, whichever is smaller. The Operator will not upgrade more than one server class at a time. If the number of pods running a server class is less than the `spec.upgrade.rollingUpgrade.maxUpgradable` amount, the Operator will not upgrade pods from the next server class in the list. + +=== Order Upgrades by Service + +Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: -[source,yaml,subs="attributes,verbatim"] +[source,yaml] ---- apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:{couchbase-version} # <.> - upgradeProcess: InPlaceUpgrade + servers: + - name: data_only + services: + - data + size: 2 + - name: idx_query + services: + - index + - query + size: 2 + - name: query_only + services: + - query + size: 2 + image: couchbase/server:8.0.0 <.> + upgrade: + upgradeOrderType: Services <.> + upgradeOrder: <.> + - index + - data + - query ---- -<.> The Operator will detect that existing pod specifications do not match the new pod specifications and trigger an in-place upgrade. \ No newline at end of file +<.> The version we want to upgrade to. +<.> The order type we want the Operator to use. +<.> The sequence by which the Operator should upgrade services. Pods running multiple services will be ordered by the first one of those services in the sequence list. Using this manifest, pods running the index service (those in the idx_query server class) will be upgraded first, followed by the pods running the data service, and finally the pods running the query service. If the number of pods running a service is less than the `spec.upgrade.rollingUpgrade.maxUpgradable` amount, the Operator will not upgrade pods from the next service in the list. If the upgrade order sequence does not include all services, pods running services not in the list will be upgraded using the default order: data, query, index, search, analytics, eventing. \ No newline at end of file From e1401f5c72e293a1fc2d689a462d256bac3d9101 Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Tue, 16 Dec 2025 17:43:33 +0530 Subject: [PATCH 03/10] Updated howto-couchbase-upgrade file --- .../ROOT/pages/howto-couchbase-upgrade.adoc | 95 ++++++++++++------- 1 file changed, 62 insertions(+), 33 deletions(-) diff --git a/modules/ROOT/pages/howto-couchbase-upgrade.adoc b/modules/ROOT/pages/howto-couchbase-upgrade.adoc index 4877acc1..4a521daa 100644 --- a/modules/ROOT/pages/howto-couchbase-upgrade.adoc +++ b/modules/ROOT/pages/howto-couchbase-upgrade.adoc @@ -8,15 +8,16 @@ How-to upgrade Couchbase Server to a later version. You can upgrade Couchbase Server by changing the `spec.image` field in the cluster manifest to a new version. While the upgrade is in progress and some pods still run the previous version, you can roll back the cluster to that previous version. The `spec.upgrade` section of the cluster manifest provides controls for granular management of the upgrade process. -Before you upgrade, review the upgrade xref:concept-upgrade.adoc[concepts] and the available controls. +Before you upgrade, review the xref:concept-upgrade.adoc[upgrade concepts] and the available controls. NOTE: During an upgrade or rollback, when the cluster runs 2 Couchbase Server versions, the Operator marks the cluster as Mixed Mode. In this state, the Operator disables sidecar pod modifications and bucket storage backend migrations. == Upgrading a Cluster -The following is the existing configuration: - +. This is the existing configuration: ++ +-- [source,yaml] ---- apiVersion: couchbase.com/v2 @@ -25,20 +26,26 @@ spec: image: couchbase/server:7.6.8 ---- -<.> The image can be modified to any valid Couchbase Server image. +** You can modify the image to any valid Couchbase Server image. [source,yaml] ---- apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:8.0.0 # <.> + image: couchbase/server:8.0.0 ---- -<.> The modification will trigger the Operator to compare existing pod specifications, which use the old image, to new pod specifications, which will use the new image. Since they don't match, by default the Operator will begin a SwapRebalance upgrade process using the RollingUpgrade strategy. This creates new pods and rebalances them into the cluster before ejecting the old pods. +-- ++ + +. The modification triggers the Operator to compare existing pod specifications that use the old image with new pod specifications that use the new image. +Because the specifications differ, the Operator starts a `SwapRebalance` upgrade by using the `RollingUpgrade` strategy. +The Operator creates new pods, rebalances them into the cluster, and then ejects the old pods. === In Place Upgrade -Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: + +Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0`, update the manifest to: [source,yaml] ---- @@ -50,12 +57,13 @@ spec: upgradeProcess: InPlaceUpgrade # <.> ---- -<.> The version we want to upgrade to. -<.> Inform the Operator we want to perform in-place upgrades of the existing pods. This re-creates pods in-place using the same name and the same persistent volume. +<.> The version to which you want to upgrade. +<.> Configure the Operator to perform in-place upgrades on the existing pods. +This process re-creates each pod in place by using the same name and persistent volume. === Rolling Upgrade Controls -Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: +Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0`, update the manifest to: [source,yaml] ---- @@ -71,15 +79,19 @@ spec: maxUpgradablePercent: 10 <.> ---- -<.> The version we want to upgrade to. -<.> couchbasecluster.spec.upgrade.rollingUpgrade has two options. Either or both can be configured and the Operator will upgrade the lower number of pods per cycle. -<.> Configure Operator to only upgrade 3 pods at a time. -<.> Configure Operator to upgrade at most 10% of pods at a time relative to the total cluster size, rounded down. -If the above couchbasecluster.spec.upgrade.rollingUpgrade was used on a cluster with 10 pods, only 1 would be upgraded at a time, as the percentage value of the total is lower than the fixed number and therefore takes precedence. If however we had a cluster with 60 pods, the Operator would upgrade 3 at a time as the fixed number is now lower than the percentage. +<.> The version to which you want to upgrade. +<.> `couchbasecluster.spec.upgrade.rollingUpgrade` has 2 options. +You can configure either or both, and the Operator upgrades the lower number of pods per cycle. +<.> Configure the Operator to only upgrade 3 pods at a time. +<.> Configure the Operator to upgrade a maximum of 10% of pods at a time, relative to the total cluster size, rounded down. +When you apply the preceding `couchbasecluster.spec.upgrade.rollingUpgrade` settings to a cluster with 10 pods, the Operator upgrades one pod at a time. +In this case, the percentage value resolves to a lower number and takes precedence. +For a cluster with 60 pods, the Operator upgrades three pods at a time. +In this case, the fixed number resolves to a lower value than the percentage. === Granular Controls -Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: +Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0`, update the manifest to: [source,yaml] ---- @@ -102,15 +114,24 @@ spec: - cb-instance-2 ---- -<.> The version we want to upgrade to. -<.> The Operator will wait for this period of time between each upgrade cycle. In this instance, every time an upgrade cycle occurs, there will be a 5 minute wait until the next one. During this period, normal Operator functions, other than those that are disabled during upgrades will continue to run. -<.> The Operator will leave 4 pods on the previous version and not upgrade them. This might be useful if you want an extended stabilization period for a set number of nodes. Couchbase Server and Operator will not consider an upgrade complete until all pods are running on the new/same version. Features only available on the upgraded version will not be available until this is the case. -<.> Determine the order that the Operator will upgrade pods, either by pod (Couchbase node) name, server group, server class or by the Couchbase services running on a pod. You might want to upgrade pods in a specific availability zone first before others, or perhaps your pods running the data service should be upgraded before those with the index service. -<.> Depending on the upgradeOrderType, this field is a non-exhaustive list of the order Operator should upgrade pods by that type. In this case, the Operator will upgrade pods by Node name, meaning cb-instance-3 will be upgraded first, followed by cb-instance-1 and finally cb-instance-2. Any remaining pods that aren’t selected by the list will be upgraded in alphabetical order. +<.> The version to which you want to upgrade. +<.> The Operator waits for the specified period between each upgrade cycle. +In this example, the Operator waits five minutes before starting the next cycle. +During this time, the Operator continues normal operations except for functions disabled during upgrades. +<.> The Operator keeps four pods running the previous version and does not upgrade them. +You can use this setting to extend the stabilization period for a specific number of nodes. +Couchbase Server and the Operator consider the upgrade complete only when all pods run the same new version. +The features available only in the upgraded version remain unavailable until the upgrade completes. +<.> Define the sequence the Operator uses to upgrade pods by pod name (Couchbase Server cluster), server group, server class, or the services. +As an administrator, you can upgrade pods in a specific Availability Zone first, +or upgrade pods running the Data Service first and then the pods running the Index Service. +<.> Based on the configured `upgradeOrderType`, this field defines a non-exhaustive sequence that the Operator uses to upgrade pods. +In this example, the Operator upgrades pods by node name in the following order: `cb-instance-3`, `cb-instance-1`, and `cb-instance-2`. +The Operator upgrades any remaining pods not listed by using alphabetical order. === Order Upgrades by Server Group -Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: +Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0`, update the manifest to: [source,yaml] ---- @@ -128,13 +149,14 @@ spec: - zone-3 ---- -<.> The version we want to upgrade to. -<.> The order type we want the Operator to use. -<.> Upgrade pods running in server group zone-3 first. Pods running on server groups not in this list, zone-1 and zone-2, will be upgraded in the order given in the couchbasecluster.spec.serverGroups list. +<.> The version to which you want to upgrade. +<.> The order type you want the Operator to use. +<.> Upgrade pods running in server group `zone-3` first. +The Operator upgrades pods running in server groups not in this list, `zone-1` and `zone-2`, in the order defined in the `couchbasecluster.spec.serverGroups` list. === Order Upgrades by Server Class -Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: +Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0`, update the manifest to: [source,yaml] ---- @@ -159,13 +181,16 @@ spec: - data_only ---- -<.> The version we want to upgrade to. -<.> The order type we want the Operator to use. -<.> Upgrade pods running in server class idx_query first, followed by pods running in data_only. The maximum number of pods that will be upgraded on each cycle will be limited by either the `spec.upgrade.rollingUpgrade.maxUpgradable` field or the number of pods in the server class being upgraded, whichever is smaller. The Operator will not upgrade more than one server class at a time. If the number of pods running a server class is less than the `spec.upgrade.rollingUpgrade.maxUpgradable` amount, the Operator will not upgrade pods from the next server class in the list. +<.> The version to which you want to upgrade. +<.> The order type you want the Operator to use. +<.> Upgrade pods running in the `idx_query` server class first, followed by pods running in `data_only`. +The Operator limits the number of pods upgraded in each cycle to the smaller value between `spec.upgrade.rollingUpgrade.maxUpgradable` and the number of pods in the current server class. +The Operator upgrades only one server class at a time. +If the number of pods in a server class is less than `spec.upgrade.rollingUpgrade.maxUpgradable`, the Operator does not upgrade pods from the next server class in the list. === Order Upgrades by Service -Assuming spec.image is equal to a version below couchbase/server:8.0.0, update the manifest to: +Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0`, update the manifest to: [source,yaml] ---- @@ -195,6 +220,10 @@ spec: - query ---- -<.> The version we want to upgrade to. -<.> The order type we want the Operator to use. -<.> The sequence by which the Operator should upgrade services. Pods running multiple services will be ordered by the first one of those services in the sequence list. Using this manifest, pods running the index service (those in the idx_query server class) will be upgraded first, followed by the pods running the data service, and finally the pods running the query service. If the number of pods running a service is less than the `spec.upgrade.rollingUpgrade.maxUpgradable` amount, the Operator will not upgrade pods from the next service in the list. If the upgrade order sequence does not include all services, pods running services not in the list will be upgraded using the default order: data, query, index, search, analytics, eventing. \ No newline at end of file +<.> The version to which you want to upgrade. +<.> The order type you want the Operator to use. +<.> Define the sequence the Operator uses to upgrade services. +The Operator orders pods that run multiple services by the first service listed in the sequence. +With this manifest, the Operator upgrades pods running the Index Service first, followed by the Data Service, and then the Query Service. +If the number of pods running a service is less than `spec.upgrade.rollingUpgrade.maxUpgradable`, the Operator does not upgrade pods from the next service in the list. +When the sequence does not include all services, the Operator upgrades pods running unlisted services by using the default order: data, query, index, search, analytics, and eventing. \ No newline at end of file From 2bdf8fb4fa610f7c7bb973e54f37e6947f57db0f Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Tue, 16 Dec 2025 17:52:22 +0530 Subject: [PATCH 04/10] preview yml file --- preview/HEAD.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/preview/HEAD.yml b/preview/HEAD.yml index 3736c35f..64d12539 100644 --- a/preview/HEAD.yml +++ b/preview/HEAD.yml @@ -3,4 +3,4 @@ sources: branches: [release/8.0] docs-operator: - branches: [DOC-13656-Create-release-note-for-Couchbase-Operator-2.9.0, release/2.8] \ No newline at end of file + branches: [DOC-13839-improved-upgrade-process-in-cao-290, release/2.8] \ No newline at end of file From a832ebed5948219c13885fdb47c715359430e5e6 Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Tue, 16 Dec 2025 18:05:14 +0530 Subject: [PATCH 05/10] Minor edit in concept-upgrade file --- modules/ROOT/pages/concept-upgrade.adoc | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/concept-upgrade.adoc b/modules/ROOT/pages/concept-upgrade.adoc index 6ff04a6b..f18e73b9 100644 --- a/modules/ROOT/pages/concept-upgrade.adoc +++ b/modules/ROOT/pages/concept-upgrade.adoc @@ -22,14 +22,14 @@ The following is a `spec.upgrade` example in the CouchbaseCluster manifest for a [source,yaml] ---- upgrade: - upgradeProcess: SwapRebalance - upgradeStrategy: RollingUpgrade - rollingUpgrade: + upgradeProcess: SwapRebalance # <.> + upgradeStrategy: RollingUpgrade # <.> + rollingUpgrade: # <.> maxUpgradable: 1 maxUpgradablePercent: 100% - stabilizationPeriod: 10s - previousVersionPodCount: 0 - upgradeOrderType: Nodes + stabilizationPeriod: 10s # <.> + previousVersionPodCount: 0 # <.> + upgradeOrderType: Nodes # <.> upgradeOrder: - node-1 - node-2 @@ -37,7 +37,7 @@ upgrade: The upgrade example explanation is as follows: -* `upgradeProcess` supports `SwapRebalance` or `InPlaceUpgrade`, and defaults to `SwapRebalance` when you don't specify a value. +<.> `upgradeProcess` supports `SwapRebalance` or `InPlaceUpgrade`, and defaults to `SwapRebalance` when you don't specify a value. The selected `upgradeStrategy` determines how `SwapRebalance` creates pods running the upgraded version. To use `InPlaceUpgrade`, set the strategy to `rollingUpgrade`. @@ -48,7 +48,7 @@ The Operator rebalances data from the existing pods to the new pods and then del The Operator detaches the volumes from those pods, replaces them with pods running the new cluster version, and rebinds the existing volumes to the new pods. This process completes faster than a `rollingUpgrade`, and the Operator retains the pod names and network settings for the updated pods. -* `upgradeStrategy` determines how `SwapRebalance` creates new pods by using either `RollingUpgrade` or `ImmediateUpgrade`. +<.> `upgradeStrategy` determines how `SwapRebalance` creates new pods by using either `RollingUpgrade` or `ImmediateUpgrade`. To use `InPlaceUpgrade`, set the strategy to `rollingUpgrade`. ** `rollingUpgrade` upgrades a predetermined number of pods at a time, which limits risk and simplifies rollback. @@ -57,14 +57,14 @@ Because this strategy uses the least network and compute resources, it minimizes ** `ImmediateUpgrade` increases risk and resource utilization during the upgrade but completes the operation faster. Because the strategy upgrades all pods at the same time, it can cause an adverse impact on client performance. -* `StabilizationPeriod` lets you control how long the Operator waits between upgrade cycles and gives you time to check cluster health and service availability. +<.> `StabilizationPeriod` lets you control how long the Operator waits between upgrade cycles and gives you time to check cluster health and service availability. -* `PreviousVersionPodCount` instructs the Operator to keep a fixed number of pods running the previous cluster version. +<.> `PreviousVersionPodCount` instructs the Operator to keep a fixed number of pods running the previous cluster version. This setting supports rollbacks or an extended `StabilizationPeriod` for the final pods during a cluster upgrade. Couchbase Server considers the upgrade process complete only when all pods run the new cluster version. During this time, the Operator marks the cluster as Mixed Mode, which may restrict some features. -* `UpgradeOrderType` defines the sequence the Operator uses to upgrade pods to the new cluster version. +<.> `UpgradeOrderType` defines the sequence the Operator uses to upgrade pods to the new cluster version. It determines how the Operator interprets `UpgradeOrder` and must be set to Nodes, ServerGroups, ServerClasses, or Services. The Operator follows the sequence specified in `UpgradeOrder` and applies the default ordering to any items not listed. From 41edafa5c93886cd4bb398b2b9cf085b00a12b5d Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Tue, 16 Dec 2025 18:14:39 +0530 Subject: [PATCH 06/10] Minor edit in concept-upgrade file --- modules/ROOT/pages/concept-upgrade.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/concept-upgrade.adoc b/modules/ROOT/pages/concept-upgrade.adoc index f18e73b9..c87a6c0e 100644 --- a/modules/ROOT/pages/concept-upgrade.adoc +++ b/modules/ROOT/pages/concept-upgrade.adoc @@ -24,7 +24,7 @@ The following is a `spec.upgrade` example in the CouchbaseCluster manifest for a upgrade: upgradeProcess: SwapRebalance # <.> upgradeStrategy: RollingUpgrade # <.> - rollingUpgrade: # <.> + rollingUpgrade: maxUpgradable: 1 maxUpgradablePercent: 100% stabilizationPeriod: 10s # <.> From 33df60841c0f372ffa1be119248ed9005d1847e7 Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Tue, 16 Dec 2025 18:22:02 +0530 Subject: [PATCH 07/10] Another minor fix --- modules/ROOT/pages/concept-upgrade.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/concept-upgrade.adoc b/modules/ROOT/pages/concept-upgrade.adoc index c87a6c0e..c3e141d5 100644 --- a/modules/ROOT/pages/concept-upgrade.adoc +++ b/modules/ROOT/pages/concept-upgrade.adoc @@ -57,16 +57,16 @@ Because this strategy uses the least network and compute resources, it minimizes ** `ImmediateUpgrade` increases risk and resource utilization during the upgrade but completes the operation faster. Because the strategy upgrades all pods at the same time, it can cause an adverse impact on client performance. -<.> `StabilizationPeriod` lets you control how long the Operator waits between upgrade cycles and gives you time to check cluster health and service availability. +<.> `stabilizationPeriod` lets you control how long the Operator waits between upgrade cycles and gives you time to check cluster health and service availability. -<.> `PreviousVersionPodCount` instructs the Operator to keep a fixed number of pods running the previous cluster version. +<.> `previousVersionPodCount` instructs the Operator to keep a fixed number of pods running the previous cluster version. This setting supports rollbacks or an extended `StabilizationPeriod` for the final pods during a cluster upgrade. Couchbase Server considers the upgrade process complete only when all pods run the new cluster version. During this time, the Operator marks the cluster as Mixed Mode, which may restrict some features. -<.> `UpgradeOrderType` defines the sequence the Operator uses to upgrade pods to the new cluster version. -It determines how the Operator interprets `UpgradeOrder` and must be set to Nodes, ServerGroups, ServerClasses, or Services. -The Operator follows the sequence specified in `UpgradeOrder` and applies the default ordering to any items not listed. +<.> `upgradeOrderType` defines the sequence the Operator uses to upgrade pods to the new cluster version. +It determines how the Operator interprets `upgradeOrder` and must be set to Nodes, ServerGroups, ServerClasses, or Services. +The Operator follows the sequence specified in `upgradeOrder` and applies the default ordering to any items not listed. NOTE: `InPlaceUpgrade` can interrupt service and increase the risk of data loss. Use this process only when the cluster has at least two nodes running the Data Service. From 7f550b772e4e2785ee833581b202c47fb23c3190 Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Tue, 16 Dec 2025 21:24:58 +0530 Subject: [PATCH 08/10] Implemented review comments --- modules/ROOT/pages/concept-upgrade.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/concept-upgrade.adoc b/modules/ROOT/pages/concept-upgrade.adoc index c3e141d5..8c162da2 100644 --- a/modules/ROOT/pages/concept-upgrade.adoc +++ b/modules/ROOT/pages/concept-upgrade.adoc @@ -46,7 +46,7 @@ The Operator rebalances data from the existing pods to the new pods and then del ** During an `InPlaceUpgrade`, the Operator selects one or more candidate pods and fails them over. The Operator detaches the volumes from those pods, replaces them with pods running the new cluster version, and rebinds the existing volumes to the new pods. -This process completes faster than a `rollingUpgrade`, and the Operator retains the pod names and network settings for the updated pods. +This process completes faster than a `SwapRebalance`, and the Operator retains the pod names and network settings for the updated pods. <.> `upgradeStrategy` determines how `SwapRebalance` creates new pods by using either `RollingUpgrade` or `ImmediateUpgrade`. To use `InPlaceUpgrade`, set the strategy to `rollingUpgrade`. @@ -129,7 +129,7 @@ Keep the time spent in this mode to a minimum. === Upgrading Pods Kubernetes pods are immutable. -When you modify the CouchbaseCluster manifest in a way that requires pod replacement, the Operator creates new pods by using the same process that of the upgrade to replace pods running the previous version. +When you modify the CouchbaseCluster manifest in a way that requires pod replacement, the Operator creates new pods by using the same process as upgrading or rolling back pods to replace pods running the previous version. Upgrading Couchbase Server is only a subset of modifying any other pod specification parameter. The Operator builds pod specifications from the manifest and compares them with the existing pods in the cluster. From 2d79630796aef778aec52ba86295b943cd2c37f3 Mon Sep 17 00:00:00 2001 From: rao-shwe Date: Wed, 17 Dec 2025 16:17:11 +0530 Subject: [PATCH 09/10] Accepted peer review suggestion Co-authored-by: Ray Offiah <77050471+RayOffiah@users.noreply.github.com> --- modules/ROOT/pages/concept-upgrade.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/concept-upgrade.adoc b/modules/ROOT/pages/concept-upgrade.adoc index 8c162da2..5f880e9b 100644 --- a/modules/ROOT/pages/concept-upgrade.adoc +++ b/modules/ROOT/pages/concept-upgrade.adoc @@ -61,7 +61,7 @@ Because the strategy upgrades all pods at the same time, it can cause an adverse <.> `previousVersionPodCount` instructs the Operator to keep a fixed number of pods running the previous cluster version. This setting supports rollbacks or an extended `StabilizationPeriod` for the final pods during a cluster upgrade. -Couchbase Server considers the upgrade process complete only when all pods run the new cluster version. +Couchbase Server considers the upgrade process complete only when all pods are running the new cluster version. During this time, the Operator marks the cluster as Mixed Mode, which may restrict some features. <.> `upgradeOrderType` defines the sequence the Operator uses to upgrade pods to the new cluster version. From caa80be77026eb9112814b89dd46b90bd51d5a51 Mon Sep 17 00:00:00 2001 From: rao-shwe Date: Wed, 17 Dec 2025 16:20:41 +0530 Subject: [PATCH 10/10] Updated howto-couchbase-upgrade.adoc --- .../ROOT/pages/howto-couchbase-upgrade.adoc | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/howto-couchbase-upgrade.adoc b/modules/ROOT/pages/howto-couchbase-upgrade.adoc index 4a521daa..085734f3 100644 --- a/modules/ROOT/pages/howto-couchbase-upgrade.adoc +++ b/modules/ROOT/pages/howto-couchbase-upgrade.adoc @@ -70,13 +70,13 @@ Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0 apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:8.0.0 <.> + image: couchbase/server:8.0.0 # <.> upgrade: upgradeProcess: SwapRebalance upgradeStrategy: RollingUpgrade - rollingUpgrade: <.> - maxUpgradable: 3 <.> - maxUpgradablePercent: 10 <.> + rollingUpgrade: # <.> + maxUpgradable: 3 # <.> + maxUpgradablePercent: 10 # <.> ---- <.> The version to which you want to upgrade. @@ -98,17 +98,17 @@ Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0 apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:8.0.0 <.> + image: couchbase/server:8.0.0 # <.> upgrade: upgradeProcess: SwapRebalance upgradeStrategy: RollingUpgrade rollingUpgrade: maxUpgradable: 1 maxUpgradablePercent: 20 - stabilizationPeriod: 5m <.> - previousVersionPodCount: 4 <.> - upgradeOrderType: Nodes <.> - upgradeOrder: <.> + stabilizationPeriod: 5m # <.> + previousVersionPodCount: 4 # <.> + upgradeOrderType: Nodes # <.> + upgradeOrder: # <.> - cb-instance-3 - cb-instance-1 - cb-instance-2 @@ -142,10 +142,10 @@ spec: - zone-1 - zone-2 - zone-3 - image: couchbase/server:8.0.0 <.> + image: couchbase/server:8.0.0 # <.> upgrade: - upgradeOrderType: ServerGroups <.> - upgradeOrder <.> + upgradeOrderType: ServerGroups # <.> + upgradeOrder # <.> - zone-3 ---- @@ -173,10 +173,10 @@ spec: - index - query size: 6 - image: couchbase/server:8.0.0 <.> + image: couchbase/server:8.0.0 # <.> upgrade: - upgradeOrderType: ServerClasses <.> - upgradeOrder: <.> + upgradeOrderType: ServerClasses # <.> + upgradeOrder: # <.> - idx_query - data_only ---- @@ -211,10 +211,10 @@ spec: services: - query size: 2 - image: couchbase/server:8.0.0 <.> + image: couchbase/server:8.0.0 # <.> upgrade: - upgradeOrderType: Services <.> - upgradeOrder: <.> + upgradeOrderType: Services # <.> + upgradeOrder: # <.> - index - data - query @@ -226,4 +226,4 @@ spec: The Operator orders pods that run multiple services by the first service listed in the sequence. With this manifest, the Operator upgrades pods running the Index Service first, followed by the Data Service, and then the Query Service. If the number of pods running a service is less than `spec.upgrade.rollingUpgrade.maxUpgradable`, the Operator does not upgrade pods from the next service in the list. -When the sequence does not include all services, the Operator upgrades pods running unlisted services by using the default order: data, query, index, search, analytics, and eventing. \ No newline at end of file +When the sequence does not include all services, the Operator upgrades pods running unlisted services by using the default order: data, query, index, search, analytics, and eventing.