secure k8 s

Upgrading

Summary: Always back up before upgrading. Large version jumps are supported but every intervening version’s notes must be reviewed. HA clusters follow a specific node-replacement order.

Sources: raw/docs/upgrading/index.md, raw/docs/upgrading/ha-upgrade.md, raw/docs/upgrading/plugins.md.

Last updated: 2026-05-19

The danger up front

OpenBao does not guarantee data-store backward compatibility. Replacing the binary with an older one is not a downgrade — you must also roll back the data (source: raw/docs/upgrading/index.md). Snapshot first, every time.

Strategy

Jumps like 1.3.10 → 1.7.x are supported, but you must read each intervening minor’s upgrade notes — some require pre- or post-steps (source: raw/docs/upgrading/index.md).

Test the upgrade

Take a snapshot, restore into a test cluster, run the upgrade there. Crucial caveat: prevent the test cluster from reaching external systems (DBs, clouds) — otherwise it’ll revoke credentials its production sibling is still using (source: raw/docs/upgrading/index.md).

Non-HA upgrade

Replace the binary, restart. Upgrade tasks run when the new server is unsealed. Always shut down via SIGINT/SIGTERM so OpenBao can flush state (source: raw/docs/upgrading/index.md).

HA upgrade

Has a specific ordering — replace standbys first, then step down the leader so a new node takes over, then replace the old leader. See raw/docs/upgrading/ha-upgrade.md.

Agent / Proxy

Agent and Proxy are API clients of the server. OpenBao APIs are almost always backwards compatible; deprecations are called out in upgrade notes with long deprecation windows. Agent can lag the server; the project recommends keeping them at the same minor (source: raw/docs/upgrading/index.md).

Plugins

In-place upgrade procedure documented at raw/docs/upgrading/plugins.md. The pattern is: register the new version, then re-tune existing mounts to the new version. See plugins.