Upgrade Compatibility

Use this page when you need the exact upgrade-path contract for the operator itself.

This page defines which operator upgrade paths are supported, how CRD sequencing must work, and why rollback should be treated as a recovery decision rather than a normal lifecycle shortcut. It is the exact contract for changing the operator version, not the managed OpenBao workload version.

Reference table

Supported upgrade paths

Supported upgrade paths.

Path	Project stance	Operator guidance
Stable patch upgrades (0.Y.Z -> 0.Y.(Z+1))	Supported	Use as the normal maintenance path.
Stable minor upgrades (0.Y.Z -> 0.(Y+1).0)	Supported with release note review	Upgrade sequentially across minors and validate in staging.
Skipping multiple minors	Not recommended	Move sequentially so migrations and deprecations are not compressed into one jump.
Operator downgrades as routine rollback	Not supported	Treat downgrade pressure as a recovery decision, not as a normal release mechanism.

CRD-first upgrade rule

Apply CRDs before upgrading the Helm release when the target release changed CRD content.

Apply

CRD-first upgrade sequence

bash

kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/download/X.Y.Z/crds.yaml
helm upgrade openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator --namespace <operator-namespace>

This matches the installation guidance and keeps the API surface aligned with the controller you are about to run.

Upgrade safety checklist

Before upgrade:

• confirm the target version in Compatibility Matrix
• take and verify backups for managed clusters
• review release notes for deprecations and migrations

After upgrade:

• verify operator Deployments are Running
• verify CRD version and controller readiness
• verify managed cluster conditions and recent events

Rollback stance

If an upgrade introduces issues:

1. prefer a forward fix on a newer stable release
2. if rollback is required, treat it as a recovery operation with staging validation first
3. use backup and restore runbooks for data-path recovery scenarios

Related upgrade references

Backup operationsOpen the backup workflow before upgrades when you still need to capture or verify the recovery point.Restore from backupMove into restore procedures when rollback is no longer enough to recover state safely.Status conditions and eventsUse the status and events reference to interpret readiness and failure signals before and after the upgrade.