#Upgrade

Use this procedure when you publish a new Alauda Build of Rook-Ceph Operator version into OperatorHub on an existing cluster.

Choose the path that matches the platform version:

Approving the pending InstallPlan for rook-ceph/rook-operator installs the Operator CSV. On 4.4.1 and later, that approval is also the confirmation for the Ceph image bound to the package. On 4.4.0, the console does not write that image; you must patch it with kubectl.

#Before you start

• Identify the namespace of the Rook Operator. The default namespace created by the Distributed Storage wizard is rook-ceph.
• Download the new Alauda Build of Rook-Ceph Operator package that matches the cluster architecture.
• For internal mode, confirm CephCluster is Ready and status.ceph.health is HEALTH_OK.
• For external mode (spec.external.enable: true), upgrade only the Operator. Do not patch a local Ceph image.
• Do not edit generated CSV manifests as a persistent customization. Subsequent OLM reconciles can overwrite those edits. See Architecture.

#1. Confirm Manual approval

kubectl -n rook-ceph get subscription rook-operator \
  -o jsonpath='{.spec.installPlanApproval}{"\n"}'

The output must be Manual. If it is not, set it before you upload the package:

kubectl -n rook-ceph patch subscription rook-operator --type merge \
  -p '{"spec":{"installPlanApproval":"Manual"}}'

On 4.4.1 and later, you can also set Upgrade Strategy to Manual in Marketplace > OperatorHub > Alauda Build of Rook-Ceph.

#2. Upload the new Operator package

Upload the new Alauda Build of Rook-Ceph package with violet, then confirm the target version is visible in OperatorHub.

Follow Upload Packages and the OperatorHub steps in Operator.

After the upload succeeds, OperatorHub shows the new version as available. Do not approve it until installPlanApproval is Manual.

#3. Approve the Operator package

OLM creates an InstallPlan for the new CSV. Approve only the plan referenced by Subscription.status.installPlanRef.

kubectl -n rook-ceph get subscription rook-operator \
  -o jsonpath='{.status.state}{"\n"}{.status.installedCSV}{"\n"}{.status.currentCSV}{"\n"}{.status.installPlanRef.name}{"\n"}'

PLAN="$(kubectl -n rook-ceph get subscription rook-operator -o jsonpath='{.status.installPlanRef.name}')"
kubectl -n rook-ceph patch installplan "$PLAN" --type merge \
  -p '{"spec":{"approved":true}}'

kubectl -n rook-ceph get csv
kubectl -n rook-ceph get subscription rook-operator \
  -o jsonpath='{.status.state}{"\t"}{.status.installedCSV}{"\n"}'

#Apply the Ceph image on 4.4.0

4.4.0 does not follow the Ceph image after you approve the Operator package. For internal mode, select the Ceph daemon image from the new CSV by the relatedImage name ceph. Do not copy an image from the unfiltered relatedImages list.

CSV="$(kubectl -n rook-ceph get subscription rook-operator -o jsonpath='{.status.installedCSV}')"
CEPH_IMAGES="$(kubectl -n rook-ceph get csv "$CSV" \
  -o jsonpath='{range .spec.relatedImages[?(@.name=="ceph")]}{.image}{"\n"}{end}')"
COUNT="$(printf '%s\n' "$CEPH_IMAGES" | awk 'NF{c++} END{print c+0}')"
if [ "$COUNT" -ne 1 ]; then
  echo "expected exactly one relatedImage named ceph, found ${COUNT}:" >&2
  printf '%s\n' "$CEPH_IMAGES" >&2
  exit 1
fi
CEPH_IMAGE="$(printf '%s\n' "$CEPH_IMAGES" | awk 'NF{print; exit}')"
echo "$CEPH_IMAGE"

If the command exits with an error, stop. Do not patch CephCluster until relatedImages contains exactly one entry whose name is ceph.

List CephCluster objects and patch spec.cephVersion.image to that unique image. Replace <cephcluster-name>:

kubectl -n rook-ceph get cephcluster

kubectl -n rook-ceph patch cephcluster <cephcluster-name> --type merge \
  -p "{\"spec\":{\"cephVersion\":{\"image\":\"${CEPH_IMAGE}\"}}}"

On 4.4.1 and later, do not run this patch. Approving the package accepts the bound Ceph image.

#Verify the Operator and data plane

Confirm the Operator CSV:

kubectl -n rook-ceph get csv
kubectl -n rook-ceph get subscription rook-operator \
  -o jsonpath='{.status.state}{"\t"}{.status.installedCSV}{"\n"}'

For internal mode, confirm CephCluster health and the Ceph image:

kubectl -n rook-ceph get cephcluster <cephcluster-name> \
  -o jsonpath='phase={.status.phase} health={.status.ceph.health} image={.spec.cephVersion.image}{"\n"}'

• phase=Ready and health=HEALTH_OK.
• spec.cephVersion.image matches the unique CSV relatedImages entry named ceph.
• Existing PVCs remain Bound.

For external mode, skip the local image check. Existing consumer volumes should remain Bound.

#If the details-page button stays disabled

This section applies to 4.4.1 and later. On 4.4.0, there is no details-page button; use kubectl.

1. Confirm the user can update installplans in rook-ceph.

2. For internal mode, confirm status.ceph.health is HEALTH_OK.

3. Inspect the Subscription and the referenced InstallPlan:

   kubectl -n rook-ceph get subscription rook-operator
   kubectl -n rook-ceph get installplan

   If the catalog already has a newer CSV but there is no pending unapproved InstallPlan, check whether startingCSV is pinning the Subscription. Do not try to repair that pin from the details page.

4. If the InstallPlan is already approved but the Ceph image did not change on 4.4.1 or later, confirm the installed CSV is Succeeded and that relatedImages contains exactly one entry named ceph.

Do not delete the CephCluster or PV objects to cancel an upgrade.

#Related topics

• Architecture — OLM upgrade overview
• Upload Packages — upload the Operator package
• Operator — Subscription, InstallPlan, and approval strategy
• Deploying in Internal Mode — install-time Upgrade Strategy