Vault 2.2.0 Breaking Changes: What Operators Must Change

The Vault v2.2.0 release notes contain these entries under their breaking changes and CHANGES sections. The Vault v2.2.0-rc1 release notes contain the same container, PostgreSQL, PKI and token entries in the excerpt provided. This article covers only those breaking items and the operator actions that the notes state, and it labels every point that is an inference.

Summary of the breaking changes #

Container images: the two cap_ipc_lock entries #

The first container entry in the v2.2.0 breaking changes states that the cap_ipc_lock capability is removed on Vault at build time, to allow Vault to run in common container runtimes. The same entry says that Vault in containers will no longer be able to call mlock() to lock memory. Operators are told to set disable_mlock = true in Vault's configuration. The notes also advise runtime operators to disable swapping to guarantee data safety.

The loss of mlock() is attributed only to that removal entry. The notes do not connect it to the second container entry, which is separate. That second entry states that the cap_ipc_lock capability is set on Vault at build time, and that container runtimes will need to add IPC_LOCK capabilities when running the Vault container. The v2.2.0-rc1 excerpt lists both entries in the same way.

The two entries describe the capability in opposite directions, and the notes do not say which build each one applies to. For that reason, this article does not decide which setting an image uses. Operators should check the build of the exact image they plan to run, and then follow the matching instruction: disable_mlock = true and disabled swapping for the removal build, or the IPC_LOCK capability at run time for the set build.

The notes also state that the gnupg, openssl and procps packages have been removed from UBI-based container images. This is a separate entry from the capability entries. Any startup script, health check or troubleshooting step that calls one of these binaries will need changing, because the notes list their removal as a breaking change without offering a replacement.

PostgreSQL storage: Workload Identity over Managed Identity #

The physical/postgresql entry in the v2.2.0 notes is labelled a breaking change. PostgreSQL storage backend authentication now prefers Azure Workload Identity over Managed Identity. The notes state that go-pgmultiauth is updated to v1.1.0 for this change.

The notes state that existing Managed Identity-based PostgreSQL configurations may stop working if Workload Identity is configured. They also state that affected users must migrate PostgreSQL authentication to Workload Identity. The notes tie the possible failure to the presence of Workload Identity configuration, so an operator with Managed Identity settings should check whether Workload Identity is also configured in the same environment.

The notes give no fallback path and no timing for the migration. Scheduling the migration relative to the upgrade is the author's recommendation, not a statement from the notes. A staging check of storage connectivity before production is a reasonable way to confirm the change in a given environment.

ACME finalization and SAN types in PKI #

The PKI entry in the v2.2.0 notes changes ACME finalization under the default sign-verbatim directory policy. Finalization now rejects CSRs that contain URI SANs, email SANs or Other SANs. The notes give the reason as stated by the release: ACME challenges verify only DNS names and IP addresses, those other SAN types are never validated, and they must not appear in issued certificates.

Operators who need the previous behaviour can set default_directory_policy to sign-verbatim-unsafe in config/acme. The notes say that the resulting certificates may contain unverified identity claims, so the override is a choice that carries a stated consequence. The same entry appears in the v2.2.0-rc1 notes.

For ACME clients, the practical check is the CSR content. The notes do not describe any other way to issue certificates with these SAN types under the default policy. A team that wants to keep the default policy would need CSRs that carry only DNS names and IP addresses, which is the set the notes say ACME validates.

JWT revocation through token endpoints #

Under CHANGES, the v2.2.0 notes state that JWT revocation via auth/token/revoke-self and auth/token/revoke-accessor is no longer supported. They also state that auth/token/revoke and auth/token/revoke-orphan now require the full JWT to revoke an OAuth JWT, and that these two endpoints reject the internal stored JWT ID form. The notes add that non-JWT Vault token behaviour is unchanged.

Automation that revokes OAuth JWTs through revoke-self or revoke-accessor is the group the notes describe as affected. Automation that passes the internal stored JWT ID to revoke or revoke-orphan is also affected, because the notes say those endpoints reject that form. Scripts that handle only non-JWT Vault tokens fall outside the stated change.

The notes do not say to use revoke or revoke-orphan as a replacement for the removed endpoints. They state only that these two endpoints remain and require the full JWT. Moving revocation calls to them is an inference, and it should be checked against the behaviour in a test environment.

Release-note dating #

The v2.2.0-rc1 page text reads October 07, 2026, while the metadata for the same excerpt gives a date of 2026-10-08. The v2.2.0 notes are dated October 15, 2026. This article reports the dates as the excerpts show them and does not infer a release order beyond what the notes state.

Upgrade checklist #

1. Identify the Vault container image you run, and confirm from its build which cap_ipc_lock state applies, since the notes list both entries without saying which build each one applies to.
2. If the image is built with the removal entry, set disable_mlock = true in Vault's configuration, as the notes instruct. Do not apply this setting to an image without that build, because the notes make it conditional on the removal.
3. For the removal build, disable swapping on the hosts, as the notes advise for data safety.
4. For the set build, add IPC_LOCK capabilities to the container runtime configuration when running the Vault container, as the notes state.
5. Search startup scripts, health checks and troubleshooting runbooks for gnupg, openssl and procps, and replace any calls to them in the UBI-based images.
6. Check each PostgreSQL storage configuration for Managed Identity use, and check whether Workload Identity is also configured. If both are present, migrate PostgreSQL authentication to Workload Identity, as the notes require for affected users.
7. Review ACME clients and CSR templates for URI, email or Other SANs. Remove them, or decide explicitly to use sign-verbatim-unsafe and accept the consequence the notes describe.
8. Search automation for calls to auth/token/revoke-self and auth/token/revoke-accessor that revoke OAuth JWTs. Update those calls, and test whether auth/token/revoke or auth/token/revoke-orphan with the full JWT meets the same need. The choice of replacement is the author's inference.
9. Author's recommendation, not a stated requirement: run the changes above in a staging environment that matches production. Cover container start-up, storage connectivity, certificate issuance and token revocation.
10. Author's recommendation, not a stated requirement: after staging passes, roll out to production and monitor start-up logs, storage authentication, certificate issuance and revocation results.