»Overview
This page contains the list of deprecations and important or breaking changes for Vault 1.12.x compared to 1.11. Please read it carefully.
Changes
Supported Storage Backends
Vault Enterprise will now perform a supported storage check at startup. There is no impact on open-source Vault users.
For enterprise customers, HashiCorp provides official support for Vault's Integrated Storage and Consul as storage backends. Vault Enterprise customers are strongly recommended to use these supported storage backends for best outcomes. Version 1.12.0 of Vault Enterprise will not start if configured to use a storage backend other than Integrated Storage or Consul. This was meant to protect against issues caused by using unsupported backends that do not support transactional storage. Version 1.12.2 modified this behavior to instead log a warning when unsupported storage backends are used, while ensuring that Vault will start.
Consul Dataplane Compatibility
If you are using Consul on Kubernetes, please be aware that upgrading to Consul 1.14.0 will impact Consul secrets, storage, and service registration. As of Consul 1.14.0, Consul on Kubernetes uses Consul Dataplane by default instead of client agents. Vault does not currently support Consul Dataplane. Please follow the Consul 1.14.0 upgrade guide to ensure that your Consul on Kubernetes deployment continues to use client agents.
Known Issues
Pinning to builtin plugin versions may cause failure on upgrade
1.12.0 introduced plugin versions, and with it, the ability to explicitly specify
the builtin version of a plugin when mounting an auth, database or secrets plugin.
For example, vault auth enable -plugin-version=v1.12.0+builtin.vault approle
. If
there are any mounts where the builtin version was explicitly specified in this way,
Vault may fail to start on upgrading to 1.12.1 due to the specified version no
longer being available.
To check whether a mount path is affected, read the tune information, or the
database config. The affected plugins are snowflake-database-plugin@v0.6.0+builtin
and any plugins with +builtin.vault
metadata in their version.
In this example, the first two mounts are affected because plugin_version
is
explicitly set and is one of the affected versions. The third mount is not
affected because it only has +builtin
metadata, and is not the Snowflake
database plugin. All mounts where the version is omitted, or the plugin is
external (regardless of whether the version is specified) are unaffected.
NOTE: Make sure you use Vault CLI 1.12.0 or later to check mounts.
As it is not currently possible to unset the plugin version, there are 3 possible remediations if you have any affected mounts:
- Upgrade Vault directly to 1.12.2 once released
- Upgrade to an external version of the plugin before upgrading to 1.12.1;
- Using the tune API for auth methods
- Using the tune API for secrets plugins
- Or using the configure connection API for database plugins
- Unmount and remount the path without a version specified before upgrading to 1.12.1. Note: This will delete all data and leases associated with the mount.
The bug was introduced by commit https://github.com/hashicorp/vault/commit/c36330f4c713b886a8a23c08cbbd862a7c530fc8.
Impacted Versions
Affects upgrading from 1.12.0 to 1.12.1. All other upgrade paths are unaffected. 1.12.2 will introduce a fix that enables upgrades from affected deployments of 1.12.0.
Mounts associated with deprecated builtin plugins will result in core shutdown on upgrade
As of 1.12.0 Standalone (logical) DB Engines and the AppId Auth Method have been
marked with the Pending Removal
status. Any attempt to unseal Vault with
mounts backed by one of these builtin plugins will result in an immediate
shutdown of the Vault core.
NOTE In the event that an external plugin with the same name and type as a deprecated builtin is deregistered, any subsequent unseal of Vault will also result in a core shutdown.
The remediation for affected mounts is to set the
VAULT_ALLOW_PENDING_REMOVAL_MOUNTS
environment variable and replace any Pending Removal
feature with the
preferred alternative
feature.
For more information on the phases of deprecation, see the Deprecation Notices FAQ.
Impacted Versions
Affects upgrading from any version of Vault to 1.12.x. All other upgrade paths are unaffected.
vault plugin list
fails when audit logging is enabled
If audit logging is enabled, Vault will fail to audit the response from any
calls to the GET /v1/sys/plugins/catalog
endpoint, which causes the whole request to fail and return a 500 internal
server error. From the CLI, this looks like the following:
It will produce errors in Vault Server's logs such as:
As a workaround, listing plugins by type will succeed:
vault list sys/plugins/catalog/auth
vault list sys/plugins/catalog/database
vault list sys/plugins/catalog/secret
The bug was introduced by commit https://github.com/hashicorp/vault/commit/76165052e54f884ed0aa2caa496083dc84ad1c19.
Impacted Versions
Affects versions 1.12.0, 1.12.1, and 1.12.2. A fix will be released in 1.12.3.