Upgrade the operator · Next · OpenBao Operator

Upgrade the CRDs before the controller whenever the target release changes the CRD bundle. This page covers the operator installation. Changes to the OpenBao workload version use spec.version and the cluster upgrade strategy.

Supported paths

Operator path	Project stance	Action
Stable patch, `0.Y.Z` to the next patch	Supported maintenance path	Review the release notes and upgrade
Stable minor, `0.Y.Z` to `0.(Y+1).0`	Supported with release-note review	Move sequentially and validate in staging
Skip multiple minor releases	Not recommended	Apply intermediate migrations in order
Routine operator downgrade	Unsupported	Prefer a forward fix; treat any rollback as recovery

Restore changes in this release

Finish in-flight restores before upgrading. Requests from older releases do not use the submission claim.
A restore into an existing cluster now ends Unknown and waits for an administrator acknowledgement. The operator no longer drains read replicas or restarts voters automatically; Resume runs a managed restart instead. See Recover an uncertain restore.
status.restore on OpenBaoCluster is deprecated and no longer written.
openbao_restore_state adds values 4–7. An unresolved recovery takes precedence; otherwise the newest retained request determines the value. Update alerts that assume the previous values.
Static-unseal clusters can use spec.unseal.credentialsSecretRef as their key source, and admission prevents changing it later. Earlier releases ignored this field for static clusters. A cluster that already has an operator-generated <cluster>-unseal-key keeps using that key, so an existing reference stays ignored.

Upgrade a Helm installation

Replace X.Y.Z with the exact target release.

Apply the release CRDs.

kubectl apply -f \
  https://github.com/kubebao/openbao-operator/releases/download/X.Y.Z/crds.yaml

Upgrade the chart.

helm upgrade openbao-operator \
  oci://ghcr.io/kubebao/charts/openbao-operator \
  --version X.Y.Z \
  --namespace openbao-operator-system

Helm does not upgrade CRDs stored in a chart’s crds/ directory. Applying the release bundle first prevents the new controller from starting against an older schema.

Verify the upgrade

Verify the operator workloads.

kubectl -n openbao-operator-system get deployments,pods

Verify that the stored CRD version is v1alpha1 and that the CRDs report Established=True.

kubectl get crd openbaoclusters.openbao.org \
  -o jsonpath='{.status.storedVersions}{"\n"}{.status.conditions}{"\n"}'

Inspect each managed cluster’s phase, conditions, and recent events.

kubectl get openbaocluster -A
kubectl -n <namespace> describe openbaocluster <name>

Recover from a failed operator upgrade

Prefer a forward fix on a newer stable release. If that is not possible, validate the exact older controller and CRD combination in staging before changing production. Use backup and restore procedures when the failure affects the OpenBao data path; do not assume a chart rollback reverses CRD or workload state.