--- 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 ### 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. ### 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. ### 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: ```shell-session WARNING! The following warnings were returned from Vault: * default_report_months is deprecated: defaulting to billing start time ``` 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: ```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 ``` ### 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 apk add curl ``` ```shell-session kubectl exec -ti -- 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 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 -- 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'