Agent Skills: HashiCorp Vault Knowledge Patch

HashiCorp Vault Knowledge Patch

Load this skill when configuring, upgrading, integrating, or troubleshooting Vault. It emphasizes changed defaults, removals, request and response schema changes, edition-specific behavior, and operational hazards.

How to use this skill

1. Determine the exact server, CLI, SDK, plugin, and provider versions in use.
2. Distinguish Community and Enterprise features before proposing a design.
3. Read the topic reference for every subsystem touched by the change.
4. Apply breaking-change and upgrade-safety guidance before new-feature advice.
5. Validate paths, response fields, listener settings, and policy semantics against the deployed release rather than assuming old behavior persists.
6. For clustered changes, test standby, secondary, seal, snapshot, and event behavior as applicable—not just an active-node happy path.
7. For secrets and identity changes, plan rollback around externally created credentials, synchronized copies, and ownership boundaries.

Reference index

| Reference | Topics | | --- | --- | | operations-and-upgrades.md | Server configuration, containers, Raft, snapshots, storage, recovery, cluster health, upgrade issues | | authentication-and-policy.md | Auth methods, identities, SCIM, OAuth resource servers, ACLs, policy templates | | pki-and-cryptography.md | Transit, PKI, ACME, SCEP, KMIP, managed keys, FIPS, TLS | | secrets-and-rotation.md | Secrets engines, static and root rotation, Secret Sync, databases, secret delivery | | audit-events-and-telemetry.md | Audit schemas, events, utilization, billing, logs, metrics | | plugins-ui-and-clients.md | Plugin packaging, registration APIs, SDKs, listener limits, GUI routes |

Breaking changes and removals

Reject duplicate HCL

Duplicate server-configuration and policy attributes are parsing errors. Do not rely on the former warning-only compatibility switch; it is gone. Search and deduplicate keys before deployment. See operations and upgrades.

Remove Snowflake password authentication

Snowflake database connections must no longer use password authentication. Plan a key-pair migration and account for the separate key-pair refresh issue on affected older release lines. See secrets and rotation.

Migrate retired integrations

The Active Directory secrets plugin is retired, and Centrify authentication is no longer officially supported. Replace both before an upgrade depends on their continued availability. See secrets and rotation and authentication and policy.

Use per-element list-policy matching

Exact-match comparison for list-valued allowed_parameters and denied_parameters is retired. Write constraints for per-element contains-all matching, and remember that policy names are lowercased before constraint evaluation. See authentication and policy.

Stop using the token-counter endpoint

/sys/internal/counters/tokens returns an unsupported-path 403. Replace it with supported activity, utilization, or billing interfaces. See operations and upgrades and audit and telemetry.

Set integrated-storage memory locking explicitly

An integrated-storage server will not start if disable_mlock is omitted. Containers cannot call mlock() in the current image behavior, so set disable_mlock = true there and prevent swapping outside Vault. See operations and upgrades.

Supply removed UBI utilities yourself

Do not assume gnupg, openssl, or procps exists inside a UBI image. Add a separate tool image or package layer for scripts and diagnostics that need them. See operations and upgrades.

Replace the Agent API proxy

Built-in API proxying in Vault Agent is deprecated and pending removal. Move proxy workloads to Vault Proxy. See plugins, UI, and clients.

Enforce Azure auth bindings and stored precedence

Azure auth requires a bound group or service-principal ID. Stored plugin configuration wins over AZURE_* environment variables, so move intended values into auth/azure/config. See authentication and policy.

Respect token-header limits

Listeners cap Vault token and bearer-authorization headers at 8 KB by default. Reduce oversized tokens or explicitly configure the listener; use -1 only after assessing the operational tradeoff. See plugins, UI, and clients.

Treat SCIM-managed identities as externally owned

Entity merge cannot move aliases, policies, or memberships across the SCIM-managed ownership boundary, even for privileged callers. Reconcile those changes through the managing SCIM client. See authentication and policy.

Treat External CA PEM bundles as secret material

An External CA pem_bundle certificate response includes the private key in the certificate field. Protect logs, caches, and parsers that handle it. See PKI and cryptography.

Reclassify invalid cross-cluster tokens

Invalid cross-cluster consistency tokens at an active performance secondary prefer HTTP 403 rather than 412. Update retry and authorization-error logic. See operations and upgrades.

Upgrade-safety checklist

• Remove duplicate HCL attributes and deprecated configuration fields.
• Confirm Azure auth values are stored where precedence rules will read them.
• Space Azure static-role rotations to allow cloud propagation.
• Upgrade away from plugin-signing-key verification failures before registering newly released Enterprise plugins.
• Preserve rekey nonces for cancellation automation.
• Verify container startup, memory locking, and required diagnostic utilities.
• Exercise snapshot load, delegated recovery, unload, and destination-path restore before relying on disaster recovery.
• Test policy paths containing wildcards, trailing slashes, and rendered identity values under the stricter rules.
• Check GUI workarounds independently from CLI/API access.
• Verify event consumers tolerate bounded-queue loss and status-code changes.

The detailed version-specific fixes and known issues are in operations and upgrades and the subsystem references.

High-value feature guidance

Snapshot recovery

Enterprise recovery can load snapshots, delegate recovery separately from snapshot management, restore to another live path, and recover KV v1, KV v2, cubbyhole data, selected static credentials, and an SSH CA. See operations and upgrades.

OAuth resource-server authorization

Vault can authorize requests from OAuth JWTs and apply RAR parameter controls with identity-template expressions. Validate accepted typ values and treat an empty optional authorization-details array as absent. See authentication and policy.

SCIM provisioning

Enterprise SCIM manages identities, aliases, and groups, supports multi-change PATCH operations, offers explicit filtering, and exposes direct memberships. Unsupported filters return 400. See authentication and policy.

LDAP self-managed rotation

Mount the engine as ldap, enable self_managed, and account for Rotation Manager migration, retry/orphan policy, and manual-rotation cadence. See secrets and rotation.

Transit and managed keys

Transit supports newer signature schemes, AES-CBC, derived-DEK context, envelope encryption, managed-key rewrap, and managed-key certificate operations. Parse managed-key usages as names rather than integers. See PKI and cryptography.

PKI protocol services

PKI includes SCEP, richer ACME administration, External CA workflows, managed key issuers, chain constraints, and delta-CRL advertisement. Apply the private key handling rule for External CA PEM bundles. See PKI and cryptography.

Secret Sync safeguards

Use destination allowlists, workload identity federation, and customer-managed GCP keys. Understand force_delete orphaning, mount-triggered unsync, and KV v2 fallback behavior before deleting either side. See secrets and rotation.

Event and billing consumers

Events can include consistency indexes and lease or LDAP rotation signals; billing and utilization schemas add and rename fields. Treat schema changes as API migrations rather than display-only additions. See audit, events, and telemetry.

External plugins

Place extracted artifacts before registration, use detailed registration APIs, and validate pinned-version overrides and SHA-256 data. Confirm the server line can verify the current Enterprise plugin signing key. See plugins, UI, and clients.

Task routing

For a server upgrade, begin with operations, then read every reference matching an enabled auth method, secrets engine, audit device, plugin, or UI workflow.

For policy or identity work, combine authentication guidance with the target auth or secrets-engine reference; identity templates affect both ACL paths and OAuth authorization details.

For certificate workflows, read PKI guidance plus authentication guidance when certificates are used for login, and audit guidance when OCSP or failed-login metadata enters audit records.

For rotation automation, combine secrets guidance with audit/event guidance so the schedule, retry policy, and compliance signals agree.