mirror of
https://github.com/hashicorp/vault.git
synced 2025-11-19 17:51:42 +01:00
d23892d803
* Add known issue for hsm duplicate * update wording * swap: * more clarification * clean up * clean up * clean up * reorder * reorder * link
208 lines
7.5 KiB
Plaintext
208 lines
7.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Upgrade to Vault 1.17.x - Guides
|
|
description: |-
|
|
Deprecations, important or breaking changes, and remediation recommendations
|
|
for anyone upgrading to 1.17.x from Vault 1.16.x.
|
|
---
|
|
|
|
# Overview
|
|
|
|
The Vault 1.17.x upgrade guide contains information on deprecations, important
|
|
or breaking changes, and remediation recommendations for anyone upgrading from
|
|
Vault 1.16. **Please read carefully**.
|
|
|
|
## Important changes
|
|
|
|
<a id="audit-headers" />
|
|
|
|
### Allowed audit headers now have unremovable defaults
|
|
|
|
The [config auditing API endpoint](/vault/api-docs/system/config-auditing#create-update-audit-request-header)
|
|
tells Vault to log incoming request headers (when present) in the audit log.
|
|
|
|
Previously, Vault only logged headers that were explicitly configured for
|
|
logging. As of version 1.17, Vault automatically logs a predefined set of
|
|
[default headers](/vault/docs/audit#default-headers). By default, the header
|
|
values are not HMAC encrypted. You must explicitly configure the
|
|
[HMAC setting](/vault/api-docs/system/config-auditing#hmac) for each of the
|
|
default headers if required.
|
|
|
|
Refer to the
|
|
[audit request headers documentation](/vault/docs/audit#audit-request-headers)
|
|
for more information.
|
|
|
|
<a id="pki-truncate" />
|
|
|
|
### PKI sign-intermediate now truncates notAfter field to signing issuer
|
|
|
|
Prior to 1.17.x, Vault allowed the calculated sign-intermediate `notAfter` field
|
|
to go beyond the signing issuer `notAfter` field. The extended value lead to a
|
|
CA chain that would not validate properly. As of 1.17.x, Vault truncates the
|
|
intermediary `notAfter` value to the signing issuer `notAfter` if the calculated
|
|
field is greater.
|
|
|
|
#### How to opt out
|
|
|
|
You can use the new `enforce_leaf_not_after_behavior` flag on the
|
|
sign-intermediate API along with the `leaf_not_after_behavior` flag for the
|
|
signing issuer to opt out of the truncating behavior.
|
|
|
|
When you set `enforce_leaf_not_after_behavior` to true, the sign-intermediate
|
|
API uses the `leaf_not_after_behavior` value configured for the signing issuer
|
|
to control truncation the behavior. Setting the issuer `leaf_not_after_behavior`
|
|
field to `permit` and `enforce_leaf_not_after_behavior` to true restores the
|
|
legacy behavior.
|
|
|
|
<a id="request-limiter" />
|
|
|
|
### Request limiter deprecation
|
|
|
|
Vault 1.16.0 included an experimental request limiter. The limiter was disabled
|
|
by default. Further testing indicated that an alternative approach improves
|
|
performance and reduces risk for many workloads. Vault 1.17.0 includes a
|
|
new [adaptive overload
|
|
protection](/vault/docs/concepts/adaptive-overload-protection) feature that
|
|
prevents outages when Vault is overwhelmed by write requests. Adaptive overload
|
|
protection is a beta feature in 1.17.0 and is disabled by default.
|
|
|
|
The beta request limiter will be removed from Vault entirely in a later release.
|
|
|
|
### JWT auth login requires bound audiences on the role
|
|
|
|
The `bound_audiences` parameter of "jwt" roles is **mandatory** if the JWT contains an audience
|
|
(which is more often than not the case), and **must** match at least one of
|
|
the JWT's associated `aud` claims. The `aud` claim claim can be a single string
|
|
or a list of strings as per [RFC 7519 Section 4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3).
|
|
If the JWT's `aud` claim is not set, then the role's `bound_audiences`
|
|
parameter is not required.
|
|
|
|
Users may not be able to log into Vault if the JWT role is configured
|
|
incorrectly. For additional details, refer to the
|
|
[JWT auth method (API)](/vault/api-docs/auth/jwt) documentation.
|
|
|
|
### Activity Log Changes
|
|
|
|
#### Default Activity Log Querying Period
|
|
|
|
As of 1.17.9 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.17.3 and later, the billing start date (license start date if not configured) 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.17.3 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.17.9, 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/ocsp-redirect.mdx'
|
|
|
|
@include 'known-issues/agent-and-proxy-excessive-cpu-1-17.mdx'
|
|
|
|
@include 'known-issues/config_listener_proxy_protocol_behavior_issue.mdx'
|
|
|
|
@include 'known-issues/transit-input-on-cmac-response.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/aws-auth-external-id.mdx'
|
|
|
|
@include 'known-issues/sync-activation-flags-cache-not-updated.mdx'
|
|
|
|
@include 'known-issues/duplicate-hsm-key.mdx'
|