mirror of
https://github.com/hashicorp/vault.git
synced 2025-11-20 10:11:34 +01:00
d23892d803
* Add known issue for hsm duplicate * update wording * swap: * more clarification * clean up * clean up * clean up * reorder * reorder * link
236 lines
8.0 KiB
Plaintext
236 lines
8.0 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Upgrade to Vault 1.16.x - Guides
|
|
description: |-
|
|
Deprecations, important or breaking changes, and remediation recommendations
|
|
for anyone upgrading to 1.16.x from Vault 1.15.x.
|
|
---
|
|
|
|
# Overview
|
|
|
|
The Vault 1.16.x upgrade guide contains information on deprecations, important
|
|
or breaking changes, and remediation recommendations for anyone upgrading from
|
|
Vault 1.15. **Please read carefully**.
|
|
|
|
## Important changes
|
|
|
|
### External plugin variables take precedence over system variables ((#external-plugin-variables))
|
|
|
|
Vault gives precedence to plugin environment variables over system environment
|
|
variables when loading external plugins. The behavior for builtin plugins and
|
|
plugins that do not specify additional environment variables is unaffected.
|
|
|
|
For example, if you register an external plugin with `SOURCE=child` in the
|
|
[env](/vault/api-docs/system/plugins-catalog#env) parameter but the main Vault
|
|
process already has `SOURCE=parent` defined, the plugin process starts
|
|
with `SOURCE=child`.
|
|
|
|
Refer to the [plugin management](/vault/docs/plugins/plugin-management) page for
|
|
more details on plugin environment variables.
|
|
|
|
<Highlight title="Avoid conflicts with containerized plugins">
|
|
|
|
Containerized plugins do not inherit system-defined environment variables. As
|
|
a result, containerized plugins cannot have conflicts with Vault environment
|
|
variables.
|
|
|
|
</Highlight>
|
|
|
|
#### How to opt out
|
|
|
|
To opt out of the precedence change, set the
|
|
`VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING` environment variable to `true` for the
|
|
main Vault process:
|
|
|
|
```shell-session
|
|
$ export VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING=true
|
|
```
|
|
|
|
Setting `VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING` to `true` tells Vault to:
|
|
|
|
1. prioritize environment variables from the Vault server environment whenever
|
|
the system detects a variable conflict.
|
|
1. report on plugin variable conflicts during the unseal process by printing
|
|
warnings for plugins with conflicting environment variables or logging an
|
|
informational entry when there are no conflicts.
|
|
|
|
For example, assume you set `VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING` to `true`
|
|
and have an environment variable `SOURCE=parent`.
|
|
|
|
If you register an external plugin called `myplugin` with `SOURCE=child`, the
|
|
plugin process starts with `SOURCE=parent` and Vault reports a conflict for
|
|
`myplugin`.
|
|
|
|
### LDAP auth login changes
|
|
|
|
Users cannot log in using LDAP unless the LDAP plugin is configured
|
|
with an `userdn` value scoped to an organization unit (OU) where the
|
|
user resides.
|
|
|
|
### LDAP auth entity alias names no longer include upndomain
|
|
|
|
The `userattr` field on the LDAP auth config is now used as the entity alias.
|
|
Prior to 1.16, the LDAP auth method would detect if `upndomain` was configured
|
|
on the mount and then use `<cn>@<upndomain>` as the entity alias value.
|
|
|
|
The consequence of not configuring this correctly means users may not have the
|
|
correct policies attached to their tokens when logging in.
|
|
|
|
#### How to opt out
|
|
|
|
To opt out of the entity alias change, update the `userattr` field on the config:
|
|
|
|
```
|
|
userattr="userprincipalname"
|
|
```
|
|
|
|
Refer to the [LDAP auth method (API)](/vault/api-docs/auth/ldap) page for
|
|
more details on the configuration.
|
|
|
|
### Secrets Sync now requires setting a one-time flag before use
|
|
|
|
To use the Secrets Sync feature, the feature must be activated with a new one-time
|
|
operation called an activation-flag. The feature is gated until a Vault operator
|
|
decides to trigger the flag. More information can be found in the
|
|
[secrets sync documentation](/vault/docs/sync#activating-the-feature).
|
|
|
|
### Activity Log Changes
|
|
|
|
#### Default Activity Log Querying Period
|
|
|
|
As of 1.16.13 and later, the field `default_report_months` can no longer be configured or read. Any previously set values
|
|
will be ignored by the system.
|
|
|
|
|
|
Attempts to modify `default_report_months` through the
|
|
[/sys/internal/counters/config](/vault/api-docs/system/internal-counters#update-the-client-count-configuration)
|
|
endpoint, will result in the following warning from Vault:
|
|
|
|
<CodeBlockConfig hideClipboard>
|
|
|
|
```shell-session
|
|
|
|
WARNING! The following warnings were returned from Vault:
|
|
|
|
* default_report_months is deprecated: defaulting to billing start time
|
|
|
|
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
|
|
The `current_billing_period` toggle for `/sys/internal/counters/activity` is also deprecated, as this will be set
|
|
true by default.
|
|
|
|
Attempts to set `current_billing_period` will result in the following warning from Vault:
|
|
|
|
<CodeBlockConfig hideClipboard>
|
|
|
|
```shell-session
|
|
|
|
WARNING! The following warnings were returned from Vault:
|
|
|
|
* current_billing_period is deprecated; unless otherwise specified, all requests will default to the current billing period
|
|
|
|
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
### Auto-rolled billing start date
|
|
|
|
As of 1.16.7 and later, the billing start date (license start date if not configured) automatically rolls over to the latest billing year at the end of the last cycle.
|
|
|
|
@include 'auto-roll-billing-start.mdx'
|
|
|
|
@include 'auto-roll-billing-start-example.mdx'
|
|
|
|
### Docker image no longer contains `curl`
|
|
|
|
As of 1.16.7 and later, the `curl` binary is no longer included in the published Docker container
|
|
images for Vault and Vault Enterprise. If your workflow depends on `curl` being available in the
|
|
container, consider one of the following strategies:
|
|
|
|
#### Create a wrapper container image
|
|
|
|
Use the HashiCorp image as a base image to create a new container image with `curl` installed.
|
|
|
|
```Dockerfile
|
|
FROM hashicorp/vault-enterprise
|
|
RUN apk add curl
|
|
```
|
|
|
|
**NOTE:** While this is the preferred option it will require managing your own registry and rebuilding new images.
|
|
|
|
#### Install it at runtime dynamically
|
|
|
|
When running the image as root (not recommended), you can install it at runtime dynamically by using the `apk` package manager:
|
|
|
|
```shell-session
|
|
docker exec <CONTAINER-ID> apk add curl
|
|
```
|
|
```shell-session
|
|
kubectl exec -ti <NAME> -- apk add curl
|
|
```
|
|
|
|
When running the image as non-root without privilege escalation (recommended) you can use existing
|
|
tools to install a static binary of `curl` into the `vault` users home directory:
|
|
|
|
```shell-session
|
|
docker exec <CONTAINER-ID> wget https://github.com/moparisthebest/static-curl/releases/latest/download/curl-amd64 -O /home/vault/curl && chmod +x /home/vault/curl
|
|
```
|
|
```shell-session
|
|
kubectl exec -ti <NAME> -- wget https://github.com/moparisthebest/static-curl/releases/latest/download/curl-amd64 -O /home/vault/curl && chmod +x /home/vault/curl
|
|
```
|
|
|
|
**NOTE:** When using this option you'll want to verify that the static binary comes from a trusted source.
|
|
|
|
### Product usage reporting
|
|
|
|
As of 1.16.13, Vault will collect anonymous product usage metrics for HashiCorp. This information will be collected
|
|
alongside client activity data, and will be sent automatically if automated reporting is configured, or added to manual
|
|
reports if manual reporting is preferred.
|
|
|
|
See the main page for [Vault product usage metrics reporting](/vault/docs/enterprise/license/product-usage-reporting) for
|
|
more details, and information about opt-out.
|
|
|
|
## Known issues and workarounds
|
|
|
|
@include 'known-issues/1_17_audit-log-hmac.mdx'
|
|
|
|
@include 'known-issues/1_16-jwt_auth_bound_audiences.mdx'
|
|
|
|
@include 'known-issues/1_16-jwt_auth_config.mdx'
|
|
|
|
@include 'known-issues/1_16-ldap_auth_login_anonymous_group_search.mdx'
|
|
|
|
@include 'known-issues/1_16-ldap_auth_login_missing_entity_alias.mdx'
|
|
|
|
@include 'known-issues/1_16-default-policy-needs-to-be-updated.mdx'
|
|
|
|
@include 'known-issues/1_16-default-lcq-pre-1_9-upgrade.mdx'
|
|
|
|
@include 'known-issues/ocsp-redirect.mdx'
|
|
|
|
@include 'known-issues/1_16_azure-secrets-engine-client-id.mdx'
|
|
|
|
@include 'known-issues/perf-standbys-revert-to-standby.mdx'
|
|
|
|
@include 'known-issues/1_13-reload-census-panic-standby.mdx'
|
|
|
|
@include 'known-issues/autopilot-upgrade-upgrade-version.mdx'
|
|
|
|
@include 'known-issues/1_16_secrets-sync-chroot-activation.mdx'
|
|
|
|
@include 'known-issues/config_listener_proxy_protocol_behavior_issue.mdx'
|
|
|
|
@include 'known-issues/dangling-entity-aliases-in-memory.mdx'
|
|
|
|
@include 'known-issues/duplicate-identity-groups.mdx'
|
|
|
|
@include 'known-issues/manual-entity-merge-does-not-persist.mdx'
|
|
|
|
@include 'known-issues/duplicate-hsm-key.mdx'
|
|
|