ADR-011: Vault server image tag explicit pin (chart 0.32.0 + Vault 2.0.0)¶
Status¶
Accepted (2026-04-14, adopted as an interim measure)
Date¶
2026-04-14
Context¶
kubernetes/secrets/vault/values.yaml explicitly pins server.image.tag to "2.0.0". This ADR records the background and the conditions for lifting that pin.
Background: a silent-upgrade incident¶
The HashiCorp Vault Helm chart 0.32.0 (released 2026-01-14) has a template quirk: when server.image.tag is set to an empty string "", it falls through to default "latest", rendering image: hashicorp/vault:latest.
This repo originally set the empty string expecting to follow the chart default, but :latest was actually resolved. When Vault 2.0.0 was published to the :latest tag on 2026-04-14, all 3 replicas got silently rolling-upgraded to 2.0.0. This was caught during review of PR #271.
Impact¶
- An unplanned major-version upgrade of Vault (1.x → 2.x)
- HashiCorp does not officially support downgrading across major versions (no raft snapshot / storage format compatibility)
- Reverting would require a manual storage migration — not realistic at homelab scale
Decision¶
Explicitly pin server.image.tag: "2.0.0".
The proper principle¶
- Remove the
tagline entirely and follow the chart default (chart 0.32.0 defaultsserver.image.tagto1.21.2) - This keeps chart upgrades and image upgrades as a single reviewable unit
Why an interim measure¶
- Already running 2.0.0 in production; downgrading to 1.21 carries risk due to incompatible raft storage formats
- Priority is keeping the major version that's currently running stable
Conditions for lifting the pin¶
Lift this pin once all of the following are true:
- A chart 0.33+ line is released whose
server.image.tagdefault tracks the 2.x line - At that point, the running Vault major version matches the chart default's major version
Removal steps:
- Delete the server.image.tag line and let the chart default take over
- In the chart-upgrade PR, diff the helm template output to confirm the image tag lands on the expected 2.x line
Lesson¶
- A Helm chart's
default "latest"behavior is fertile ground for silent upgrades - Passing
tag: ""does not always mean "follow the chart default" — it can resolve to:latest - Avoid passing an empty string; either pin explicitly or delete the line
References¶
- PR #271: discovery and remediation of the silent upgrade
- HashiCorp Vault chart 0.32.0 (released 2026-01-14)
- Vault 2.0.0 (GA 2026-04-14)