diff --git a/modules/ROOT/pages/concept-upgrade.adoc b/modules/ROOT/pages/concept-upgrade.adoc index 2358c4d..5f880e9 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 `SwapRebalance`, 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 are running 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 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 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 diff --git a/modules/ROOT/pages/howto-couchbase-upgrade.adoc b/modules/ROOT/pages/howto-couchbase-upgrade.adoc index bfe39fb..085734f 100644 --- a/modules/ROOT/pages/howto-couchbase-upgrade.adoc +++ b/modules/ROOT/pages/howto-couchbase-upgrade.adoc @@ -3,52 +3,227 @@ 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 xref:concept-upgrade.adoc[upgrade 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 + +. This is the existing configuration: ++ +-- +[source,yaml] +---- +apiVersion: couchbase.com/v2 +kind: CouchbaseCluster +spec: + image: couchbase/server:7.6.8 +---- + +** 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 +---- + +-- ++ + +. 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 earlier than `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: InPlaceUpgrade # <.> +---- + +<.> 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 earlier than `couchbase/server:8.0.0`, update the manifest to: + +[source,yaml] ---- apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:{couchbase-version-upgrade-from} # <.> + image: couchbase/server:8.0.0 # <.> + upgrade: + upgradeProcess: SwapRebalance + upgradeStrategy: RollingUpgrade + rollingUpgrade: # <.> + maxUpgradable: 3 # <.> + maxUpgradablePercent: 10 # <.> ---- -<.> 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. +<.> 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 earlier than `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: SwapRebalance + upgradeStrategy: RollingUpgrade + rollingUpgrade: + maxUpgradable: 1 + maxUpgradablePercent: 20 + stabilizationPeriod: 5m # <.> + previousVersionPodCount: 4 # <.> + upgradeOrderType: Nodes # <.> + upgradeOrder: # <.> + - cb-instance-3 + - cb-instance-1 + - cb-instance-2 ---- -<.> 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 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. -== In Place Upgrade -Given the existing configuration: +=== Order Upgrades by Server Group -[source,yaml,subs="attributes,verbatim"] +Assuming `spec.image` is equal to a version earlier than `couchbase/server:8.0.0`, update the manifest to: + +[source,yaml] ---- apiVersion: couchbase.com/v2 kind: CouchbaseCluster spec: - image: couchbase/server:{couchbase-version-upgrade-from} - upgradeProcess: InPlaceUpgrade # <.> + serverGroups: + - zone-1 + - zone-2 + - zone-3 + image: couchbase/server:8.0.0 # <.> + upgrade: + upgradeOrderType: ServerGroups # <.> + upgradeOrder # <.> + - zone-3 ---- -<.> This field will inform the operator that we want to perform an in-place upgrade of the existing pods. +<.> 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 earlier than `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 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 earlier than `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 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. diff --git a/preview/HEAD.yml b/preview/HEAD.yml index a29fd69..6d02668 100644 --- a/preview/HEAD.yml +++ b/preview/HEAD.yml @@ -3,4 +3,4 @@ sources: branches: [release/8.0] docs-operator: - branches: [DOC-13857-tutorial-to-detect-avx2, release/2.8] \ No newline at end of file + branches: [DOC-13857-tutorial-to-detect-avx2, release/2.8]