Hashicorp Vault Knowledge Patch

HashiCorp Vault Knowledge Patch

Use this skill when planning, implementing, reviewing, or troubleshooting modern Vault deployments, clients, plugins, policies, authentication, secrets engines, PKI, integrated storage, or upgrades. Prefer the repository's manifests, configuration, running-server behavior, and tests when they disagree with this guidance.

Reference index

Upgrade blockers first

Remove duplicate HCL attributes

Duplicate attributes in server configuration and policy HCL are hard parse errors. The temporary compatibility environment variable is gone. Find and remove duplicates before starting an upgraded server.

Set integrated-storage memory locking explicitly

When using integrated storage, configure disable_mlock explicitly as true or false; omission prevents startup. Current containers cannot call mlock(), so container deployments normally set it to true and prevent swap at the host or runtime layer.

Migrate retired authentication and credential modes

• The Active Directory secrets plugin is retired; migrate its workloads.
• Snowflake password authentication is retired; use key-pair authentication.
• Centrify authentication is no longer officially supported.
• Exact-match list policy comparison is retired; use per-element matching.
• The Vault Agent API proxy is deprecated; use Vault Proxy.
• Remove the obsolete LDAP deny_null_bind setting.

Check plugin signing compatibility

Enterprise releases 1.19.17, 1.20.11, 1.21.6, and 2.0.1 cannot verify the renewed signing key used by Enterprise plugins released on or after April 21, 2026. Upgrade to the patched release in the same line before registering such plugins.

Account for changed API schemas and statuses

• Managed-key usage values are names such as encrypt and sign, not integers.
• Activity exports use token_creation_time instead of timestamp.
• Utilization bundles use snapshot_records and decoded_snapshot.
• Invalid cross-cluster consistency tokens may return HTTP 403 instead of 412.
• External-CA pem_bundle certificate fields can include a private key.
• AWS credential consumers should read session_token, not security_token.

See Migration and known issues for the complete upgrade checklist and unresolved release-line issues.

Authentication, identity, and ACL quick reference

Harden privileged and forwarded authentication

• Root generation, DR operation-token generation, and rekey endpoints authenticate callers by default. Opt into legacy unauthenticated access only with enable_unauthenticated_access.
• Vault strips Vault tokens from forwarded Authorization headers unless the header is explicitly configured for passthrough.
• Certificate auth accepts RFC 9440 forwarded certificate headers and can work behind a TLS-terminating proxy even when listener TLS is disabled.
• Validate and constrain trusted proxy headers; X-Forwarded-For values must be valid IP addresses.

Update identity and policy controls

• Entity merges require sudo; merges involving SCIM-managed entities are rejected.
• Enable force_identity_deduplication only when intentionally resolving duplicate entities and groups by rename.
• allowed_parameters and denied_parameters use per-element list matching. Policy names are lowercased before constraint evaluation.
• Set deny_slash_in_templated_path = true when rendered identity values must never create additional path segments.
• Wildcards in rendered identity templates are rejected, and resultant-acl includes segment-wildcard paths in glob_paths.

Adopt workload identity features deliberately

Vault can authenticate SPIFFE JWTs and X.509 identities and can issue JWT-SVIDs. Its OAuth resource server can authorize registered agents with JWTs and apply Rich Authorization Request constraints. Enterprise SCIM manages entities, aliases, and groups but preserves a strict ownership boundary around managed entities.

See Authentication, identity, and policy for exact fields, endpoints, and auth-method behavior.

Server and storage quick reference

Detect removed or unhealthy nodes

Use sys/health, sys/seal-status, and vault status to distinguish a removed node from an unhealthy standby. Do not reuse Raft data from a removed node: join rejects it, and removed nodes stop serving requests and seal.

Bound requests and queues

• Configure JSON nesting, string, object-entry, and array-element limits.
• Configure max_token_header_size; it defaults to 8 KB and -1 disables it.
• Event subscriber queues are unbuffered by default. A positive VAULT_EVENT_NOTIFICATIONS_BOUNDED_QUEUE_SIZE enables a bounded buffer up to 1000 but can trade backpressure for missed events.
• Large random-byte responses use correspondingly more memory.

Operate snapshots and seals safely

Enterprise snapshot loading supports delegated recovery and recovery into a different path. Automated snapshots can be autoloaded, and a forced unload can clear a stuck snapshot. Seal HA requires every seal to be healthy before persisting the barrier keyring.

See Server, cluster, and storage for health codes, listener settings, Raft details, storage credentials, and diagnostics.

Secrets and rotation quick reference

Treat partial updates and rotations explicitly

• AWS secrets configuration writes preserve omitted fields; send a zero value to clear an existing field.
• Rotation Manager schedules are UTC. Configure retries and monitor orphaned entries after exhausted attempts.
• Manually rotating an LDAP static role does not reset its automated TTL. Toggle disable_automated_rotation to start a new cadence.
• Space Azure static-role rotations by several minutes to avoid propagation races and orphaned credentials.

Protect synchronization and recovery

Secret Sync destinations support workload identity, network allowlists, and GCP customer-managed encryption keys. force_delete can leave provider-side secrets orphaned, while disabling or deleting a source mount unsyncs secrets immediately. Snapshot recovery supports KV v1, KV v2, cubbyhole, database static-role, and SSH CA recovery where applicable.

See Secrets, rotation, and synchronization for engine-specific migration and operational details.

PKI and cryptography quick reference

Enforce issuance constraints

PKI enforces issuer extensions, name constraints, chain validation, path length, and configured maximum TTLs. Use leaf_not_after_behavior = "always_enforce_err" when overlong leaf lifetimes must fail even for CA and ACME issuance. Bound CRL growth with max_crl_entries.

Handle modern algorithms and managed keys

Transit supports post-quantum signatures, RSA PKCS#1 v1.5 encryption, AES-CBC, envelope encryption, and managed-key operations according to edition and feature maturity. PKCS#11 slot and token_label are mutually exclusive; clear the old selector while setting the new one.

Treat certificate bundles as secrets

External CA responses requested as pem_bundle can place the private key in the certificate field. Protect logs, caches, and parsers that handle that field.

See PKI, Transit, and managed keys for algorithms, protocols, constraints, and managed-key endpoint support.

Plugins, agents, delivery, and UI

Register plugins from the intended artifact

External plugin registration expects an extracted artifact in the plugin directory. Official-plugin automatic downloads are beta, and Enterprise can override pinned versions when mounting or tuning supported backends. Prefer the detailed registration client APIs; the older RegisterPlugin variants are deprecated.

Prepare minimal containers

Containers run as the vault user, lack built-in IPC_LOCK, and UBI images no longer include gnupg, openssl, or procps. Supply required operational tools separately rather than assuming they exist in the image.

Update UI links and automation

Secrets-engine UI routes use /secrets-engines, and the list no longer supports bulk deletion. Pagination has a known issue when page size changes away from page 1. Root-token GUI access under an EGP can fail for the UI mounts endpoint; use CLI/API access or explicitly permit that endpoint.

See Plugins, agents, and delivery and Audit, events, billing, and UI for delivery mechanisms, UI capabilities, reporting, and event semantics.

Review workflow

1. Identify the exact Vault edition, release, enabled plugins, and storage type.
2. Read the migration reference before changing binaries or container tags.
3. Validate listener, seal, storage, and policy configuration in a non-production environment.
4. Exercise authentication, rotation, lease, event, and recovery workflows that the deployment actually uses.
5. Update clients for changed fields, endpoints, status codes, and retry rules.
6. Inspect audit, billing, utilization, and rotation evidence after rollout.