Upgrade to Vault 1.14.x

The Vault 1.14.x upgrade guide contains information on deprecations, important or breaking changes, and remediation recommendations for anyone upgrading from Vault 1.13. Please read carefully.

Feature deprecations and EOL

Duplicative Docker images

As of Vault 1.14 we will no longer update the the vault Docker image. Only the Verified Publisher hashicorp/vault image will be updated on DockerHub.

Users of Official Images need to use docker pull hashicorp/vault:<version> instead of docker pull vault:<version> to get newer versions of Vault in Docker images. Currently, HashiCorp publishes and updates identical Docker images of Vault as Verified Publisher and Official images separately.

Important changes

vault.raft_storage.bolt.write.time has been corrected from a summary to a counter to more accurately reflect that it is measuring cumulative time writing, and not the distribution of individual write times.

Application of Sentinel Role Governing Policies (RGPs) via identity groups

As of versions 1.15.0, 1.14.4, and 1.13.8, the Sentinel RGPSs derived from membership in identity groups apply only to entities in the same and child namespaces, relative to the identity group.

Also, the group_policy_application_mode only applies to to ACL policies. Vault Sentinel Role Governing Policies (RGPs) are not affected by group policy application mode.

Known issues and workarounds

Users limited by control groups can only access issuer detail from PKI overview page

Affected versions

• Vault 1.14.x

Issue

Vault UI users who require control group approval to read issuer details are directed to the Control Group Access page when they try to view issuer details from links on the Issuer list page.

Workaround

Vault UI users constrained by control groups should select issuers from the PKI overview page to view detailed information instead of the Issuers list page.

API calls to update-primary may lead to data loss

Affected versions

All versions of Vault before 1.14.1, 1.13.5, 1.12.9, and 1.11.12.

Issue

The update-primary endpoint temporarily removes all mount entries except for those that are managed automatically by vault (e.g. identity mounts). In certain situations, a race condition between mount table truncation replication repairs may lead to data loss when updating secondary replication clusters.

Situations where the race condition may occur:

• When the cluster has local data (e.g., PKI certificates, app role secret IDs) in shared mounts. Calling update-primary on a performance secondary with local data in shared mounts may corrupt the merkle tree on the secondary. The secondary still contains all the previously stored data, but the corruption means that downstream secondaries will not receive the shared data and will interpret the update as a request to delete the information. If the downstream secondary is promoted before the merkle tree is repaired, the newly promoted secondary will not contain the expected local data. The missing data may be unrecoverable if the original secondary is is lost or destroyed.
• When the cluster has an Allow paths defined. As of Vault 1.0.3.1, startup, unseal, and calling update-primary all trigger a background job that looks at the current mount data and removes invalid entries based on path filters. When a secondary has Allow path filters, the cleanup code may misfire in the windown of time after update-primary truncats the mount tables but before the mount tables are rewritten by replication. The cleanup code deletes data associated with the missing mount entries but does not modify the merkle tree. Because the merkle tree remains unchanged, replication will not know that the data is missing and needs to be repaired.

Workaround 1: PR secondary with local data in shared mounts

Watch for cleaning key in merkle tree in the TRACE log immediately after an update-primary call on a PR secondary to indicate the merkle tree may be corrupt. Repair the merkle tree by issuing a replication reindex request to the PR secondary.

If TRACE logs are no longer available, we recommend pre-emptively reindexing the PR secondary as a precaution.

Workaround 2: PR secondary with "Allow" path filters

Watch for deleted mistakenly stored mount entry from backend in the INFO log. Reindex the performance secondary to update the merkle tree with the missing data and allow replication to disseminate the changes. You will not be able to recover local data on shared mounts (e.g., PKI certificates).

If INFO logs are no longer available, query the shared mount in question to confirm whether your role and configuration data are present on the primary but missing from the secondary.

Using 'update_primary_addrs' on a demoted cluster causes Vault to panic

Affected versions

• 1.13.3, 1.13.4 & 1.14.0

Issue

If the update_primary_addrs parameter is used on a recently demoted cluster, Vault will panic due to no longer having information about the primary cluster.

Workaround

Instead of using update_primary_addrs on the recently demoted cluster, instead provide an activation token.

Safari login screen appears broken on the UI

Affected versions

• 1.14.0

Issue

The login screen on Safari appears to be broken, presenting as a blank white screen.

Workaround

Scroll down to find the login section.

AWS static roles ignore changes to rotation period

Affected versions

• 1.14.0+

Issue

