#Upgrade Valkey

Upgrade by increasing spec.version on the owning Valkey resource. The validating webhook rejects version downgrades.

The 2.0.0 product supports Valkey 7.2, 8.1, and 9.1. The source proves only that the webhook rejects a lower target version; it does not define a tested source-to-target matrix or prove that either sequential or skipped-line upgrades are safe. Obtain that matrix from the delivered release validation before changing a production instance.

#Before you begin

1. Confirm the instance is Ready and no scale, restart, access, certificate, scheduling, or configuration change is running.
2. Complete and verify an external backup or export. The Operator has no integrated backup or rollback controller.
3. Check application and module compatibility with the target Valkey line.
4. Review spec.customConfigs for directives removed or changed by the target version.
5. Confirm enough schedulable capacity for rolling Pod replacement.

Record the current state:

kubectl -n default get valkey valkey-cluster -o yaml > valkey-before-upgrade.yaml
kubectl -n default get pods,pvc,service -l buf.red/name=valkey-cluster -o wide
kubectl -n default get events --sort-by=.lastTimestamp

For Cluster architecture, also verify slot and membership health from a ready Pod:

kubectl -n default exec <ready-cluster-pod> -c valkey -- \
  valkey-cli CLUSTER INFO
kubectl -n default exec <ready-cluster-pod> -c valkey -- \
  valkey-cli CLUSTER NODES

#Apply the upgrade

Example: upgrade from 7.2 to 8.1.

kubectl -n default patch valkey valkey-cluster --type=merge \
  -p '{"spec":{"version":"8.1"}}'

Watch the high-level resource, Pods, and Events:

kubectl -n default get valkey valkey-cluster -w
kubectl -n default get pods -l buf.red/name=valkey-cluster -w
kubectl -n default get events --sort-by=.lastTimestamp

Do not apply another change while Pods are being replaced or the phase is not Ready.

#Verify the result

Read the desired and last recorded values, then inspect every server Pod:

kubectl -n default get valkey valkey-cluster \
  -o jsonpath='{.spec.version}{"\t"}{.status.lastVersion}{"\t"}{.status.phase}{"\n"}'
kubectl -n default get pods -l buf.red/name=valkey-cluster \
  -o custom-columns='NAME:.metadata.name,IMAGE:.spec.containers[?(@.name=="valkey")].image,READY:.status.containerStatuses[?(@.name=="valkey")].ready'
kubectl -n default exec <ready-pod> -c valkey -- valkey-cli INFO server

status.lastVersion is copied from the desired version during high-level reconciliation. It is not an observation of every running process. Verify the image and INFO server output on every data Pod; in Cluster architecture, do not assume one Pod represents every shard.

Then verify application reads and writes, access control list (ACL) authentication, replication or Cluster slot coverage, failover discovery where applicable, and exporter metrics.

#Failure boundary

Do not patch spec.version back to the previous value; downgrade is rejected and can be unsafe for persisted data. Preserve logs and Events, stop further changes, and follow the product support recovery plan. A downgrade requires a separately created compatible instance and a validated data migration or restore process.

Use the exact target version's command index and INFO reference when checking command, configuration, and runtime compatibility.