AWS static roles currently ignore configuration changes made to the key rotation period. As a result, Vault will continue to use whatever rotation period was set when the roles were originally created.

Workaround

Delete and recreate any static role objects that should use the new rotation period.

Transit Encryption with Cloud KMS managed keys causes a panic

Affected versions

• 1.13.1+ up to 1.13.8 inclusively
• 1.14.0+ up to 1.14.4 inclusively
• 1.15.0

Issue

Vault panics when it receives a Transit encryption API call that is backed by a Cloud KMS managed key (Azure, GCP, AWS).

Workaround

None at this time

Transit Sign API calls with managed keys fail

Affected versions

• 1.14.0+ up to 1.14.4 inclusively
• 1.15.0

Issue

Vault responds to Transit sign API calls with the following error when the request uses a managed key:

requested version for signing does not contain a private part

Workaround

None at this time

Collapsed navbar does not allow you to click inside the console or namespace picker

Affected versions

The UI issue affects Vault versions 1.14.0+ and 1.15.0+. A fix is expected for Vault 1.16.0.

Issue

The Vauil UI currently uses a version of HDS that does not allow users to click within collapsed elements. In particular, the dev console or namespace picker become inaccessible when viewing the components in smaller viewports.

Workaround

Expand the width of the screen until you deactivate the collapsed view. Once the full navbar is displayed, click the desired components.

Internal error when vault policy in namespace does not exist

If a user is a member of a group that gets a policy from a namespace other than the one they’re trying to log into, and that policy doesn’t exist, Vault returns an internal error. This impacts all auth methods.

Affected versions

• 1.13.8 and 1.13.9
• 1.14.4 and 1.14.5
• 1.15.0 and 1.15.1

A fix will be released in Vault 1.15.2, 1.14.6, and 1.13.10.

Workaround

During authentication, Vault derives inherited policies based on the groups an entity belongs to. Vault returns an internal error when attaching the derived policy to a token when:

1. the token belongs to a different namespace than the one handling authentication, and
2. the derived policy does not exist under the namespace.

You can resolve the error by adding the policy to the relevant namespace or deleting the group policy mapping that uses the derived policy.

As an example, consider the following userpass auth method failure. The error is due to the fact that Vault expects a group policy under the namespace that does not exist.

# Failed login
$ vault login -method=userpass username=user1 password=123
Error authenticating: Error making API request.

URL: PUT http://127.0.0.1:8200/v1/auth/userpass/login/user1
Code: 500. Errors:

* internal error

To confirm the problem is a missing policy, start by identifying the relevant entity and group IDs:

$ vault read -format=json identity/entity/name/user1 | \
  jq '{"entity_id": .data.id, "group_ids": .data.group_ids} '
{
  "entity_id": "420c82de-57c3-df2e-2ef6-0690073b1636",
  "group_ids": [
    "6cb152b7-955d-272b-4dcf-a2ed668ca1ea"
  ]
}

Use the group ID to fetch the relevant policies for the group under the ns1 namespace:

$ vault read -format=json -namespace=ns1 \
  identity/group/id/6cb152b7-955d-272b-4dcf-a2ed668ca1ea | \
  jq '.data.policies'
[
  "group_policy"
]

Now that we know Vault is looking for a policy called group_policy, we can check whether that policy exists under the ns1 namespace:

$ vault policy list -namespace=ns1
default

The only policy in the ns1 namespace is default, which confirms that the missing policy (group_policy) is causing the error.

To fix the problem, we can either remove the missing policy from the 6cb152b7-955d-272b-4dcf-a2ed668ca1ea group or create the missing policy under the ns1 namespace.

$ vault write                                             \
  -namespace=ns1                                          \
  identity/group/id/6cb152b7-955d-272b-4dcf-a2ed668ca1ea  \
  name="test"                                             \
  policies="default"

$ vault policy write -namespace=ns1 group_policy - << EOF
    path "secret/data/*" {
        capabilities = ["create", "update"]
    }
EOF

Verify the fix by re-running the login command:

$ vault login -method=userpass username=user1 password=123

Vault is storing references to ephemeral sub-loggers leading to a memory leak

Vault is unexpectedly storing references to ephemeral sub-loggers which prevents them from being cleaned up, leading to a memory leak. This impacts many areas of Vault, but primarily logins in Enterprise. There is no workaround.

Affected versions

This issue affects Vault Community and Enterprise versions:

• 1.13.7+
• 1.14.3+
• 1.15.0+

A fix will be issued in the next release