diff --git a/content/vault/v1.21.x (rc)/content/api-docs/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/index.mdx index 98a09f8865..298b68d25e 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/index.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/index.mdx @@ -340,4 +340,19 @@ A maximum request size of 32MB is imposed to prevent a denial of service attack with arbitrarily large requests; this can be tuned per `listener` block in Vault's server configuration file. +Vault also supports several listener options to enforce payload size limits for to incoming JSON +request bodies. + +You can configure the payload limits individullly on each listener and give +administrators granular control over the: + +- maximum allowed nesting depth of a JSON object or array (`max_json_depth`). +- maximum allowed length for any single string value in the payload (`max_json_string_value_length`.) +- maximum number of key-value pairs allowed in a single JSON object (`max_json_object_entry_count`). +- maximum number of elements permitted in a single JSON array `max_json_array_element_count`. + +The configuration defaults provide intentionally generous limits to accommodate +a wide range of legitimate use cases while still guarding against most malicious +or malformed requests. + [proxy]: /vault/docs/agent-and-proxy/proxy#listener-stanza diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/azure.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/azure.mdx index 4df27472ed..71e6eb1481 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/azure.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/azure.mdx @@ -46,7 +46,10 @@ plugin workload identity federation (WIF). environment variable. If not specified, Vault will use Azure Public Cloud. - `root_password_ttl` `(string: 182d)` - Specifies how long the root password is valid for in Azure when rotate-root generates a new client secret. Uses [duration format strings](/vault/docs/concepts/duration-format). - +- `metadata` (`map[string]string: {}`) - A map of string to string key/value pairs that will be stored + as metadata for the mount. This can be used to store additional information about the + mount for reference purposes. + @include 'rotationfields.mdx' ### Sample payload @@ -214,12 +217,18 @@ information about roles. [roles docs][roles] for details on role definition. - `persist_app` (`bool: "false"`) – If set to true, persists the created service principal and application for the lifetime of the role. Useful for when the Service Principal needs to maintain ownership of objects it creates -- `ttl` (`string: ""`) – Specifies the default TTL for service principals generated using this role. +- `ttl` (`string: ""`) – Specifies the default TTL for service principals generated using the role. Accepts time suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine default TTL time. -- `max_ttl` (`string: ""`) – Specifies the maximum TTL for service principals generated using this role. Accepts time - suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine max TTL time. -- `explicit_max_ttl` (`string: ""`) – Specifies the explicit maximum lifetime of the lease and service principal. - If not set or set to 0, will use the system default (10 years). +- `max_ttl` (`string: "0"`) – Specifies the maximum TTL for service principals + generated using the role. Accepts time suffixed strings ("1h") or an integer + number of seconds. The default (`0`) defers to the system/engine max TTL time. +- `explicit_max_ttl` (`string: "0"`) – Limits the lifetime of the service + principal secret in Azure and sets an upper bound on the TTL for the + corresponding lease. You cannot update the service principle lifetime of an + existing lease and clients cannot renew a lease once the lifetime expires. + Use the default (`0`) to create the service principal with a max TTL of 10 + years. When the lifetime ends, Vault deletes the service principal and all + corresponding leases. - `permanently_delete` (`bool: false`) - Specifies whether to permanently delete Applications and Service Principals that are dynamically created by Vault. If `application_object_id` is present, `permanently_delete` must be `false`. - `sign_in_audience` (`string: ""`) - Specifies the security principal types that are allowed to sign in to the application. @@ -257,6 +266,64 @@ $ curl \ https://127.0.0.1:8200/v1/azure/roles/my-role ``` +## Read role + +The Read Role endpoint returns information about the named role: + +- Configuration details for the role +- The constant `invalid_data` for roles created in earlier versions of Vault. +- A `404` error if the named role does not exist. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/azure/roles/:name` | + + +### Path parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/azure/roles/example-role +``` + +### Sample response + +```json +{ + "data": { + "application_object_id": "", + "azure_groups": null, + "azure_roles": [ + { + "role_name": "Contributor", + "scope": "/subscriptions/>/resourceGroups/Website" + }, + { + "role_id": "/subscriptions/>/providers/Microsoft.Authorization/roleDefinitions/", + "scope": "/subscriptions/" + } + ], + "ttl": 3600, + "max_ttl": 0, + "explicit_max_ttl": 0, + "permanently_delete": false, + "persist_app": false, + "sign_in_audience": "AzureADMyOrg", + "tags": [ + "team:engineering", + "team:development" + ], + } +} +``` + + ## List roles Lists all of the roles that are registered with the plugin. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx index 7c6c586916..460ab69656 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx @@ -8,8 +8,7 @@ description: This is the API documentation for the Vault Cubbyhole secrets engin This is the API documentation for the Vault Cubbyhole secrets engine. For general information about the usage and operation of the Cubbyhole secrets -engine, please see the -[Vault Cubbyhole documentation](/vault/docs/secrets/cubbyhole). +engine, please see the [Vault Cubbyhole documentation](/vault/docs/secrets/cubbyhole). This documentation assumes the Cubbyhole secrets engine is enabled at the `/cubbyhole` path in Vault. Since it is possible to enable secrets engines at @@ -25,8 +24,8 @@ This endpoint retrieves the secret at the specified location. ### Parameters -- `path` `(string: )` – Specifies the path of the secret to read. - This is specified as part of the URL. +- `path` `(string: )` – Specifies the path of the secret to read as + part of the URL. - `read_snapshot_id` `(string: )` - Query parameter specifing a loaded snapshot ID to read the secret. @@ -152,7 +151,8 @@ $ curl \ ## Recover secret -[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot. +[Recover](/vault/docs/sysadmin/snapshots/recover-a-secret) a secret at the +specified location from the given loaded snapshot. | Method | Path | |:----------|:-------------------| diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx index 4c8f40487e..d450be840c 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx @@ -165,7 +165,8 @@ $ curl \ ## Recover secret -[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot. +[Recover](/vault/docs/sysadmin/snapshots/recover-a-secret) a secret at the +specified location from the given loaded snapshot. | Method | Path | |:----------|:----------------| diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx index 2b7e205de2..d4d643cb15 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx @@ -42,6 +42,8 @@ to search and change entry passwords in LDAP. to use to generate passwords. Note that this accepts the name of the policy, not the policy itself. - `schema` `(string: "openldap")` - The LDAP schema to use when storing entry passwords. Valid schemas include `openldap`, `ad`, and `racf`. +- `credential_type` `(string: "password")` - The type of password to generate. Valid values include `password` and `phrase`. + When set to `phrase`, the secrets engine will modify the RACF schema for all static roles to manage password phrases instead of passwords. - `userdn` `(string: )` - The base DN under which to perform user search in [library management](/vault/api-docs/secret/ldap#library-management) and [static roles](/vault/api-docs/secret/ldap#static-roles). For example, `ou=Users,dc=hashicorp,dc=com`. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx index 3b6d745289..61ff1f1e9c 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx @@ -883,6 +883,7 @@ $ curl \ "enabled": true, "external_validation": {}, "last_updated": "2025-05-26T09:59:24-04:00", + "log_level" : "WARN", "restrict_ca_chain_to_issuer": true } } @@ -940,6 +941,8 @@ refer to the [SCEP documentation](/vault/docs/secrets/pki/scep). chain within GetCACert responses. Set `restrict_ca_chain_to_issuer` to `true` to make your PKI configuration compatible with Microsoft Intune. +- `log_level` `(string: "")` - the log level to use for logging SCEP-specific requests. One of standard log levels: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or use the empty string to reset to the vault-level default. (1.20.1+ only) + - `external_validation` `(map[string]map[string]string: "")` - a map specifying configuration for 3rd party validation of SCEP requests. Map keys can be any of the following: diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/ssh.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/ssh.mdx index df75b10280..6bfc7fa96f 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/ssh.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/ssh.mdx @@ -559,13 +559,15 @@ $ curl \ ## Submit CA information This endpoint allows submitting the CA information for the secrets engine via an SSH -key pair. _If you have already set a certificate and key, they will be -overridden._ +key pair. If you call submit CA with an existing certificate or key, the +endpoint returns an error. To update existing values, call the delete CA +information endpoint before calling the submit endpoint. | Method | Path | | :----- | :--------------- | -------------------------- | | `POST` | `/ssh/config/ca` | `200/204 application/json` | + ### Parameters - `private_key` `(string: "")` – Specifies the private key part the SSH CA key @@ -649,7 +651,8 @@ This endpoint recovers the CA information for the backend via an SSH key pair. ### Headers -- `X-Vault-Recover-Snapshot-Id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains SSH CA information. +- `X-Vault-Recover-Snapshot-Id` `(string: )` - The ID of a snapshot +previously loaded into Vault that contains SSH CA information. ### Sample request diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx index 63aebe0bee..013b5ed4fc 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx @@ -70,6 +70,7 @@ values set here cannot be changed after key creation. - `aes256-cmac` - AES-256 CMAC (CMAC generation, verification) - `ml-dsa` - ML-DSA (asymmetric) (experimental) - `hybrid` - hybrid signatures combining a post-quantum algorithm and an elliptic curve algorithm (asymmetric) (experimental) + - `slh-dsa` - SLH-DSA (asymmetric) (experimental) - `aes128-cbc` - AES-128 in CBC mode (symmetric, supports derivation and convergent encryption) - `aes256-cbc` - AES-256 in CBC mode (symmetric, supports derivation and convergent encryption) @@ -102,8 +103,14 @@ values set here cannot be changed after key creation. hour. Uses [duration format strings](/vault/docs/concepts/duration-format). - `managed_key_name` `(string: "")` - The name of the managed key to use for this transit key. - `managed_key_id` `(string: "")` - The UUID of the managed key to use for this transit key. -- `parameter_set` `(string:"")` - The parameter set to use for ML-DSA. Required for -ML-DSA and hybrid keys. Valid values are `44`, `65`, and `87`. +- `parameter_set` `(string:"")` - The parameter set to use for ML-DSA or SLH-DSA. + Required for ML-DSA, SLH-DSA, and hybrid keys. Must be one of the following: + - ML-DSA - `44`, `65`, `87` + - SLH-DSA - `slh-dsa-sha2-128s`, `slh-dsa-shake-128s`, `slh-dsa-sha2-128f`, + `slh-dsa-shake-128`, `slh-dsa-sha2-192s`, + `slh-dsa-shake-192s`, `slh-dsa-sha2-192f`, `slh-dsa-shake-192f`, + `slh-dsa-sha2-256s`, `slh-dsa-shake-256s`, + `slh-dsa-sha2-256f`, and `slh-dsa-shake-256f` - `hybrid_key_type_pqc` `(string: "")` - The post-quantum algorithm to use for hybrid signatures. Currently, ML-DSA is the only supported key type. - `hybrid_key_type_ec` `(string: "")` - The elliptic curve algorithm to use for hybrid signatures. @@ -834,8 +841,9 @@ will be returned. derivation. This is required if key derivation is enabled for this key. - `key_version` `(int: 0)` – Specifies the version of the key to use for - encryption. If not set, uses the latest version. Must be greater than or - equal to the key's `min_encryption_version`, if set. + encryption. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `nonce` `(string: "")` – Specifies the **base64 encoded** nonce value. This must be provided if convergent encryption is enabled for this key and the key @@ -1073,8 +1081,9 @@ functionality to untrusted users or scripts. derivation. This is required if key derivation is enabled. - `key_version` `(int: 0)` – Specifies the version of the key to use for the - operation. If not set, uses the latest version. Must be greater than or equal - to the key's `min_encryption_version`, if set. + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `nonce` `(string: "")` – Specifies a base64 encoded nonce value used during encryption. Must be provided if convergent encryption is enabled for this key @@ -1180,6 +1189,11 @@ then made available to trusted users. It is recommended that the default of OAEP be used unless specific backwards compatibility is required. +- `key_version` `(int: 0)` – Specifies the version of the key to use for the + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. + ### Sample payload ```json @@ -1405,8 +1419,9 @@ be used. generate hmac against. This is specified as part of the URL. - `key_version` `(int: 0)` – Specifies the version of the key to use for the - operation. If not set, uses the latest version. Must be greater than or equal - to the key's `min_encryption_version`, if set. + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are: @@ -1536,8 +1551,9 @@ supports signing. use for signing. This is specified as part of the URL. - `key_version` `(int: 0)` – Specifies the version of the key to use for - signing. If not set, uses the latest version. Must be greater than or equal - to the key's `min_encryption_version`, if set. + signing. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `hash_algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use for supporting key types (notably, not including `ed25519` which specifies its @@ -1937,8 +1953,9 @@ argument to verify returned CMACs. CMAC function. This is specified as part of the URL. - `key_version` `(int: 0)` – Specifies the version of the key to use for the - operation. If not set, uses the latest version. Must be greater than or equal - to the key's `min_encryption_version`, if set. + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of `input` or `batch_input` must be supplied. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/internal-counters.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/internal-counters.mdx index bfb207c543..b1dbd6bf4b 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/internal-counters.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/internal-counters.mdx @@ -211,6 +211,18 @@ The `start_time` in the response is the earliest time there is activity data in the queried period. The `end_time` is the end of the final month of the queried period. +The `/sys/internal/counters` endpoint only supports monthly granularity. As a +result, the `start_time` and `end_time` values in API reponses are normalized to +align with full calendar months. + +Normalization occurs whether you provide explicit times in the request or use +the defaults: + +- `start_time` normalizes to the start of the month in which the effective + `start_time` falls. +- `end_time` normalizes to the end of the month in which the effective + `end_time` falls. + - If the `end_date` supplied to the API is the current month, exact activity information will be returned for all months in the queried period. The last element in the `months` response stanza will signify the current month. @@ -464,9 +476,15 @@ is unknown. ### Parameters -- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the start of the - period for which client counts will be reported. If no start time is specified, the billing start date will be used. - The [billing start date](/vault/docs/concepts/billing-start-date) automatically rolls over to the latest billing year at the end of the last cycle. +- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. + Specifies the start of the period for which client counts will be reported. + Vault uses the [billing start date](/vault/docs/concepts/billing-start-date) + by default, which automatically rolls over to the latest billing year at the + end of the last cycle. Vault Community **requires** `start_time`, but Vault + Enterprise uses the billing start date as defined by the cluster license by + default. Vault Community does not have a billing start time, so ommitting + `start_time` can lead to undefined behavior. We recommend setting an explicit + start time to ensure reliable behavior in all Vault versions. - `end_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the end of the period for which client counts will be reported. If no end time is specified, the end of the current month will be used. - `limit_namespaces` `(int, optional)` - Controls the total number of by_namespace data returned. This can @@ -1283,7 +1301,9 @@ There are a few things to keep in mind while using this API. - The response includes the actual time period covered, which may not exactly match the query parameters due to the month granularity of data or missing -months in the requested time range. +months in the requested time range. Vault always normalizes the effective +`start_time` and `end_time` to full calendar months by adjusting `start_time` to +the beginning of the month and `end_time` to the end of the month. - If the `end_date` supplied to the API is for the current month, the activity information returned by this API will include activity for this month, however @@ -1301,8 +1321,15 @@ it may be up to 20 minutes delayed. ### Parameters -- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the start of the - period for which client counts will be reported. If no start time is specified, the billing start time will be used. +- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. + Specifies the start of the period for which client counts will be reported. + Vault uses the [billing start date](/vault/docs/concepts/billing-start-date) + by default, which automatically rolls over to the latest billing year at the + end of the last cycle. Vault Community **requires** `start_time`, but Vault + Enterprise uses the billing start date as defined by the cluster license by + default. Vault Community does not have a billing start time, so ommitting + `start_time` can lead to undefined behavior. We recommend setting an explicit + start time to ensure reliable behavior in all Vault versions. - `end_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the end of the period for which client counts will be reported. If no end time is specified, the end of current month will be used. - `format` `(string, optional)` - The desired format of the output file. Allowed diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx index dd168f98a6..fb26eaf40a 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx @@ -154,7 +154,10 @@ parameters in the context of AWS EKS & S3 configuration. - `azure_account_name` `(string)` - Azure account name. -- `azure_auth_mode` `(string)` - One of `shared` or `managed`. +- `azure_auth_mode` `(string)` - One of `shared`, `managed`, or `environment`. + If `environment` is set, Azure authentication details are retrieved from the + environment variables: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, + `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`. - `azure_account_key` `(string)` - Azure account key. Used for `shared` authentication. diff --git a/content/vault/v1.21.x (rc)/content/docs/about-vault/how-vault-works.mdx b/content/vault/v1.21.x (rc)/content/docs/about-vault/how-vault-works.mdx index f94a5139dc..bc8afc0d33 100644 --- a/content/vault/v1.21.x (rc)/content/docs/about-vault/how-vault-works.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/about-vault/how-vault-works.mdx @@ -7,7 +7,6 @@ description: >- # How Vault works - Vault is an identity-based secrets and encryption management system that centralizes secret management, rotates old credentials, generates credentials on demand, audits client interactions, and supports regulatory @@ -35,7 +34,12 @@ them access to secrets or stored sensitive data. ## Core Vault workflow -Vault works primarily with tokens and a token is associated to the client's policy. Each policy is path-based and policy rules constrains the actions and accessibility to the paths for each client. With Vault, you can create tokens manually and assign them to your clients, or the clients can log in and obtain a token. The illustration below displays Vault's core workflow. +Vault works primarily with tokens associated to a client policy. The path-based +policy defines rules that constrain the actions and accessibility of the +associated paths for each client. + +Clients can authenticate against Vault to log in and obtain a token automatically +or you can create tokens manually and explicitly assign them to your clients. ![Vault Workflow](/img/vault-workflow-diagram1.png) diff --git a/content/vault/v1.21.x (rc)/content/docs/audit/best-practices.mdx b/content/vault/v1.21.x (rc)/content/docs/audit/best-practices.mdx new file mode 100644 index 0000000000..16b59897fc --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/audit/best-practices.mdx @@ -0,0 +1,104 @@ +--- +layout: docs +page_title: Audit logging best practices +description: Recommendations for setting up audit logging in HashiCorp Vault. +--- + +# Best practices for audit logging + +The following recommendations apply generally to most Vault deployments. You should always independently evaluate whether a given recommendation makes sense in the context of your deployment and use of Vault. + +## Test configuration changes + +Always test your audit logging changes in a non-production environment that closely mirrors your production environment. Your test environment should include performance benchmarking under production-like loads and match in all aspects relevant to the audit logging configuration you want to test. + +## Enable audit devices at cluster initialization + +Enable at least one audit device immediately after you initialize a new Vault cluster, and ensure that the configuration of your audit device is [valid for all Vault cluster nodes](/vault/docs/audit#enabling-and-disabling-audit-devices). + +Audit logging is disabled by default on new Vault clusters. By enabling at least one audit device post-initialization, you ensure that Vault will audit all subsequent API requests, including those for initial cluster configuration and root token revocation. + +## Enable at least two audit devices + +Enable at least two audit devices, of different types, on each Vault cluster. Configure *at least one* of those devices to forward logs to a remote system for analysis and long-term storage. + +Vault does not respond to client requests it cannot log. Enabling at least two audit devices reduces the risk of Vault not responding to client requests when the only audit device becomes partially or fully unavailable. + + + + Vault sends each audit log entry to all enabled devices, and guarantees that it writes the audit log entry successfully to at least one audit device. To ensure that you have a complete record of all API requests and responses, you **must** analyze audit log entries across all configured devices. You may deduplicate audit log entries based on the value of `.request.id`. + + + + + + + +If you enable a `file` audit device, use a dedicated volume or partition for Vault's audit logs to protect against other workloads on the system taking up the disk space intended for your log files. + +Additionally, establish a log rotation process that is appropriate for your organization, deployment, and policies, using a purpose-built system like *logrotate*. Configure your log rotation system to send Vault an `HUP` signal, which causes Vault to start writing audit log entries to the new log file. + + + + When running Vault on a Kubernetes cluster, a common approach is to configure a `file` audit device with `file_path` set to `stdout`. Vault will write audit logs to the standard output for the container, which lets you process the logs with a Kubernetes cluster-level log collector. + + If you choose this approach, we suggest configuring the audit device with a `prefix`, so your log collector can separate audit logs from server logs. + + + + + + + +To configure a `syslog` audit device, you must deploy Vault on Unix, and you must use the default syslog service running on the same host as the Vault server. If you enable a `syslog` audit device, use a TCP listener so that Vault can record large audit log entries that may exceed the size limit of UDP listeners. + + + + + +If you configure a `socket` audit device, configure a local service to bind a Unix socket. + +Socket devices using TCP and UDP listeners can result in lost audit log data if the TCP connection is interrupted or the receiving UDP endpoint becomes unavailable. Using a local socket helps protect against data loss. + + + + + +## Configure audit devices + +Review the configuration options that are specific to the type of audit device, as well as those [common](/vault/api-docs/system/audit#parameters) to all audit device types, and ensure that you configure all audit devices in a way that is appropriate for your organization and deployment. + +In general, we recommend the following options for all audit devices: + +- Set `elide_list_responses = true` to reduce the volume of log data produced by API list requests (see [Eliding list response bodies](/vault/docs/audit#eliding-list-response-bodies)). +- Set `hmac_accessor = false`. A token accessor is generally not considered sensitive information: it does not grant any access to Vault, but rather serves as a unique identifier for a single Vault token. A token accessor enables you to [revoke](/vault/docs/commands/token/revoke) its corresponding Vault token, even when you do not know the token itself. By disabling token accessor hashing, if you identify unusual access patterns in your audit logs, you can quickly revoke the corresponding Vault token through its accessor. + +## Monitor audit device health + +Configure monitoring and alerting on the health of your audit devices through Vault telemetry and device-specific monitoring (such as available disk space, disk IOPS, and log rotation status for `file` type audit devices). + +Vault produces several audit logging [telemetry metrics](/vault/docs/internals/telemetry/metrics/audit). We especially recommend monitoring the following metrics for spikes, which can indicate one or more audit devices failing: + +- [`vault.audit.log_request_failure`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-log_request_failure) +- [`vault.audit.log_response_failure`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-log_response_failure) +- [`vault.audit.{DEVICE}.log_request`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-device-log_request) +- [`vault.audit.{DEVICE}.log_response`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-device-log_response) + +## Configure attribute hashing + +Evaluate which request and response attributes need *not* be [hashed](/vault/docs/audit#hashing-sensitive-values) in the audit logs for each authentication backend and secrets engine mount you configure in Vault. Leave hashing enabled for attributes that are sensitive (e.g., passwords, private keys) or that may be excessively large for your audit log. + +You can disable hashing for individual request and response attributes with the `audit_non_hmac_request_keys` and `audit_non_hmac_response_keys` attributes in the following tuning endpoints: + +- [`/sys/auth/{path}/tune`](/vault/api-docs/system/auth#tune-auth-method) +- [`/sys/mounts/{path}/tune`](/vault/api-docs/system/mounts#tune-mount-configuration) + +## Monitor suspicious activity + +Configure monitoring and alerting for unusual or suspicious activity in your audit logs. Examples of events to monitor include: + +- Root token creation +- Root token usage +- Modifications to audit logging configuration +- Spikes in authentication failures +- Spikes in permission denied failures diff --git a/content/vault/v1.21.x (rc)/content/docs/audit/index.mdx b/content/vault/v1.21.x (rc)/content/docs/audit/index.mdx index a3abf8ffd7..85cc1c4716 100644 --- a/content/vault/v1.21.x (rc)/content/docs/audit/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/audit/index.mdx @@ -4,228 +4,146 @@ page_title: Audit Devices description: Audit devices are mountable devices that log requests and responses in Vault. --- -# Audit devices +# Audit logging -Audit devices are the components in Vault that collectively keep a detailed log of all -requests to Vault, and their responses. Because every operation with Vault is an API -request/response, when using a single audit device, the audit log contains _every_ interaction with -the Vault API, including errors - except for a few paths which do not go via the audit system. +With a small set of [exceptions](#excepted-api-endpoints), Vault audit devices record all API requests and responses in detail. An audit device can be a [file](/vault/docs/audit/file), a [syslog server](/vault/docs/audit/syslog), or a [socket](/vault/docs/audit/socket). -The non-audited paths are: +Refer to the [best practices](/vault/docs/audit/best-practices) page for important considerations before you configure your audit devices. - sys/init - sys/seal-status - sys/seal - sys/step-down - sys/unseal - sys/leader - sys/health - sys/rekey/init - sys/rekey/update - sys/rekey/verify - sys/rekey-recovery-key/init - sys/rekey-recovery-key/update - sys/rekey-recovery-key/verify - sys/storage/raft/bootstrap - sys/storage/raft/join - sys/internal/ui/feature-flags +Audit logs differ from server logs (also known as operational logs). Server logs emit information about the Vault server process, such as process errors and configuration warnings. Audit logs record the details of every request received and response sent by the Vault API. Refer to the [Troubleshoot Vault](/vault/tutorials/monitoring/troubleshooting-vault#vault-server-logs) tutorial for more information about server logs. -and also, if the relevant listener configuration settings allow unauthenticated access: +## Enabling and disabling audit devices ((#enabling-disabling-audit-devices)) - sys/metrics - sys/pprof/* - sys/in-flight-req +When you initialize a new Vault cluster, auditing is disabled. You must enable audit devices with the [Vault API](/vault/api-docs/system/audit#enable-audit-device), [Vault CLI](/vault/docs/commands/audit/enable), or tools like the [Terraform Vault provider](/vault/docs/configuration/programmatic-management). -## Enabling multiple devices +You can set [common](/vault/api-docs/system/audit#common-configuration-options) and type-specific options when you enable a new audit device. -When multiple audit devices are enabled, Vault will attempt to send the audit -logs to all of them. This allows you to not only have redundant copies, but also -a way to check for data tampering in the logs themselves. - -Vault considers a request to be successful if it can log to *at least* one -configured audit device (see: [Blocked Audit -Devices](/vault/docs/audit#blocked-audit-devices) section below). Therefore in order -to build a complete picture of all audited actions, use the aggregate/union of -the logs from each audit device. - -~> Note: It is **highly recommended** that you configure Vault to use multiple audit -devices. Audit failures can prevent Vault from servicing requests, so it is -important to provide at least one other device. +For example, the following command enables a `file` type audit device using a type-specific option to write to the file at `/var/log/vault_audit.log` and two common options to disable [elide list responses](#eliding-list-response-bodies) and [hashing](#hashing-sensitive-values) for token accessors. +```shell-session +$ vault audit enable file \ + file_path=/var/log/vault_audit.log \ + hmac_accessor=false \ + elide_list_responses=true +``` -## Format +Vault replicates audit device configurations to all nodes within a cluster. Vault Enterprise also replicates audit device configurations to performance secondary and disaster recovery secondary clusters unless you configure the audit device as [`local`](/vault/api-docs/system/audit#local) to the cluster. Before you enable an audit device, ensure that all Vault nodes to which the audit device configuration replicates can successfully log to that audit device. -Each line in the audit log is a JSON object. The `type` field specifies what -type of object it is. Currently, only two types exist: `request` and `response`. -The line contains all of the information for any given request and response. By -default, all the sensitive information is first hashed before logging in the -audit logs. +When you disable an audit device, Vault immediately stops writing information to the device, but leaves the existing log information untouched. -## Sensitive information +Once you disable an audit device, you can no longer [compute hashes](#hashing-sensitive-values) for the associated audit log entries. Even if you re-enable the audit device at the same path, Vault creates a new hashing key for the new log entries. -The audit logs contain the full request and response objects for every -interaction with Vault. The request and response can be matched utilizing a -unique identifier assigned to each request. + -Most strings contained within requests and responses are hashed with a salt using HMAC-SHA256. -The purpose of the hash is so that secrets aren't in plaintext within your audit logs. -However, you're still able to check the value of secrets by generating HMACs yourself; -this can be done with the audit device's hash function and salt by using the `/sys/audit-hash` -API endpoint (see the documentation for more details). +## Availability of audit devices ((#enabling-multiple-devices)) -~> Currently, only strings that come from JSON or returned in JSON are -HMAC'd. Other data types, like integers, booleans, and so on, are passed -through in plaintext. We recommend that all sensitive data be provided as string values -inside all JSON sent to Vault (i.e., that integer values are provided in quotes). +Vault sends the audit log entry of every API request and response to all enabled audit devices and guarantees that it saves to at least one of the enabled devices. As a result, if you have audit devices enabled and Vault cannot log information to at least one of the enabled devices, Vault refuses to service the corresponding API request. -While most strings are hashed, Vault can be configured to make some exceptions. -For example in auth methods and secrets engines, users can enable additional exceptions -using the [secrets enable](/vault/docs/commands/secrets/enable) command, and then -[tune](/vault/docs/commands/secrets/tune) it afterward. +When all enabled audit devices become unavailable, Vault in effect becomes unavailable as well. To prevent audit-related unavailability of Vault, HashiCorp recommends that you: -**see also**: +- Enable at least two audit devices. +- Analyze the combined audit log entries across all enabled audit devices to ensure a complete record of every API request and response. -[auth enable](/vault/docs/commands/auth/enable) +Refer to the [best practices](/vault/docs/audit/best-practices) page for additional information. -[auth tune](/vault/docs/commands/auth/tune) +## Hashing sensitive values ((#sensitive-information)) -## Audit request headers +By default, Vault only writes a keyed hash (HMAC-SHA256) of most string values to audit logs to protect the confidentiality of potentially sensitive information. -Use the [Vault API](/vault/api-docs/system/config-auditing) to configure request -headers to monitor and audit headers in incoming client request. +Vault does not hash non-string values, such as integers and booleans. We recommend sending all sensitive data to Vault as string values. For example, encapsulate sensitive integer values in quotes in JSON files: -By default, Vault **does not** encrypt request header values with HMAC if you -[create](/vault/api-docs/system/config-auditing#create-update-audit-request-header) -an exception to allow request headers in the audit log. To encrypt the header -values, you must [configure](/vault/api-docs/system/config-auditing#hmac) the -relevant headers individually. +```json +{ + "name": "sidon", + "age": "12" +} +``` -### Default headers +To calculate the keyed hash of any known value for a given audit device, use the [`/sys/audit-hash`](/vault/api-docs/system/audit-hash) API endpoint. +Alternatively, you can selectively exempt specific request or response attributes from hashing for each [authentication backend](/vault/docs/commands/auth/tune) and [secrets engine](/vault/docs/commands/secrets/tune) you enable. -To help correlate requests across distributed systems, Vault automatically -records the following headers in the audit log: +## Eliding list response bodies -- `correlation-id` -- `x-correlation-id` +Some Vault responses can be very large, especially with `LIST` requests. For example, listing all active leases could return a list that is tens of megabytes long. +Some audit backends cannot process individual audit records of larger sizes. To avoid overloading your audit devices, you can use the [`elide_list_responses`](/vault/api-docs/system/audit#elide_list_responses) option to replace `keys` and `key_info` values in audit log entries for `LIST` responses with the number of objects those fields contain. -To ensure Vault uses HMAC on the header values during logging, set the `hmac` value to true for the `config/auditing/request-headers` API call. +Using `elide_list_responses` [`elide_list_responses`](/vault/api-docs/system/audit#elide_list_responses) improves compatibility with audit devices and reduces the amount of audit data that audit devices ingest, store, and process, while retaining some level of information about what was returned to the client. -For example, to enable HMAC for `correlation-id` +For example, the following partial audit record shows an elided list where the `keys` field returns `4`, instead of the actual list of keys, which would have been `["a", "b", "c", "d"]`: -```shell -curl \ - --header "X-Vault-Token: ..." \ - http://127.0.0.1:8200/v1/sys/config/auditing/request-headers/correlation-id \ - --data '{ "hmac": true }' +```json +{ + "type": "response", + "request": { + "operation": "list" + }, + "response": { + "data": { + "keys": 4 + } + } +} ``` -Another way to identify the source of a request is through the User-Agent request header. -Vault will automatically record this value as `user-agent` within the `headers` of a -request entry within the audit log. - - -## Enabling/Disabling audit devices +## Logging request headers ((#audit-request-headers)) -When a Vault server is first initialized, no auditing is enabled. Audit -devices must be enabled by a root user using `vault audit enable`. +You can use the [`/sys/config/auditing`](/vault/api-docs/system/config-auditing#create-update-audit-request-header) endpoint to configure which incoming client request headers you want Vault to record in the corresponding audit log entries. -When enabling an audit device, options can be passed to it to configure it. -For example, the command below enables the file audit device: +By default, Vault records the following request headers: -```shell-session -$ vault audit enable file file_path=/var/log/vault_audit.log -``` - -In the command above, we passed the "file_path" parameter to specify the path -where the audit log will be written to. Each audit device has its own -set of parameters. See the documentation to the left for more details. +- `User-Agent` +- `Correlation-Id` +- `X-Correlation-Id` -~> Note: Audit device configuration is replicated to all nodes within a -cluster by default, and to performance/DR secondaries for Vault Enterprise clusters. -Before enabling an audit device, ensure that all nodes within the cluster(s) -will be able to successfully log to the audit device to avoid Vault being -blocked from serving requests. -An audit device can be limited to only within the node's cluster with the [`local`](/vault/api-docs/system/audit#local) parameter. +Vault does not hash request header values by default. You can [configure](/vault/api-docs/system/config-auditing#hmac) Vault to apply the [keyed hash](#hashing-sensitive-values) to any request header value you consider sensitive. -When an audit device is disabled, it will stop receiving logs immediately. -The existing logs that it did store are untouched. +## Exempted API endpoints -~> Note: Once an audit device is disabled, you will no longer be able to HMAC values -for comparison with entries in the audit logs. This is true even if you re-enable -the audit device at the same path, as a new salt will be created for hashing. +Vault does not audit requests and responses for the following API endpoints: -## Blocked audit devices - -Audit device logs are critically important and ignoring auditing failures opens an avenue for attack. Vault will not respond to requests when no enabled audit devices can record them. - -Vault can distinguish between two types of audit device failures. +``` +sys/init +sys/seal-status +sys/seal +sys/step-down +sys/unseal +sys/leader +sys/health +sys/rekey/init +sys/rekey/update +sys/rekey/verify +sys/rekey-recovery-key/init +sys/rekey-recovery-key/update +sys/rekey-recovery-key/verify +sys/storage/raft/bootstrap +sys/storage/raft/join +sys/internal/ui/feature-flags +``` -- A blocking failure is one where an attempt to write to the audit device never completes. This is unlikely with a local disk device, but could occure with a network-based audit device. +Additionally, Vault does not audit requests to the following endpoints when the associated listener configuration allows unauthenticated access: -- When multiple audit devices are enabled, if any of them fail in a non-blocking fashion, Vault requests can still complete successfully provided at least one audit device successfully writes the audit record. If any of the audit devices fail in a blocking fashion however, Vault requests will hang until the blocking is resolved. +``` +sys/metrics +sys/pprof/* +sys/in-flight-req +``` -In other words, Vault will not complete any requests until the blocked audit device can write. +## Additional resources -## Tutorial + -Refer to [Blocked Audit Devices](/vault/tutorials/monitoring/blocked-audit-devices) for a step-by-step tutorial. + -## API + - [Recover blocked audit devices](/vault/tutorials/monitoring/blocked-audit-devices) -Audit devices also have a full HTTP API. Please see the [Audit device API -docs](/vault/api-docs/system/audit) for more details. + -## Common configuration options + -@include 'audit-options-common.mdx' + - [Audit API](/vault/api-docs/system/audit) -## Eliding list response bodies + -Some Vault responses can be very large. Primarily, this affects list operations - -as Vault lacks pagination in its APIs, listing a very large collection can result -in a response that is tens of megabytes long. Some audit backends are unable to -process individual audit records of larger sizes. - -The contents of the response for a list operation is often not very interesting; -most contain only a "keys" field, containing a list of IDs. Select API endpoints -additionally return a "key_info" field, a map from ID to some additional -information about the list entry - `identity/entity/id/` is an example of this. -Even in this case, the response to a list operation is usually less-confidential -or public information, for which having the full response in the audit logs is of -lesser importance. - -The `elide_list_responses` audit option provides the flexibility to not write the -full list response data from the audit log, to mitigate the creation of very long -individual audit records. - -When enabled, it affects only audit records of `type=response` and -`request.operation=list`. The values of `response.data.keys` and -`response.data.key_info` will be replaced with a simple integer, recording how -many entries were contained in the list (`keys`) or map (`key_info`) - therefore -even with this feature enabled, it is still possible to see how many items were -returned by a list operation. - -This extra processing only affects the response data fields `keys` and `key_info`, -and only when they have the expected data types - in the event a list response -contains data outside of the usual conventions that apply to Vault list responses, -it will be left as is by this feature. - -Here is an example of an audit record that has been processed by this feature -(formatted with extra whitespace, and with fields not relevant to the example -omitted): -```json -{ - "type": "response", - "request": { - "operation": "list" - }, - "response": { - "data": { - "key_info": 4, - "keys": 4 - } - } -} -``` + diff --git a/content/vault/v1.21.x (rc)/content/docs/audit/schema.mdx b/content/vault/v1.21.x (rc)/content/docs/audit/schema.mdx new file mode 100644 index 0000000000..4d9389c2f2 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/audit/schema.mdx @@ -0,0 +1,376 @@ +--- +layout: docs +page_title: Audit log entry schema +description: Schema reference for Vault audit log entries. +--- + +# Audit log entry schema + +Vault logs audit entries as individual JSON objects separated by line breaks. Audit log entries include attributes that are common across all API endpoints and endpoint-specific request and response attributes. + +Audit log entries represent API requests received by Vault and API response sent by Vault. You can match response entries to the corresponding request entry with the ID field of the `request` object (`.request.id`) included in both entries. + +Attribute | Type | Description +---------------- | -------- | ----------- +`auth` | `object` | [`authentication`](#authentication-object) object describing the authenticated principal making the API call. +`error` | `string` | Error string generated by the request or returned in the response. Omitted for successful transactions. +`forwarded_from` | `string` | Host and port of the performance standby node forwarding the request. Omitted for requests not forwarded. +`request` | `object` | [`request`](#request-object) object describing the request details. +`response` | `object` | [`response`](#response-object) object describing response details. Omitted for request entries. +`time` | `string` | Date and time of the API request/response in ISO 8601 format. +`type` | `string` | Type of the audit log entry. One of `request` or `response`. + + + + + +```json +{ + "auth": , + "error": "error converting input {\"name\":\"John\"} for field \"data\": '' expected a map, got 'string'", + "forwarded_from": "vault-1.prod.corp.com:443", + "request": , + "time": "2025-06-05T16:10:22.292517Z", + "type": "request" +} +``` + + + + + +```json +{ + "auth": , + "error": "1 error occurred:\n\t* invalid request\n\n", + "forwarded_from": "vault-1.prod.corp.com:443", + "request": , + "response": , + "time": "2025-06-05T16:10:22.292639Z", + "type": "response" +} +``` + + + + + +## Authentication object + +Vault omits irrelevant `authentication` object attributes from the audit entry. For example, `accessor` and `client_token` are irrelevant for unauthenticated requests and `metadata` is irrelevant if the authentication token lacks metadata. + +| Attribute | Type | Description | +| :---- | :---- | :---- | +| `accessor` | `string` | Accessor of the Vault token that performed the request. This value is hashed by default; the example shows a *non-hashed* token accessor. Refer to [token accessors](/vault/docs/concepts/tokens#token-accessors) for more information. | +| `client_token` | `string` | Vault token that performed the request, in hashed form. | +| `display_name` | `string` | Name associated with the Vault token that performed the request. This is a non-sensitive value that can help identify tokens. If a display name is not set, `"token"` will be shown. | +| `token_type` | `string` | Whether the Vault token is a `service`, `batch`, or `periodic` token. Refer to [token types](/vault/docs/concepts/tokens#token-types). | +| `token_issue_time` | `string` | Date and time when the Vault token was issued, in ISO 8601 format. | +| `token_ttl` | `integer` | Validity period of the Vault token, in seconds and as of when the token was first issued, relative to `token_issue_time`. Note that this value is not updated when the token's lifetime is changed subsequent to initial issuance. | +| `metadata` | `object` | Metadata associated with the Vault token. | +| `num_uses` | `integer` | When the API request results in a token being issued, which token has a limited number of uses, the number of uses on that token. | +| `remaining_uses` | `integer` | If the Vault token has a limit on the number of uses, the number of uses remaining *prior to the current request*. | +| `entity_created` | `boolean` | Whether the request resulted in an entity being created, i.e. an authorized principal logs into Vault for the first time. Omitted when false. | +| `entity_id` | `string` | If the Vault token is associated with an entity, the ID of that entity. | +| `policies` | `list(string)` | List of the names of the ACL policies associated with either the Vault token or the corresponding entity. | +| `identity_policies` | `list(string)` | If the Vault token is associated with an entity, a list of the names of the ACL policies associated (directly or via group membership) with that entity. | +| `token_policies` | `list(string)` | A list of the names of the ACL policies associated directly with the Vault token. | +| `no_default_policy` | `boolean` | Whether the Vault token does **not** have Vault's "default" ACL policy associated with it. Omitted when false. | +| `external_namespace_ policies` | `object` | If the Vault token is associated with an entity, and that entity inherits ACL policies from a namespace other than the namespace in which the entity exists, a JSON object containing a boolean attribute `allowed` and `granting_policies`, a list of those inherited ACL policies. Refer to the JSON structure below for more information about `granting_policies`. | +| `policy_results` | `object` | JSON object containing a boolean attribute `allowed` and `granting_policies`, a list of ACL policies associated with either the Vault token or the corresponding entity that resulted in the request being allowed. Refer to the JSON structure below for more information about `granting_policies`. | + +```json +{ + "accessor": "", + "client_token": "", + "display_name": "", + "entity_created": "", + "entity_id": "", + "external_namespace_policies": { + "allowed": true, + "granting_policies": [ + { + "name": "", + "namespace_id": "", + "namespace_path": "", + "type": "" + } + ] + }, + "identity_policies": [""], + "metadata": {}, + "no_default_policy": false, + "num_uses": 10, + "policies": [""], + "policy_results": { + "allowed": true, + "granting_policies": [ + { + "name": "", + "namespace_id": "", + "namespace_path": "", + "type": "" + } + ] + }, + "remaining_uses": 5, + "token_policies": [""], + "token_issue_time": "", + "token_ttl": 3600, + "token_type": "" +} +``` + +## Request object ((#request)) + +The following request object definition includes example data with simple types (`string`, `bool`, `int`) and used in other JSON examples that include a `` object. + +| Attribute | Type | Description | +| :---- | :---- | :---- | +| `id` | `string` | Random ID generated by Vault to uniquely identify the API request. | +| `operation` | `string` | Whether the request is a `create`, `read`, `update`, `delete`, or `list` operation. | +| `namespace` | `object` | JSON object with the namespace's unique `id` and its `path`. | +| `path` | `string` | API path that received the request. | +| `request_uri` | `string` | The original request path from the HTTP request, if it differs from `path` (e.g., when the Vault namespace is specified as an HTTP header). | +| `mount_accessor` | `string` | Unique identifier of the Vault mount (secret engine or authentication backend) that received the API request. | +| `mount_type` | `string` | Type of Vault mount that received the API request. | +| `mount_running_version` | `string` | Version string for the Vault mount that received the API request. | +| `mount_running_sha256` | `string` | If the mount that received the API request is an external plugin, the SHA-256 hash of the plugin's running version. | +| `mount_is_external_ plugin` | `boolean` | Whether the mount that received the API request is an external plugin. | +| `remote_address` | `string` | IP address of the client making the request, as seen by Vault. Note that load balancers, proxies, and reverse proxies may all mask the true client's IP address. | +| `remote_port` | `integer` | Port number used by the client making the request, as seen by Vault. | +| `headers` | `object` | JSON object containing request headers [configured](/vault/docs/audit#logging-of-request-headers) to be logged. | +| `policy_override` | `boolean` | Whether the client requested an override of a [Sentinel policy](/vault/docs/enterprise/sentinel). | +| `client_id` | `string` | ID of the Vault [client](https://developer.hashicorp.com/vault/docs/concepts/client-count) making the request. | +| `client_token` | `string` | Vault token that performed the request, in hashed form. | +| `client_token_accessor` | `string` | Accessor of the Vault token that performed the request. This value is hashed by default; the example shows a *non-hashed* token accessor. Refer to [token accessors](/vault/docs/concepts/tokens#token-accessors) for more information. | +| `client_certificate_ serial_number` | `string` | If the client's connection to Vault is mutually authenticated, the serial number of the client's TLS certificate. | +| `wrap_ttl` | `integer` | If the client requested the response to be [wrapped](/vault/docs/concepts/response-wrapping), the number of seconds for which the wrapped response will be available. | +| `data` | `object` | JSON object containing the request's payload. This is dependent on the API endpoint called. | +| `replication_cluster` | `string` | If the request was forwarded from a Performance Replication secondary cluster, the name of the secondary cluster. | + +```json +{ + "client_certificate_serial_number": "", + "client_id": "", + "client_token": "", + "client_token_accessor": "", + "data": {}, + "id": "", + "headers": {}, + "mount_accessor": "", + "mount_class": "", + "mount_point": "", + "mount_type": "", + "mount_running_version": "", + "mount_running_sha256": "", + "mount_is_external_plugin": "", + "namespace": { + "id": "", + "path": "" + }, + "operation": "", + "path": "", + "policy_override": true, + "remote_address": "", + "remote_port": 1234, + "replication_cluster": "", + "request_uri": "", + "wrap_ttl": 60 +} +``` + +## Response object ((#response)) + +The following response object definition includes example data with simple types (`string`, `bool`, `int`) and used in other JSON examples that include a `` object. + +| Attribute | Type | Description | +| :---- | :---- | :---- | +| `auth` | `object` | If the request results in a token being created, an `authentication` object with the token information. See [`authentication`](#authentication-object) above. | +| `headers` | `object` | Set of HTTP response headers sent by the plugin that handled the API request. | +| `redirect` | `string` | For requests sent to authentication backends, the URL to which the authentication backend redirected the user for further authentication. | +| `warnings` | `list(string)` | If the API returned one or more warnings, a list of the warning messages. | +| `data` | `object` | JSON object containing the response payload. This is dependent on the API endpoint called. | +| `secret` | `object` | If the API returned a [leased secret](/vault/docs/concepts/lease), a JSON object with one attribute, `lease_id`, that identifies that leased secret. | +| `wrap_info` | `object` | If the API returned a [response-wrapped secret](/vault/docs/concepts/response-wrapping), a JSON object containing the properties of the wrapping token. See below for the attributes in the JSON object. | +| `mount_class` | `string` | Type of API mount, `auth` or `secret`. | +| `mount_accessor` | `string` | Unique identifier of the Vault mount (secret engine or authentication backend) that responded to the API request. | +| `mount_type` | `string` | Type of Vault mount that responded to the API request. | +| `mount_running_plugin_version` | `string` | Version string for the Vault mount that responded to the API request. | +| `mount_running_sha256` | `string` | If the mount that received the API request is an external plugin, the SHA-256 hash of the plugin's running version. | +| `mount_is_external_plugin` | `boolean` | Whether the mount that received the API request is an external plugin. | + +```json +{ + "auth": , + "data": {}, + "headers": {}, + "mount_accessor": "", + "mount_class": "", + "mount_is_external_plugin": false, + "mount_point": "", + "mount_running_sha256": "", + "mount_running_plugin_version": "", + "mount_type": "", + "redirect": "", + "secret": { + "lease_id": "" + }, + "wrap_info": { + "accessor": "", + "creation_path": "", + "creation_time": "", + "token": "", + "ttl": 60, + "wrapped_accessor": "" + }, + "warnings": [ + "" + ] +} +``` + +## JSON schemas + +
+Request audit entries + +@include 'audit/request-entry-json-schema.mdx' + +
+ +
+Response audit entries + +@include 'audit/response-entry-json-schema.mdx' + +
+ +## Full entry examples + + + + + +```json +{ + "auth": { + "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "client_token": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d", + "display_name": "userpass-alice", + "entity_id": "62ff123b-7609-1ed9-5707-ea621da72de7", + "metadata": { "username": "alice" }, + "policies": ["default"], + "policy_results": { + "allowed": true, + "granting_policies": [ + { "type": "" }, + { "name": "default", "namespace_id": "root", "type": "acl" } + ] + }, + "token_policies": ["default"], + "token_issue_time": "2025-06-04T16:01:31-04:00", + "token_ttl": 2764800, + "token_type": "service" + }, + "request": { + "client_id": "62ff123b-7609-1ed9-5707-ea621da72de7", + "client_token": "hmac-sha256:3431e8c2ce0e5f5e179a857fcf9d948afd83363de9f64a5e956851262e1285e0", + "client_token_accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "headers": { "user-agent": ["Go-http-client/1.1"] }, + "id": "79cc9b26-488f-eabf-2a97-303ed3bef0d6", + "mount_class": "auth", + "mount_point": "auth/token/", + "mount_running_version": "v1.19.1+builtin.vault", + "mount_type": "token", + "namespace": { "id": "root" }, + "operation": "read", + "path": "auth/token/lookup-self", + "remote_address": "127.0.0.1", + "remote_port": 64199 + }, + "time": "2025-06-04T20:02:46.117181Z", + "type": "request" +} +``` + + + + + +```json +{ + "auth": { + "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "client_token": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d", + "display_name": "userpass-alice", + "entity_id": "62ff123b-7609-1ed9-5707-ea621da72de7", + "metadata": { "username": "alice" }, + "policies": ["default"], + "policy_results": { + "allowed": true, + "granting_policies": [ + { "type": "" }, + { "name": "default", "namespace_id": "root", "type": "acl" } + ] + }, + "token_policies": ["default"], + "token_issue_time": "2025-06-04T16:01:31-04:00", + "token_ttl": 2764800, + "token_type": "service" + }, + "request": { + "client_id": "62ff123b-7609-1ed9-5707-ea621da72de7", + "client_token": "hmac-sha256:3431e8c2ce0e5f5e179a857fcf9d948afd83363de9f64a5e956851262e1285e0", + "client_token_accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "headers": { "user-agent": ["Go-http-client/1.1"] }, + "id": "79cc9b26-488f-eabf-2a97-303ed3bef0d6", + "mount_accessor": "auth_token_d43d387d", + "mount_class": "auth", + "mount_point": "auth/token/", + "mount_running_version": "v1.19.1+builtin.vault", + "mount_type": "token", + "namespace": { "id": "root" }, + "operation": "read", + "path": "auth/token/lookup-self", + "remote_address": "127.0.0.1", + "remote_port": 64199 + }, + "response": { + "data": { + "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "creation_time": 1749067291, + "creation_ttl": 2764800, + "display_name": "hmac-sha256:e9fb3affb6ae22b7f747e1a60bdda5b57809c9e64ae6f39ebac24e371e6b9d89", + "entity_id": "hmac-sha256:d2458e3011b3567a0070f22bcdd5e513aeb3473457922e1866f01463ccce2b11", + "expire_time": "2025-07-06T16:01:31.771304-04:00", + "explicit_max_ttl": 0, + "id": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d", + "issue_time": "2025-06-04T16:01:31.771306-04:00", + "meta": { + "username": "hmac-sha256:b93081f3689ff25929e88d5c323631ccf7d6145cd9f33c0c5129a7a340248b9a" + }, + "num_uses": 0, + "orphan": true, + "path": "hmac-sha256:82f79af6be9e1d33d6821a8cfcfcba3196e5ec68512c1f5ed4c919acd8443dd6", + "policies": [ + "hmac-sha256:1b1a37ccd3a6a78da781140396f04eb50e3460504492d2da75b446d775d3325b" + ], + "renewable": true, + "ttl": 2764725, + "type": "hmac-sha256:b835fe7ff7616f2023c77f6dbddc7afd83ef5c6644aba61c574c378dda710809" + }, + "mount_accessor": "auth_token_d43d387d", + "mount_class": "auth", + "mount_point": "auth/token/", + "mount_running_plugin_version": "v1.19.1+builtin.vault", + "mount_type": "token" + }, + "time": "2025-06-04T20:02:46.117567Z", + "type": "response" +} +``` + + + + diff --git a/content/vault/v1.21.x (rc)/content/docs/auth/approle/approle-pattern.mdx b/content/vault/v1.21.x (rc)/content/docs/auth/approle/approle-pattern.mdx index 47d6887d19..dd2ef6f2ef 100644 --- a/content/vault/v1.21.x (rc)/content/docs/auth/approle/approle-pattern.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/auth/approle/approle-pattern.mdx @@ -301,7 +301,7 @@ In any trusted broker situation, the broker (in this case, the Jenkins worker) m Also, as the Vault audit logs provide time-stamped events, monitor the whole process with alerts on two events: - When a wrapped SecretID is requested for an AppRole, and no Jenkins job is running -- When the Jenkins slave attempts to unwrap the token and Vault refuses as the token has already been used +- When the Jenkins agent attempts to unwrap the token and Vault refuses as the token has already been used In both cases, this shows that the trusted-broker workflow has likely been compromised and the event should investigated. @@ -311,3 +311,4 @@ In both cases, this shows that the trusted-broker workflow has likely been compr - [Response wrapping concept](/vault/docs/concepts/response-wrapping) - [ACL policies](/vault/docs/concepts/policies) - [Token periods and TTLs](/vault/docs/concepts/tokens#token-time-to-live-periodic-tokens-and-explicit-max-ttls) +- [Vault Secrets Operator CSI driver](/vault/docs/platform/k8s/vso/csi) for providing response-wrapped secret IDs to Kubernetes pods \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/docs/auth/gcp.mdx b/content/vault/v1.21.x (rc)/content/docs/auth/gcp.mdx index 70acc2dfe1..e2ea79387d 100644 --- a/content/vault/v1.21.x (rc)/content/docs/auth/gcp.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/auth/gcp.mdx @@ -296,7 +296,7 @@ if you need to limit Vault API exposure. 1. [Authenticate a workload](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#authenticate) in GCP by granting the identity pool access to a dedicated service account using service account impersonation. Filter requests using the unique `sub` claim issued by plugin identity tokens so the GCP Auth method can -impersonate the service account. `sub` claims have the form: `plugin-identity::auth:`. +impersonate the service account. `sub` claims have the form: `plugin-identity::auth:`. 1. Configure the GCP auth method with the OIDC audience value and service account email. diff --git a/content/vault/v1.21.x (rc)/content/docs/auth/ldap.mdx b/content/vault/v1.21.x (rc)/content/docs/auth/ldap.mdx index f9f5707733..4607aebfcc 100644 --- a/content/vault/v1.21.x (rc)/content/docs/auth/ldap.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/auth/ldap.mdx @@ -196,10 +196,14 @@ Use `vault path-help` for more details. The root bindpass can be rotated to a Vault-generated value that is not accessible by the operator. This will ensure that only Vault is able to access the "root" user that Vault uses to manipulate credentials. +Manual root rotations will be logged to the vault.log and state that the rotation was `on user request`. + ```shell-session -vault write -f auth/ldap/rotate-root +vault write -f auth/ldap/config/rotate-root ``` +Vault logs manual root rotations to `vault.log` with a note that the rotation was `on user request`. + ### Schedule-based root credential rotation @include 'alerts/enterprise-only.mdx' @@ -252,6 +256,8 @@ load-balancer. For more details on rotating root credentials in the LDAP plugin, refer to the [Root credential rotation](/vault/api-docs/auth/ldap#rotate-root) API docs. +@include 'rotation-manager-logging.mdx' + ## Examples scenarios ### Scenario 1 diff --git a/content/vault/v1.21.x (rc)/content/docs/configuration/index.mdx b/content/vault/v1.21.x (rc)/content/docs/configuration/index.mdx index cf243b6cf4..28e05d219d 100644 --- a/content/vault/v1.21.x (rc)/content/docs/configuration/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/configuration/index.mdx @@ -280,6 +280,9 @@ can have a negative effect on performance due to the tracking of each lock attem [os.TempDir()](https://pkg.go.dev/os#TempDir) (usually `/tmp` on Unix systems). This can be updated on a running Vault process with a SIGHUP signal. +- `allow_audit_log_prefixing` `(bool: false)` - Enable to allow prefixes on audit log entries for + [file sinks](/vault/docs/audit/file). + ### High availability parameters The following parameters are used on backends that support [high availability][high-availability]. diff --git a/content/vault/v1.21.x (rc)/content/docs/configuration/listener/tcp/index.mdx b/content/vault/v1.21.x (rc)/content/docs/configuration/listener/tcp/index.mdx index 2fe9fd3166..c85799cef0 100644 --- a/content/vault/v1.21.x (rc)/content/docs/configuration/listener/tcp/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/configuration/listener/tcp/index.mdx @@ -297,6 +297,42 @@ default value in the `"/sys/config/ui"` [API endpoint](/vault/api-docs/system/co - `disable_replication_status_endpoints` `(bool: false)` - Disables replication status endpoints for the configured listener when set to `true`. + The JSON parsing limits like `max_json_depth` and `max_json_token` have + intentionally permissive defaults to suport a wide range of use cases. The + primary constraints on parsing limits are available RAM and CPU. We recommend + tuning your JSON parsing limits down from the defaults to match your specific + application needs and available resourcess. Due to the way the parsing limits + interact, running with permissive defaults in a low-resource environment like + a lightweight container can increase the risk that a large, complex JSON + payload could exhaust the available resources. + +- `max_json_depth` `(int: 500)` – Specifies the maximum nesting depth of a JSON + payload. Limiting object depth mitigates the risk of stack exhaustion from + deeply nested objects, which could lead to a Denial of Service (DoS). + +- `max_json_string_value_length` `(int: 1048576)` – Defines the maximum allowed + length in bytes for a single string value within a JSON payload. Limiting + string length provides a critical defense against excessive memory allocation + attacks where a client might send a very large string to exhaust server memory. + Defaults to 1MB. + +- `max_json_object_entry_count` `(int: 10000)` – Sets the maximum number of + key-value pairs allowed in a single JSON object. Limiting the entry count on + JSON objects helps mitigate hash-collision Denial of Service (HashDoS) attacks + and prevents general resource exhaustion from objects with an excessive number + of entries. + +- `max_json_array_element_count` `(int: 10000)` – Determines the maximum number + of elements permitted in a single JSON array. Limiting the number of array + elements prevents a single request from causing excessive memory consumption + when processing large lists. + +- `max_json_token` `(int: 500000)` – Sets the maximum total number of tokens + (e.g., keys, values, braces, brackets) permitted in a single JSON payload. + Setting a limit on tokens acts as an overall complexity limit to provide a + safeguard against attacks that use a huge number of small elements to exhaust + CPU and memory. + ### `telemetry` parameters - `unauthenticated_metrics_access` `(bool: false)` - If set to true, allows diff --git a/content/vault/v1.21.x (rc)/content/docs/configuration/seal/index.mdx b/content/vault/v1.21.x (rc)/content/docs/configuration/seal/index.mdx index 877fc6b112..e6f6ca3513 100644 --- a/content/vault/v1.21.x (rc)/content/docs/configuration/seal/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/configuration/seal/index.mdx @@ -47,13 +47,16 @@ environment variable will take precedence over values in the configuration file. Some configuration options, considered sensitive, may use a special syntax in the value of the option that indicates the final value should be sourced -from the environment or a file. Two URL style forms are supported: +from the environment or a file. Three URL style forms are supported: * `env://name`: The final value will be the contents of the environment variable with key `name`. * `file://path`: The final value will be the contents of the file at `path`. Path may be absolute or relative, and if relative, is relative to the working directory of the Vault process. +* `string://data`: The final value will be everything after string:// + without further interpretation. This is useful if you needed a literal + string that was preceded by one of the above special prefixes. Note that indirect value references are not whitespace pruned, so in particular with the file method care to eliminate trailing newlines is diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/comparisons.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/comparisons.mdx new file mode 100644 index 0000000000..9bb6457bf5 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/comparisons.mdx @@ -0,0 +1,142 @@ +--- +layout: docs +page_title: Kubernetes integrations comparison +description: >- + Compare the available Kubernetes integrations for Vault, including Vault Secrets + Operator, Vault Secrets Store CSI provider, + and Vault Agent Injector. +--- + +# Kubernetes integrations comparison + +HashiCorp Vault provides three different integrations to help Kubernetes workloads consume secrets from Vault without modifying application code. Each integration has unique characteristics that make it suitable for different use cases. + +Use the information below to compare the available integrations and choose the right solution for your needs. + +## Features at a glance + +| Feature | Vault Secrets Operator | Vault Secrets Store CSI provider | Vault Agent Injector +| ----------------------------------- | ----------------------------------------------------------- | ------------------------------------------- | -------------- +| Supported secret types | Static/KV, PKI, Dynamic, Database, AppRole secret IDs | All | All +| Supported auth methods | K8s, AppRole, GCP, AWS, JWT | K8s, JWT | K8s, other [auto-auth methods](/vault/docs/agent-and-proxy/autoauth) +| Storage model | K8s Secrets (default)
Ephemeral volumes (CSI driver) | Temporary K8s Secrets or ephemeral volumes | Ephemeral volumes +| Kubernetes-native | Yes | Yes | No +| Secret data persistence | Persisted in `etcd` (default)
Ephemeral (CSI driver) | Temporarily persisted or ephemeral | Ephemeral +| Secret data templating | Yes | No | Yes +| Requires Vault for Pod autoscaling | No (default)
Yes (CSI driver) | Yes | Yes +| Secret sharing between applications | Yes | Yes | No + +## Vault Secrets Operator + +The [Vault Secrets Operator](/vault/docs/platform/k8s/vso) synchronizes secrets from Vault to native Kubernetes Secrets. +Vault Secrets Operator reconciles Custom Resource Definitions (CRDs) to sync secret data from Vault to Kubernetes Secrets that applications can consume using standard Kubernetes patterns. +Vault Enterprise users can also configure Vault Secrets Operator to run a [CSI driver](/vault/docs/platform/k8s/vso/csi) to bypass Kubernetes Secrets and mount secrets directly from Vault to application containers as volumes. + +**Best for:** Teams who prefer native Kubernetes workflows and want the option of writing secrets to persistent cluster storage or ephemeral volumes. + +## Vault Secrets Store CSI provider + +The [Vault Secrets Store CSI provider](/vault/docs/platform/k8s/csi) uses the vendor-neutral [Secrets Store CSI driver](https://secrets-store-csi-driver.sigs.k8s.io/) to mount secrets from Vault as ephemeral volumes. +You can deploy Vault Agent alongside the provider to manage [caching and renewals](/vault/docs/agent-and-proxy/agent/caching#caching-and-renewals). + +**Best for:** Organizations using multiple secret stores in addition to Vault, or those who prefer vendor-neutral CSI standards. + +## Vault Agent Injector + +The [Vault Agent Injector](/vault/docs/platform/k8s/injector) injects Vault Agent sidecar containers into Pods. +The Agent containers authenticate with Vault and render secrets to a shared memory volume for consumption by application containers. + +**Best for:** Applications that want to reference multiple Vault secrets in one template or need a wider array of auth methods. + + +## Use case recommendations + +The appropriate integration for your environment depends on the applicable +security policies, secret data governance, ease of use requirements, and +system availability guarantees. + +| Limitation | Vault Secrets Operator | Vault Secrets Store CSI provider　| Vault Agent Injector +| ------------------------------------------------- | --------------------------------- | ---------------------------- | -------------- +| Requires privileged Pod access | No, except with CSI driver | Yes | No +| Flexibility in how to consume secrets | Yes | Yes | No +| Low resource consumption (I/O, CPU, Memory) | Yes | Yes | No +| Secret data limited to ephemeral volumes | No | No | Yes +| Pod Autoscaling dependent on Vault availability | No, except with CSI driver | Yes | Yes +| Personas easily separated via K8s [RBAC] policies | Yes | No | No + +[RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac + + +## Performance considerations + +Performance characteristics vary significantly between integrations based on +their architectural patterns. + + + + + +- **Vault Secrets Operator** - Lowest load due to CRD-specific connections and cluster-local secret caching. +Single manager for an entire cluster. +- **Vault Secrets Operator with CSI driver** - Lower load due to one Vault connection pool per Node, with client caching. +- **Vault Secrets Store CSI provider** - Higher load due to per-Pod connections. +- **Vault Agent Injector** - Highest load due to per-Pod connections and sidecar pattern. + + + + + +- **Vault Secrets Operator** - Secret lifecycle is independent of Pod lifecycle due +to caching in Kubernetes Secrets, unless using the Vault Secrets Operator CSI driver. +- **Vault Secrets Store CSI provider** - Secret lifecycle depends on Pod lifecycle. +- **Vault Agent Injector** - Secret lifecycle depends on Pod lifecycle. + + + + + +- **Vault Secrets Operator** - Lowest consumption due to one client process needed per Kubernetes cluster. +Low to moderate consumption if using the CSI driver, due to one driver needed per Node. +- **Vault Secrets Store CSI provider** - Low to moderate consumption due to one client process needed per Node. +- **Vault Agent Injector** - Higher consumption despite tunable resource + allocation as each Pod requires a dedicated client process as a sidecar + container. + + + + + +Integrations that share secret data across Pods scale well as the number of Pods +increase. Integrations that create independent Vault connections for each Pod do +not scale well as the number of Pods increase. + +- **Vault Secrets Operator** - shares secret data. +- **Vault Secrets Store CSI provider** - creates independent Vault connections. +- **Vault Agent Injector** - creates independent Vault connections. + + + + + + +## Migrating to Vault Secrets Operator + +To migrate to Vault Secrets Operator from the other Kubernetes integrations: + +1. Create CRDs for each relevant secret type, such as `VaultStaticSecret`, `VaultDynamicSecret`, `VaultPKISecret`, or `CSISecrets`. Refer to the [API reference](/vault/docs/platform/k8s/vso/api-reference) for configuration details. +Note that the Vault Secrets Operator CSI driver only supports KV secrets and AppRole secret IDs. +1. Update your applications to use Kubernetes Secrets. +1. To migrate from Vault Agent Injector, you may need to update your secret + templates as the Golang templating in Vault Agent Injector may not work with + the Vault Secrets Operator `SecretTransformation` resource out of the box. +1. To use [protected secrets](/vault/docs/platform/k8s/vso/csi) you also need: + 1. A Vault Enterprise license. + 1. Updated Pod specifications that reference CSI volumes. + + +## Next steps + +For detailed implementation guidance, refer to the documentation for your chosen integration: +- [Vault Secrets Operator](/vault/docs/platform/k8s/vso) +- [Vault Secrets Store CSI provider](/vault/docs/platform/k8s/csi) +- [Vault Agent Injector](/vault/docs/platform/k8s/injector) diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/configurations.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/configurations.mdx index 9a9aaee9cc..d0a9edc57c 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/configurations.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/configurations.mdx @@ -1,13 +1,13 @@ --- layout: docs -page_title: Vault CSI provider configurations +page_title: Vault Secrets Store CSI provider configurations description: >- - Learn about the command line arguments and the secret provider class parameters supported by the Vault CSI provider. + Learn about the command line arguments and the secret provider class parameters supported by the Vault Secrets Store CSI provider. --- -# Vault CSI provider configurations +# Vault Secrets Store CSI provider configurations -The following command line arguments are supported by the Vault CSI provider. +The following command line arguments are supported by the Vault Secrets Store CSI provider. Most settings support being set by, in ascending order of precedence: - Environment variables @@ -37,9 +37,9 @@ If installing via the helm chart, they can be set using e.g. - `-vault-addr` `(string: "https://127.0.0.1:8200")` - Default address for connecting to Vault. Can also be specified via the `VAULT_ADDR` environment variable. **Note:** It is highly recommended to only set the Vault address when - installing the helm chart. The helm chart will install Vault Agent as a sidecar - to the Vault CSI Provider for caching and renewals, but setting `-vault-addr` - here will cause the Vault CSI Provider to bypass the Agent's cache. + installing the Helm chart. The Helm chart installs Vault Agent as a sidecar to the + Vault Secrets Store CSI provider for caching and renewals. + Setting `vaultAddress` here causes the Vault Secrets Store CSI provider to bypass the Vault Agent cache. - `-vault-mount` `(string: "kubernetes")` - Default Vault mount path for Kubernetes authentication. Can be overridden per Secret Provider Class @@ -88,9 +88,8 @@ structure is illustrated in the [examples](/vault/docs/platform/k8s/csi/examples - `vaultAddress` `(string: "")` - The address of the Vault server. **Note:** It is highly recommended to only set the Vault address when installing the helm chart. - The helm chart will install Vault Agent as a sidecar to the Vault CSI Provider - for caching and renewals, but setting `vaultAddress` here will cause the Vault - CSI Provider to bypass the Agent's cache. + The Helm chart installs Vault Agent as a sidecar to the Vault Secrets Store CSI provider + for caching and renewals. Setting `vaultAddress` here causes the Vault Secrets Store CSI provider to bypass the Vault Agent cache. - `vaultNamespace` `(string: "")` - The Vault [namespace](/vault/docs/enterprise/namespaces) to use. diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/examples.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/examples.mdx index ecb09b8b0e..bbdeab5a38 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/examples.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/examples.mdx @@ -1,14 +1,12 @@ --- layout: docs -page_title: Vault CSI provider examples -description: Examples of using the Vault CSI provider. +page_title: Vault Secrets Store CSI provider examples +description: Examples of using the Vault Secrets Store CSI provider. --- -# Vault CSI provider examples +# Vault Secrets Store CSI provider examples -The following examples demonstrate how the Vault CSI Provider can be used. - -~> A common mistake is to not install the CSI Secret Store Driver before using the Vault CSI Provider. +The following examples demonstrate common uses of the Vault Secrets Store CSI provider. ## File based dynamic database credentials diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/index.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/index.mdx index 259159ad39..c0a6b8da9c 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/index.mdx @@ -1,26 +1,25 @@ --- layout: docs -page_title: Vault CSI provider +page_title: Vault Secrets Store CSI provider description: >- - Learn how the Vault CSI provider allows pods to consume Vault secrets using CSI volumes. + Learn how to consume Vault secrets using CSI volumes with the Vault provider + for the Secrets Store CSI driver. --- -# Vault CSI provider +# Vault Secrets Store CSI provider -The Vault CSI Provider allows pods to consume Vault secrets using -[CSI Secrets Store](https://github.com/kubernetes-sigs/secrets-store-csi-driver) volumes. +The Vault Secrets Store CSI provider allows pods to consume Vault secrets using +[Secrets Store CSI](https://github.com/kubernetes-sigs/secrets-store-csi-driver) volumes. -The Vault CSI provider is a fully supported component of HashiCorp Vault. - -~> The Vault CSI Provider requires the [CSI Secret Store](https://github.com/kubernetes-sigs/secrets-store-csi-driver) +~> The Vault Secrets Store CSI provider requires the [CSI Secret Store](https://github.com/kubernetes-sigs/secrets-store-csi-driver) Driver to be installed. ## Overview -At a high level, the CSI Secrets Store driver allows users to create `SecretProviderClass` objects. +At a high level, the Secrets Store CSI driver lets you create `SecretProviderClass` objects. This object defines which secret provider to use and what secrets to retrieve. When pods requesting CSI volumes -are created, the CSI Secrets Store driver will send the request to the Vault CSI Provider if the provider -is `vault`. The Vault CSI Provider will then use Secret Provider Class specified and the pod's service account to retrieve +are created, the Secrets Store CSI driver sends the request to the Vault Secrets Store CSI provider if the provider +is `vault`. The Vault Secrets Store CSI provider then uses the specified `SecretProviderClass` and the service account of the pod to retrieve the secrets from Vault, and mount them into the pod's CSI volume. The secret is retrieved from Vault and populated to the CSI secrets store volume during the `ContainerCreation` phase. @@ -28,7 +27,7 @@ This means that pods will be blocked from starting until the secrets have been r ### Features -The following features are supported by the Vault CSI Provider: +Vault Secrets Store CSI provider supports the following features: - All Vault secret engines supported. - Authentication using the requesting pod's service account. @@ -52,7 +51,7 @@ The following features are supported by the Vault CSI Provider: ## Authenticating with Vault -The Vault CSI Provider will authenticate with Vault as the service account of the +The Vault Secrets Store CSI provider authenticates with Vault as the service account of the pod that mounts the CSI volume. [Kubernetes](/vault/docs/auth/kubernetes) and [JWT](/vault/docs/auth/jwt) auth methods are supported. The pod's service account must be bound to a Vault role and a policy granting access to the secrets desired. @@ -71,7 +70,7 @@ kind: SecretProviderClass metadata: name: vault-db-creds spec: - # Vault CSI Provider + # Vault Secrets Store CSI provider provider: vault parameters: # Vault role name to use during login @@ -138,5 +137,5 @@ the Secret Provider Class named `vault-db-creds`. ## Tutorial -Refer to the [Vault CSI Provider](/vault/tutorials/kubernetes/kubernetes-secret-store-driver) +Refer to the [Vault Secrets Store CSI provider](/vault/tutorials/kubernetes/kubernetes-secret-store-driver) tutorial to learn how to set up Vault and its dependencies with a Helm chart. diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/installation.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/installation.mdx index b4acd0b679..581f72c187 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/installation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/installation.mdx @@ -1,15 +1,15 @@ --- layout: docs -page_title: Install the Vault CSI provider -description: Install the Vault CSI provider using Vault Helm. +page_title: Install the Vault Secrets Store CSI provider +description: Install the Vault Secrets Store CSI provider using Vault Helm. --- -# Install the Vault CSI provider +# Install the Vault Secrets Store CSI provider ## Prerequisites - Kubernetes 1.16+ for both the master and worker nodes (Linux-only) -- [Secrets store CSI driver](https://secrets-store-csi-driver.sigs.k8s.io/getting-started/installation.html) installed +- [Secrets Store CSI driver](https://secrets-store-csi-driver.sigs.k8s.io/getting-started/installation.html) installed. - `TokenRequest` endpoint available, which requires setting the flags `--service-account-signing-key-file` and `--service-account-issuer` for `kube-apiserver`. Set by default from 1.20+ and earlier in most managed services. @@ -17,12 +17,12 @@ description: Install the Vault CSI provider using Vault Helm. ## Installation using Helm The [Vault Helm chart](/vault/docs/platform/k8s/helm) is the recommended way to -install and configure the Vault CSI Provider in Kubernetes. +install and configure the Vault Secrets Store CSI provider in Kubernetes. -To install a new instance of Vault and the Vault CSI Provider, first add the +To install a new instance of Vault and the Vault Secrets Store CSI provider, first add the HashiCorp helm repository and ensure you have access to the chart: -~> **Note:** Vault CSI Provider Helm installation requires Vault Helm 0.10.0+. +~> **Note:** Vault Secrets Store CSI provider Helm installation requires Vault Helm 0.10.0+. @include 'helm/repo.mdx' @@ -41,83 +41,47 @@ changes. You can see all the available values settings by running `helm inspect values hashicorp/vault` or by reading the [Vault Helm Configuration Docs](/vault/docs/platform/k8s/helm/configuration). Commonly used values in the Helm -chart include limiting the namespaces the Vault CSI Provider runs in, TLS options and +chart include limiting the namespaces the Vault Secrets Store CSI provider runs in, TLS options and more. ## Installation on OpenShift -We recommend using the [Vault agent injector on Openshift](/vault/docs/platform/k8s/helm/openshift) -instead of the Secrets Store CSI driver. OpenShift -[does not recommend](https://docs.openshift.com/container-platform/4.9/storage/persistent_storage/persistent-storage-hostpath.html) -using `hostPath` mounting in production or -[certify Helm charts](https://github.com/redhat-certification/chart-verifier/blob/dbf89bff2d09142e4709d689a9f4037a739c2244/docs/helm-chart-checks.md#table-2-helm-chart-default-checks) -using CSI objects because pods must run as privileged. Pods will have elevated access to -other pods on the same node, which OpenShift does not recommend. +Run the Red Hat certified Vault Secrets Store CSI provider on an OpenShift +cluster. -You can run the Secrets Store CSI driver with additional -security configurations on a OpenShift development -or testing cluster. +### Prerequisites -Deploy the Secrets Store CSI driver and Vault Helm chart -to your OpenShift cluster. +- OpenShift 4.14+ +- You must have the [Secrets Store CSI driver operator](https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/storage/using-container-storage-interface-csi#persistent-storage-csi-secrets-store-driver-install_persistent-storage-csi-secrets-store) + from Red Hat installed. +- You must have a `ClusterCSIDriver` instance for `secrets-store.csi.k8s.io` created. -Then, patch the `DaemonSet` for the Vault CSI provider to -run with a privileged security context. +### Install using Helm -```shell-session -$ kubectl patch daemonset vault-csi-provider \ - --type='json' \ - --patch='[{"op": "add", "path": "/spec/template/spec/containers/0/securityContext", "value": {"privileged": true} }]' -``` - -The Secrets Store CSI driver and Vault CSI provider need `hostPath` mount access. -Add the service account for the Secrets Store CSI driver to the `privileged` -[security context constraint](https://cloud.redhat.com/blog/managing-sccs-in-openshift). +You must add the Vault Secrets Store CSI provider service account to the +`privileged` +[security context constraint](https://cloud.redhat.com/blog/managing-sccs-in-openshift) +in OpenShift to grant the Vault Secrets Store CSI provider `hostPath` mount +access. ```shell-session -$ oc adm policy add-scc-to-user privileged system:serviceaccount:${KUBERNETES_VAULT_NAMESPACE}:secrets-store-csi-driver +$ oc adm policy add-scc-to-user privileged \ + -z vault-csi-provider \ + -n ${KUBERNETES_VAULT_NAMESPACE} ``` -Add the service account for the Vault CSI provider to the `privileged` -security context constraint. +Install the CSI provider from the OpenShift helm chart repository: ```shell-session -$ oc adm policy add-scc-to-user privileged system:serviceaccount:${KUBERNETES_VAULT_NAMESPACE}:vault-csi-provider +$ helm repo add openshift-helm-charts https://charts.openshift.io/ ``` -You need to give additional access to the application retrieving secrets with the Vault CSI provider. -Create a `SecurityContextConstraint` to `allowHostDirVolumePlugin`, `allowHostDirVolumePlugin`, and -`allowHostPorts` for the application's service account. -You can adjust the other attributes based on your application's runtime configuration. - ```shell-session -$ cat > application-scc.yaml << EOF -apiVersion: security.openshift.io/v1 -kind: SecurityContextConstraints -metadata: - name: vault-csi-provider -allowPrivilegedContainer: false -allowHostDirVolumePlugin: true -allowHostNetwork: true -allowHostPorts: true -allowHostIPC: false -allowHostPID: false -readOnlyRootFilesystem: false -defaultAddCapabilities: -- SYS_ADMIN -runAsUser: - type: RunAsAny -seLinuxContext: - type: RunAsAny -fsGroup: - type: RunAsAny -users: -- system:serviceaccount:${KUBERNETES_APPLICATION_NAMESPACE}:${APPLICATION_SERVICE_ACCOUNT} -EOF +$ helm repo update ``` -Add the security context constraint for the application. - ```shell-session -$ kubectl apply -f application-scc.yaml +$ helm install vault openshift-helm-charts/vault \ + --namespace ${KUBERNETES_VAULT_NAMESPACE} \ + --set="csi.enabled=true" ``` diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/index.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/index.mdx index 22e85433a6..eda1d4ad27 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/index.mdx @@ -41,11 +41,13 @@ to the Vault cluster which can be used to [store audit logs](/vault/docs/audit). native integrations provided by Vault itself, any other tool built for Kubernetes can choose to leverage Vault. -## Getting started with Vault and kubernetes +@include 'kubernetes-supported-versions.mdx' + +## Getting started with Vault and Kubernetes There are several ways to try Vault with Kubernetes in different environments. -### Guides +### Installation guides - [Vault Installation to Minikube via Helm with Integrated Storage](/vault/tutorials/kubernetes/kubernetes-minikube-raft) covers installing Vault locally using Minikube and the official Helm chart. @@ -55,27 +57,18 @@ There are several ways to try Vault with Kubernetes in different environments. - [Vault on Kubernetes Deployment Guide](/vault/tutorials/kubernetes/kubernetes-raft-deployment-guide) covers the steps required to install and configure a single HashiCorp Vault cluster. -### High level comparison of integrations - -There are currently 3 different integrations to help Kubernetes workloads seamlessly consume secrets from Vault, without the need to modify the application to interact directly with Vault. Each integration addresses slightly different use-cases. The following is a brief overview of the strengths of each integration. - -#### Agent injector - -- No durable secret storage outside Vault. All secrets written to disk are in ephemeral in-memory volumes. -- No highly privileged service accounts required. All secrets are fetched with the pod's own service account without the need for any other service accounts to impersonate it. -- More mature solution, with proven production record and advanced features like templating, - wider array of auth methods, etc. - -#### Vault Secrets Operator +### Consume secrets in Kubernetes -- More native UX for app developers. Workloads can mount Kubernetes secrets without adding any Vault-specific configuration. -- Reduced load on Vault. Secrets are synced per CRD instead of per consuming pod. -- Better Vault secret availability. Kubernetes secrets act as a durable cluster-local cache of Vault secrets. +Vault provides the following integrations to seamlessly consume +secrets in your Kubernetes workloads without modifying your +existing application code: -#### Vault CSI provider +* [Vault Secrets Operator](/vault/docs/platform/k8s/vso) + * Protected secrets with [Vault Secrets Operator CSI driver](/vault/docs/platform/k8s/vso/csi) +* [Vault Secrets Store CSI provider](/vault/docs/platform/k8s/csi) +* [Vault Agent Injector](/vault/docs/platform/k8s/injector) -- The CSI driver that the provider is based on is vendor neutral. -- No durable secret storage outside Vault if the secret sync feature isn't used. All secrets written to disk are in ephemeral in-memory volumes. +Refer to the [comparisons](/vault/docs/platform/k8s/comparisons) page for more details. ### Documentation diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/injector/index.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/injector/index.mdx index 205722f453..0a4e28386c 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/injector/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/injector/index.mdx @@ -13,8 +13,6 @@ containers that render Vault secrets to a shared memory volume using By rendering secrets to a shared volume, containers within the pod can consume Vault secrets without being Vault aware. -The Vault Agent Injector is a fully supported component of HashiCorp Vault. - The injector is a [Kubernetes Mutation Webhook Controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/). The controller intercepts pod events and applies mutations to the pod if annotations exist within the request. This functionality is provided by the [vault-k8s](https://github.com/hashicorp/vault-k8s) diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/api-reference.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/api-reference.mdx index 39a13fba9a..7397c7665c 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/api-reference.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/api-reference.mdx @@ -7,7 +7,7 @@ description: >- # API Reference @@ -20,6 +20,8 @@ description: >- Package v1beta1 contains API Schema definitions for the secrets v1beta1 API group ### Resource Types +- [CSISecrets](#csisecrets) +- [CSISecretsList](#csisecretslist) - [HCPAuth](#hcpauth) - [HCPAuthList](#hcpauthlist) - [HCPVaultSecretsApp](#hcpvaultsecretsapp) @@ -41,6 +43,121 @@ Package v1beta1 contains API Schema definitions for the secrets v1beta1 API grou +#### AccessControl + + + +AccessControl provides configuration for controlling access to the secret. +It allows specifying the namespaces, service account, pod names, and pod +labels that should be allowed to access the secret. + + + +_Appears in:_ +- [CSISecretsSpec](#csisecretsspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `serviceAccountPattern` _string_ | ServiceAccountPattern is the name of the service account that should be used to
access the secret. It can be specified as a regex pattern.
A valid service account is always required. | | | +| `namespacePatterns` _string array_ | NamespacePatterns is a list of namespace name regex patterns that are allowed access. | | | +| `podNamePatterns` _string array_ | PodNamePatterns is a list of pod name regex patterns that should be allowed access. | | | +| `podLabels` _object (keys:string, values:string)_ | PodLabels is a map of pod label key-value pairs that should be allowed access. | | | +| `matchPolicy` _string_ | MatchPolicy is the policy to use when matching the access control rules. If
set to "any", only one of the rules should match. If set to "all", all the
rules should match. | all | Enum: [any all]
| + + +#### CSISecrets + + + +CSISecrets is the Schema for the csisecrets API + + + +_Appears in:_ +- [CSISecretsList](#csisecretslist) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | | | +| `kind` _string_ | `CSISecrets` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[CSISecretsSpec](#csisecretsspec)_ | | | | + + +#### CSISecretsList + + + +CSISecretsList contains a list of CSISecrets + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | | | +| `kind` _string_ | `CSISecretsList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `items` _[CSISecrets](#csisecrets) array_ | | | | + + +#### CSISecretsSpec + + + +CSISecretsSpec defines the desired state of CSISecrets. It contains the +configuration for the CSI driver to populate the secret data. + + + +_Appears in:_ +- [CSISecrets](#csisecrets) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `namespace` _string_ | Namespace is the Vault namespace where the secret is located. | | | +| `accessControl` _[AccessControl](#accesscontrol)_ | AccessControl provides configuration for controlling access to the secret. | | | +| `secrets` _[SecretCollection](#secretcollection)_ | Secrets that will be synced with the CSI driver. | | | +| `syncConfig` _[CSISyncConfig](#csisyncconfig)_ | SyncConfig provides configuration for syncing the secret data with the CSI driver. | | | +| `vaultAuthRef` _[VaultAuthRef](#vaultauthref)_ | VaultAuthRef is the reference to the VaultAuth resource. | | | + + + + +#### CSISyncConfig + + + + + + + +_Appears in:_ +- [CSISecretsSpec](#csisecretsspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `containerState` _[ContainerState](#containerstate)_ | ContainerState is the state of the container that the CSI driver always sync
on. This configuration is useful to sync when the last state of the container
is in the terminated state and the restart count is greater than 0. | | | + + +#### ContainerState + + + + + + + +_Appears in:_ +- [CSISyncConfig](#csisyncconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `namePattern` _string_ | NamePattern of the container. Can be expressed as a regular expression. | | | +| `imagePattern` _string_ | ImagePattern of the container. Can be expressed as a regular expression. | | | + + #### Destination @@ -302,6 +419,24 @@ _Appears in:_ | `name` _string_ | Name of the resource | | | +#### SecretCollection + + + + + + + +_Appears in:_ +- [CSISecretsSpec](#csisecretsspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `transformation` _[Transformation](#transformation)_ | Transformation provides configuration for transforming the secret data before
it is stored in the CSI volume. | | | +| `vaultAppRoleSecretIDs` _[VaultAppRoleSecretID](#vaultapprolesecretid) array_ | VaultAppRoleSecretIDs is a list of AppRole secret IDs to be used to populate the secret. | | | +| `vaultStaticSecrets` _[VaultStaticSecretCollectable](#vaultstaticsecretcollectable) array_ | VaultStaticSecrets is a list of static secrets to be synced by the CSI driver. | | | + + #### SecretTransformation @@ -352,10 +487,10 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `templates` _object (keys:string, values:[Template](#template))_ | Templates maps a template name to its Template. Templates are always included
in the rendered K8s Secret with the specified key. | | | -| `sourceTemplates` _[SourceTemplate](#sourcetemplate) array_ | SourceTemplates are never included in the rendered K8s Secret, they can be
used to provide common template definitions, etc. | | | -| `includes` _string array_ | Includes contains regex patterns used to filter top-level source secret data
fields for inclusion in the final K8s Secret data. These pattern filters are
never applied to templated fields as defined in Templates. They are always
applied last. | | | -| `excludes` _string array_ | Excludes contains regex patterns used to filter top-level source secret data
fields for exclusion from the final K8s Secret data. These pattern filters are
never applied to templated fields as defined in Templates. They are always
applied before any inclusion patterns. To exclude all source secret data
fields, you can configure the single pattern ".*". | | | +| `templates` _object (keys:string, values:[Template](#template))_ | Templates maps a template name to its Template. Templates are always included
in the rendered secret with the specified key. | | | +| `sourceTemplates` _[SourceTemplate](#sourcetemplate) array_ | SourceTemplates are never included in the rendered secret, they can be
used to provide common template definitions, etc. | | | +| `includes` _string array_ | Includes contains regex patterns used to filter top-level source secret data
fields for inclusion in the final secret data. These pattern filters are
never applied to templated fields as defined in Templates. They are always
applied last. | | | +| `excludes` _string array_ | Excludes contains regex patterns used to filter top-level source secret data
fields for exclusion from the final secret data. These pattern filters are
never applied to templated fields as defined in Templates. They are always
applied before any inclusion patterns. To exclude all source secret data
fields, you can configure the single pattern ".*". | | | @@ -457,6 +592,9 @@ _Appears in:_ _Appears in:_ - [Destination](#destination) +- [SecretCollection](#secretcollection) +- [VaultAppRoleSecretID](#vaultapprolesecretid) +- [VaultStaticSecretCollectable](#vaultstaticsecretcollectable) | Field | Description | Default | Validation | | --- | --- | --- | --- | @@ -489,6 +627,31 @@ _Appears in:_ | `ignoreExcludes` _boolean_ | IgnoreExcludes controls whether to use the SecretTransformation's Excludes
data key filters. | | | +#### VaultAppRoleSecretID + + + +VaultAppRoleSecretID defines the AppRole secret ID to be used to populate the secret. + + + +_Appears in:_ +- [SecretCollection](#secretcollection) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `mount` _string_ | Mount path to the AppRole auth engine. | | | +| `role` _string_ | Role is the name of the AppRole. | | | +| `metadata` _object (keys:string, values:string)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `cidrList` _string array_ | CIDRList is the list of CIDR blocks that access the secret ID. | | | +| `tokenBoundCIDRs` _string array_ | TokenBoundCIDRs is the list of CIDR blocks that can be used to authenticate
using tokens generated by this secret ID. | | | +| `ttl` _string_ | TTL is the TTL for the secret ID, after which it becomes invalid. | | Pattern: `^([0-9]+(\.[0-9]+)?(s|m|h))$`
| +| `numUses` _integer_ | NumUses is the number of times the secret ID can be used. | | | +| `wrapTTL` _string_ | WrapTTL is the TTL for the wrapped secret ID. | | Pattern: `^([0-9]+(\.[0-9]+)?(s|m|h))$`
| +| `syncRoleID` _boolean_ | SyncRoleID is the flag to fetch the role ID from the AppRole auth engine.
Requires that the provisioning VaultAuth has the necessary permissions to fetch the role ID. | | | +| `transformation` _[Transformation](#transformation)_ | Transformation provides configuration for transforming the secret data before
it is stored in the CSI volume. | | | + + #### VaultAuth @@ -791,7 +954,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | Name of the VaultAuthGlobal resource. | | Pattern: `^([a-z0-9.-]{1,253})$`
| -| `namespace` _string_ | Namespace of the VaultAuthGlobal resource. If not provided, the namespace of
the referring VaultAuth resource is used. | | Pattern: `^([a-z0-9.-]{1,253})$`
| +| `namespace` _string_ | Namespace of the VaultAuthGlobal resource. If not provided, the namespace of
the referring VaultAuth resource is used. | | Pattern: `^([a-z0-9-]{1,63})$`
| | `mergeStrategy` _[MergeStrategy](#mergestrategy)_ | MergeStrategy configures the merge strategy for HTTP headers and parameters
that are included in all Vault authentication requests. | | | | `allowDefault` _boolean_ | AllowDefault when set to true will use the default VaultAuthGlobal resource
as the default if Name is not set. The 'allow-default-globals' option must be
set on the operator's '-global-vault-auth-options' flag

The default VaultAuthGlobal search is conditional.
When a ref Namespace is set, the search for the default
VaultAuthGlobal resource is constrained to that namespace.
Otherwise, the search order is:
1. The default VaultAuthGlobal resource in the referring VaultAuth resource's
namespace.
2. The default VaultAuthGlobal resource in the Operator's namespace. | | | @@ -843,6 +1006,24 @@ VaultAuthList contains a list of VaultAuth | `items` _[VaultAuth](#vaultauth) array_ | | | | +#### VaultAuthRef + + + + + + + +_Appears in:_ +- [CSISecretsSpec](#csisecretsspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name of the VaultAuth resource. | | | +| `namespace` _string_ | Namespace of the VaultAuth resource. | | | +| `trustNamespace` _boolean_ | TrustNamespace of the referring VaultAuth resource. This means that any Vault
credentials will be provided by resources in the same namespace as the
VaultAuth resource. Otherwise, the credentials will be provided by the secret
resource's namespace. | | | + + #### VaultAuthSpec @@ -1005,9 +1186,9 @@ _Appears in:_ | `vaultAuthRef` _string_ | VaultAuthRef to the VaultAuth resource, can be prefixed with a namespace,
eg: `namespaceA/vaultAuthRefB`. If no namespace prefix is provided it will default to
the namespace of the VaultAuth CR. If no value is specified for VaultAuthRef the Operator
will default to the `default` VaultAuth, configured in the operator's namespace. | | | | `namespace` _string_ | Namespace of the secrets engine mount in Vault. If not set, the namespace that's
part of VaultAuth resource will be inferred. | | | | `mount` _string_ | Mount path of the secret's engine in Vault. | | | -| `requestHTTPMethod` _string_ | RequestHTTPMethod to use when syncing Secrets from Vault.
Setting a value here is not typically required.
If left unset the Operator will make requests using the GET method.
In the case where Params are specified the Operator will use the PUT method.
Please consult [secrets](/vault/docs/secrets) if you are
uncertain about what method to use.
Of note, the Vault client treats PUT and POST as being equivalent.
The underlying Vault client implementation will always use the PUT method. | | Enum: [GET POST PUT]
| -| `path` _string_ | Path in Vault to get the credentials for, and is relative to Mount.
Please consult [secrets](/vault/docs/secrets) if you are
uncertain about what 'path' should be set to. | | | -| `params` _object (keys:string, values:string)_ | Params that can be passed when requesting credentials/secrets.
When Params is set the configured RequestHTTPMethod will be
ignored. See RequestHTTPMethod for more details.
Please consult [secrets](/vault/docs/secrets) if you are
uncertain about what 'params' should/can be set to. | | | +| `requestHTTPMethod` _string_ | RequestHTTPMethod to use when syncing Secrets from Vault.
Setting a value here is not typically required.
If left unset the Operator will make requests using the GET method.
In the case where Params are specified the Operator will use the PUT method.
Please consult https://developer.hashicorp.com/vault/docs/secrets if you are
uncertain about what method to use.
Of note, the Vault client treats PUT and POST as being equivalent.
The underlying Vault client implementation will always use the PUT method. | | Enum: [GET POST PUT]
| +| `path` _string_ | Path in Vault to get the credentials for, and is relative to Mount.
Please consult https://developer.hashicorp.com/vault/docs/secrets if you are
uncertain about what 'path' should be set to. | | | +| `params` _object (keys:string, values:string)_ | Params that can be passed when requesting credentials/secrets.
When Params is set the configured RequestHTTPMethod will be
ignored. See RequestHTTPMethod for more details.
Please consult https://developer.hashicorp.com/vault/docs/secrets if you are
uncertain about what 'params' should/can be set to. | | | | `renewalPercent` _integer_ | RenewalPercent is the percent out of 100 of the lease duration when the
lease is renewed. Defaults to 67 percent plus jitter. | 67 | Maximum: 90
Minimum: 0
| | `revoke` _boolean_ | Revoke the existing lease on VDS resource deletion. | | | | `allowStaticCreds` _boolean_ | AllowStaticCreds should be set when syncing credentials that are periodically
rotated by the Vault server, rather than created upon request. These secrets
are sometimes referred to as "static roles", or "static credentials", with a
request path that contains "static-creds". | | | @@ -1150,6 +1331,46 @@ _Appears in:_ | `spec` _[VaultStaticSecretSpec](#vaultstaticsecretspec)_ | | | | +#### VaultStaticSecretCollectable + + + + + + + +_Appears in:_ +- [SecretCollection](#secretcollection) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `mount` _string_ | Mount for the secret in Vault | | | +| `path` _string_ | Path of the secret in Vault, corresponds to the `path` parameter for:
kv-v1: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v1#read-secret
kv-v2: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#read-secret-version | | | +| `version` _integer_ | Version of the secret to fetch. Only valid for type kv-v2. Corresponds to version query parameter:
https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#version | | Minimum: 0
| +| `type` _string_ | Type of the Vault static secret | | Enum: [kv-v1 kv-v2]
| +| `transformation` _[Transformation](#transformation)_ | Transformation provides configuration for transforming the secret data before
it is stored in the CSI volume. | | | + + +#### VaultStaticSecretCommon + + + + + + + +_Appears in:_ +- [VaultStaticSecretCollectable](#vaultstaticsecretcollectable) +- [VaultStaticSecretSpec](#vaultstaticsecretspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `mount` _string_ | Mount for the secret in Vault | | | +| `path` _string_ | Path of the secret in Vault, corresponds to the `path` parameter for:
kv-v1: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v1#read-secret
kv-v2: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#read-secret-version | | | +| `version` _integer_ | Version of the secret to fetch. Only valid for type kv-v2. Corresponds to version query parameter:
https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#version | | Minimum: 0
| +| `type` _string_ | Type of the Vault static secret | | Enum: [kv-v1 kv-v2]
| + + #### VaultStaticSecretList @@ -1183,12 +1404,16 @@ _Appears in:_ | --- | --- | --- | --- | | `vaultAuthRef` _string_ | VaultAuthRef to the VaultAuth resource, can be prefixed with a namespace,
eg: `namespaceA/vaultAuthRefB`. If no namespace prefix is provided it will default to the
namespace of the VaultAuth CR. If no value is specified for VaultAuthRef the Operator will
default to the `default` VaultAuth, configured in the operator's namespace. | | | | `namespace` _string_ | Namespace of the secrets engine mount in Vault. If not set, the namespace that's
part of VaultAuth resource will be inferred. | | | -| `mount` _string_ | Mount for the secret in Vault | | | -| `path` _string_ | Path of the secret in Vault, corresponds to the `path` parameter for,
[kv-v1](/vault/api-docs/secret/kv/kv-v1#read-secret) [kv-v2](/vault/api-docs/secret/kv/kv-v2#read-secret-version) | | | -| `version` _integer_ | Version of the secret to fetch. Only valid for type kv-v2. Corresponds to version query parameter:
[version](/vault/api-docs/secret/kv/kv-v2#version) | | Minimum: 0
| -| `type` _string_ | Type of the Vault static secret | | Enum: [kv-v1 kv-v2]
| | `refreshAfter` _string_ | RefreshAfter a period of time, in duration notation e.g. 30s, 1m, 24h | | Pattern: `^([0-9]+(\.[0-9]+)?(s|m|h))$`
Type: string
| | `hmacSecretData` _boolean_ | HMACSecretData determines whether the Operator computes the
HMAC of the Secret's data. The MAC value will be stored in
the resource's Status.SecretMac field, and will be used for drift detection
and during incoming Vault secret comparison.
Enabling this feature is recommended to ensure that Secret's data stays consistent with Vault. | true | | | `rolloutRestartTargets` _[RolloutRestartTarget](#rolloutrestarttarget) array_ | RolloutRestartTargets should be configured whenever the application(s) consuming the Vault secret does
not support dynamically reloading a rotated secret.
In that case one, or more RolloutRestartTarget(s) can be configured here. The Operator will
trigger a "rollout-restart" for each target whenever the Vault secret changes between reconciliation events.
All configured targets will be ignored if HMACSecretData is set to false.
See RolloutRestartTarget for more details. | | | | `destination` _[Destination](#destination)_ | Destination provides configuration necessary for syncing the Vault secret to Kubernetes. | | | | `syncConfig` _[SyncConfig](#syncconfig)_ | SyncConfig configures sync behavior from Vault to VSO | | | +| `mount` _string_ | Mount for the secret in Vault | | | +| `path` _string_ | Path of the secret in Vault, corresponds to the `path` parameter for:
kv-v1: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v1#read-secret
kv-v2: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#read-secret-version | | | +| `version` _integer_ | Version of the secret to fetch. Only valid for type kv-v2. Corresponds to version query parameter:
https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2#version | | Minimum: 0
| +| `type` _string_ | Type of the Vault static secret | | Enum: [kv-v1 kv-v2]
| + + + + diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/csi/index.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/csi/index.mdx new file mode 100644 index 0000000000..a433206689 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/csi/index.mdx @@ -0,0 +1,61 @@ +--- +layout: docs +page_title: Use protected secrets in Kubernetes +description: >- + Mount secrets from Vault directly into application containers with the Vault + Secrets Operator CSI driver. +--- + +# Use protected secrets in Kubernetes with CSI + +@include 'alerts/enterprise-only.mdx' + +While the Vault Secrets Operator lets you store Vault secrets in clusters as +native Kubernetes Secrets, you must install the Vault Secrets Operator +[CSI driver](https://github.com/container-storage-interface/spec/blob/master/spec.md) +to provide secrets directly to Kubernetes pods as protected secrets. + +The CSI driver hooks into the Pod volume lifecycle so applications can receive secret data from Vault mounted directly to containers as [ephemeral volumes](https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/) with the same lifecycle as the application Pod itself. + +Secret information updates whenever either new requesting Pods come online, or a container in a requesting Pod crashes or exits. + +The Vault Secrets Operator CSI driver supports: + +- Syncing multiple secrets from multiple plugins. Supported plugins include: + - [Key/Value v1](/vault/docs/secrets/kv/kv-v1) + - [Key/Value v2](/vault/docs/secrets/kv/kv-v2) +- Automatic generation and mounting of response-wrapped AppRole secret IDs as a + [trusted orchestrator](/vault/tutorials/app-integration/secure-introduction?in=vault%2Fapp-integration#trusted-orchestrator) for authentication between application Pods and Vault. +- Helm-based [installation](/vault/docs/platform/k8s/vso/installation). +- [Secret data transformation](/vault/docs/platform/k8s/vso/secret-transformation). + +The Vault Secrets Operator CSI driver does not support: + +- [Instant updates](/vault/docs/deploy/kubernetes/vso/sources/vault/instant-updates) + +Refer to the [Vault Secrets Operator CSI driver setup guide](/vault/docs/platform/k8s/vso/csi/setup) +to use protected secrets with your Vault Secrets Operator instance. + +## Secrets flow: Traditional VSO vs CSI driver + +In the traditional workflow, the Vault Secrets Operator caches Vault secrets as Kubernetes Secrets stored in `etcd` +and watches for changes to custom resources such as [VaultStaticSecret](/vault/docs/platform/k8s/vso/api-reference#vaultstaticsecret) or [VaultDynamicSecret](/vault/docs/platform/k8s/vso/api-reference#vaultdynamicsecret). +When the resource definition changes, Vault Secrets Operator overwrites secret data in the associated Kubernetes Secret with the new information. + +[![Diagram showing a secret flowing from Vault, through VSO, into the associated Kubernetes Secrets objects across all nodes in an app namespace](/img/vso_secrets_flow.png)](/img/vso_secrets_flow.png) + +In the CSI driver workflow, Vault Secrets Operator never stores secrets in `etcd` because the driver does not cache secrets as Kubernetes Secrets. +Instead, the driver watches for changes to a custom resource (CR) called `CSISecrets`. The +[CSISecrets](/vault/docs/deploy/kubernetes/vso/api-reference#csisecrets) resource +contains a declarative list of secrets to fetch and an access control +configuration that only allows the designated Pods to mount those secrets. +When an approved Pod starts with a reference to the `CSISecrets` resource as a volume mount, the Vault Secrets Operator CSI driver populates +that volume with the associated secrets for all referencing containers in the Pod. + +The Pod starts with all of the secrets from the `CSISecrets` resource mounted +at the configured path (for example, `/var/run/csi-secrets`) as individual files. +The driver indexes each file with a number representing its position in the +`vaultStaticSecrets` or `vaultAppRoleSecretIDs` list, starting at 0. For example, +`static_secret_0_secret`, `static_secret_1_secret`, ..., `static_secret_N_secret`, or `app_role_N_wrap_info.json`. + +[![Diagram showing a secret flowing directly from Vault, through the CSI driver on a Kubernetes node, and into the associated volume to all nodes in an app namespace](/img/vso_csi_secrets_flow.png)](/img/vso_csi_secrets_flow.png) \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/csi/setup.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/csi/setup.mdx new file mode 100644 index 0000000000..48dd9ee76c --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/csi/setup.mdx @@ -0,0 +1,286 @@ +--- +layout: docs +page_title: Vault Secrets Operator CSI driver setup +description: >- + Install the Vault Secrets Operator CSI driver and + mount secrets into your applications as ephemeral volumes. +--- + +# Set up the Vault Secrets Operator CSI driver + +@include 'alerts/enterprise-only.mdx' + +Use the Vault Secrets Operator CSI driver with a `CSISecrets` resource to +allow authorized Pods to mount ephemeral volumes containing secrets +from Vault as indexed files. Indexing starts at `0` and represents the +associated position in the associated `vaultStaticSecrets` or +`vaultAppRoleSecretIDs` list in the `CSISecrets` resource. For example, +`static_secret_0_secret`, `static_secret_1_secret`, ... `static_secret_N_secret`. + +The CSI driver generates and syncs new AppRole secret IDs on container startup. +All other secrets sync when a requesting container starts or restarts, or when a user modifies a `CSISecrets` resource. + +## Before you start + +- Review the [Vault Secrets Operator threat model](https://github.com/hashicorp/vault-secrets-operator/tree/main/docs/threat-model). + The simplified Kubernetes RBAC configuration examples below are not appropriate for production use. +- Review any applicable regulations or requirements to understand how your + authentication choices may impact cluster security. +- Review the available + [Kubernetes integrations](/vault/docs/deploy/kubernetes/comparisons) to confirm + the Vault Secrets Operator CSI driver functionality meets your needs. +- Review your application deployments to determine how, if at all, they should + handle Pod restarts for secrets updates. + + +## Step 1: Install driver + +Install the Vault Secrets Operator Helm chart with the `csi.enabled` flag set to `true` to deploy the CSI +driver as a DaemonSet running on every node: + +```shell-session +$ helm install \ + --version 1.0.0 \ + --create-namespace \ + --namespace vault-secrets-operator \ + --set "csi.enabled=true" \ + vault-secrets-operator \ + hashicorp/vault-secrets-operator +``` + +Refer to the [Helm chart documentation](/vault/docs/deploy/kubernetes/vso/helm#csi) for additional configuration options. + + +## Step 2: Create your Vault policies + +You must create a Vault [policy](https://developer.hashicorp.com/vault/docs/concepts/policies) to allow the CSI driver to fetch secrets and/or +generate AppRole secret IDs. + +For example, the following policy lets the CSI driver fetch secrets from the +Key/Value plugin: + +```hcl +path "example-kv/password" { + capabilities = ["read"] +} + +path "example-kv-v2/data/api-key" { + capabilities = ["read"] +} + +path "sys/license/status" { + capabilities = ["read"] +} +``` + +To generate AppRole secret IDs with the CSI driver so application Pods can +log into Vault and fetch secrets independently, your Vault policy must grant the CSI driver +permissions for the associated role. + +For example, the following policy lets the CSI driver generate secret IDs +using the AppRole plugin: + +``` +path "auth/approle/role/example-role/secret-id" { + capabilities = ["update"] +} + +path "auth/approle/role/example-role/role-id" { + capabilities = ["read"] +} +``` + +Once you write the policy to Vault, you can create a role that uses that policy +in any auth method supported by Vault Secrets Operator. + +For example, to use the policy with the [Kubernetes](/vault/docs/auth/kubernetes) +auth method: + +```shell-session +$ vault write auth/kubernetes/role/example-auth-role \ + bound_service_account_names=default \ + bound_service_account_namespaces=default,vault-secrets-operator-system \ + token_period=120 \ + token_policies=csi-driver-policy \ + audience=vault +``` + +## Step 3: Create your auth custom resources + +To authenticate the CSI driver to Vault, you must create [`VaultAuth`](/vault/docs/deploy/kubernetes/vso/api-reference#vaultauth) and +[`VaultConnection`](/vault/docs/deploy/kubernetes/vso/api-reference#vaultconnection) resources, +as defined in the Custom Resource Definitions (CRDs) of the Vault Secrets Operator Helm chart and apply it to your cluster. + +You can reference existing auth resources from Vault Secrets Operator or create entirely new resources. For example: + +```yaml +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultAuth +metadata: + name: default + namespace: vault-secrets-operator-system +spec: + vaultAuthGlobalRef: + name: default + +--- + +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultAuthGlobal +metadata: + name: default + namespace: vault-secrets-operator-system +spec: + defaultAuthMethod: kubernetes + kubernetes: + audiences: + - vault + mount: kubernetes + role: example-auth-role + serviceAccount: example-service-account + tokenExpirationSeconds: 600 + +--- + +apiVersion: secrets.hashicorp.com/v1beta1 +kind: VaultConnection +metadata: + name: default + namespace: vault-secrets-operator-system +spec: + address: http://vault.vault.svc.cluster.local:8200 + skipTLSVerify: false +``` + +For more detailed resource examples, refer to the Vault Secrets Operator guide for +[Vault authentication](/vault/docs/deploy/kubernetes/vso/sources/vault/auth). + +## Step 4: Create the CSISecrets resource + +To securely sync secrets between Vault and your application Pods, you +must create a custom resource called `CSISecrets` that lists information +available to the CSI driver Pods. + +For example, the following resource definition creates a single `CSISecrets` +resource that can: + +- Generate secret IDs from an `approle` auth method mounted at `auth/approle` + for a role configured with the name `my-app`. +- Limit which Pods can use the associated `CSISecrets` resource based on regular + expression patterns in the `accessControl` field. +- Fetch secrets from a `kv` v1 secrets engine mounted at `kv1`. +- Fetch secrets from a `kv` v2 secrets engine mounted at `kv2`. + +```yaml +apiVersion: secrets.hashicorp.com/v1beta1 +kind: CSISecrets +metadata: + name: my-app-secrets + namespace: vault-secrets-operator-system +spec: + vaultAuthRef: + name: default + secrets: + vaultStaticSecrets: + - mount: kv1 + path: app-api-key + type: kv-v1 + - mount: kv2 + path: app-api-key + type: kv-v2 + version: 1 # The version of the KV secret -- if not specified, defaults to the latest version + vaultAppRoleSecretIDs: + - role: my-app + mount: approle + wrapTTL: "30m" + ttl: "1h" + numUses: 2 + accessControl: + serviceAccountPattern: "default" + namespacePatterns: + - "default" + podNamePatterns: + - "^my-app-" + syncConfig: + containerState: + namePattern: "^(app|sidecar)$" +``` + +Refer to the full [`CSISecrets` API reference](/vault/docs/deploy/kubernetes/vso/api-reference#csisecrets) for additional configuration options. + + +## Step 5: Mount the volume to your containers + +Update the deployment spec for your application: + +- Add the new `CSISecrets` resource to the `volumeMounts` field. +- Define a [regular expression](https://pkg.go.dev/regexp/syntax) in the `accessControl` stanza of your `CSISecrets` resource that specifies which Pods can access the secret data. + +For example: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app + namespace: default + labels: + app.kubernetes.io/component: my-app +spec: + selector: + matchLabels: + app.kubernetes.io/component: my-app + replicas: 2 + template: + metadata: + labels: + app.kubernetes.io/component: my-app + spec: + serviceAccountName: default + containers: + - name: app + image: my-app-image:latest + volumeMounts: + - name: csi-secrets + mountPath: /var/run/csi-secrets + - name: sidecar + image: my-app-sidecar-image:latest + volumeMounts: + - name: csi-secrets + mountPath: /var/run/csi-secrets + volumes: + - name: csi-secrets + csi: + driver: csi.vso.hashicorp.com + volumeAttributes: + csiSecretsName: my-app-secrets + csiSecretsNamespace: vault-secrets-operator-system +``` + + + +You can also use the Kubernetes +[`subPath`](https://kubernetes.io/docs/concepts/storage/volumes/#using-subpath) +field and the associated file index to limit which secret files a container can +access. For example, the following `subPath` limits access to the first `approle` +secret (`app_role_0_wrap_info.json`): + +```yaml +volumeMounts: +- name: csi-secrets + mountPath: /var/run/app_role_0_wrap_info.json + subPath: app_role_0_wrap_info.json +``` + + + +Next, push the new configuration so the CSI driver Pod on your application Pod +node responds to the request. If the update succeeds, the `kubelet` publishes +a volume containing all the secrets from the `CSISecrets` resource. + +## Step 6: Verify Pods can access secrets appropriately + +Once a Pod starts, you can verify whether it does, or does not, have access to the relevant `CSISecrets` resource +by inspecting files on the configured mount. +For example, `/var/run/csi-secrets`. + diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/helm.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/helm.mdx index 95942f06e1..bc13953600 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/helm.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/helm.mdx @@ -28,6 +28,7 @@ Use these links to navigate to a particular top-level stanza. - [`defaultAuthMethod`](#h-defaultauthmethod) - [`telemetry`](#h-telemetry) - [`hooks`](#h-hooks) +- [`csi`](#h-csi) - [`tests`](#h-tests) ## All Values @@ -39,6 +40,8 @@ Use these links to navigate to a particular top-level stanza. - `replicas` ((#v-controller-replicas)) (`integer: 1`) - Set the number of replicas for the operator. + - `priorityClassName` ((#v-controller-priorityclassname)) (`string: ""`) - Set the priority class for the operator. + - `strategy` ((#v-controller-strategy)) (`object: ""`) - Configure update strategy for multi-replica deployments. Kubernetes supports types Recreate, and RollingUpdate ref: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy @@ -89,6 +92,28 @@ Use these links to navigate to a particular top-level stanza. - antarctica-east1 - antarctica-west1 + - `topologySpreadConstraints` ((#v-controller-topologyspreadconstraints)) (`array: []`) - TopologySpreadConstraints settings for vault-secrets-operator pod. + The value is an array of PodSpec TopologySpreadConstraint maps. + A labelSelector for the pods will be added automatically to the template in case it is not set. + ref: https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/ + Example: + topologySpreadConstraints: + - maxSkew: 1 + topologyKey: zone + whenUnsatisfiable: DoNotSchedule + + - `podDisruptionBudget` ((#v-controller-poddisruptionbudget)) - Configure the PodDisruptionBudget for the controller deployment. + + - `enabled` ((#v-controller-poddisruptionbudget-enabled)) (`boolean: false`) - toggles the deployment of the PodDisruptionBudget for the controller. + + - `maxUnavailable` ((#v-controller-poddisruptionbudget-maxunavailable)) (`string: 0`) - Sets the maximum number of pods that can be unavailable during the eviction. + This field cannot be set if minAvailable is set. + Can be set as an integer (e.g. "2") or a percentage (e.g. "50%"). + + - `minAvailable` ((#v-controller-poddisruptionbudget-minavailable)) (`string: 0`) - Sets the number of pods that must be available during the eviction. + This field cannot be set if maxUnavailable is set. + Can be set as an integer (e.g. "2") or a percentage (e.g. "50%"). + - `rbac` ((#v-controller-rbac)) - `clusterRoleAggregation` ((#v-controller-rbac-clusterroleaggregation)) - clusterRoleAggregation defines the roles included in the aggregated ClusterRole. @@ -205,7 +230,7 @@ Use these links to navigate to a particular top-level stanza. - `globalVaultAuthOptions` ((#v-controller-manager-globalvaultauthoptions)) - Global Vault auth options. In addition to the boolean options below, these options may be set via the - `VSO_GLOBAL_VAULT_OPTION_OPTIONS` environment variable as a + `VSO_GLOBAL_VAULT_AUTH_OPTIONS` environment variable as a comma-separated list. Valid values are: `allow-default-globals` - `allowDefaultGlobals` ((#v-controller-manager-globalvaultauthoptions-allowdefaultglobals)) (`boolean: true`) - allowDefaultGlobals directs the operator search for a "default" @@ -726,6 +751,160 @@ Use these links to navigate to a particular top-level stanza. - `executionTimeout` ((#v-hooks-upgradecrds-executiontimeout)) (`string: 30s`) - Set the timeout for the CRD upgrade. The operation should typically take less than 5s to complete. +### csi ((#h-csi)) + +- `csi` ((#v-csi)) + + - `enabled` ((#v-csi-enabled)) (`boolean: false`) - Only supports Vault Enterprise servers. + Toggles the deployment of the Vault Secrets Operator CSI driver. This will deploy the driver and the necessary + resources to the cluster. + + - `hostAliases` ((#v-csi-hostaliases)) (`array`) - Host Aliases settings for the vault-secrets-operator-csi pods. + The value is an array of PodSpec HostAlias maps. + ref: https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/ + Example: + hostAliases: + - ip: 192.168.1.100 + hostnames: + - vault.example.com + + - `nodeSelector` ((#v-csi-nodeselector)) (`map`) - nodeSelector labels for vault-secrets-operator-csi pod assignment. + ref: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector + Example: + nodeSelector: + beta.kubernetes.io/arch: amd64 + + - `tolerations` ((#v-csi-tolerations)) (`array`) - Toleration Settings for vault-secrets-operator-csi pods. + The value is an array of PodSpec Toleration maps. + ref: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/ + Example: + tolerations: + - key: "key1" + operator: "Equal" + value: "value1" + effect: "NoSchedule" + + - `affinity` ((#v-csi-affinity)) - Affinity settings for vault-secrets-operator-csi pods. + The value is a map of PodSpec Affinity maps. + ref: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity + Example: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: topology.kubernetes.io/zone + operator: In + values: + - antarctica-east1 + - antarctica-west1 + + - `imagePullSecrets` ((#v-csi-imagepullsecrets)) (`array`) - Image pull secret to use for private container registry authentication which will be applied to the controllers + service account. Alternatively, the value may be specified as an array of strings. + Example: + ```yaml + imagePullSecrets: + - name: pull-secret-name-1 + - name: pull-secret-name-2 + ``` + Refer to https://kubernetes.io/docs/concepts/containers/images/#using-a-private-registry. + + - `extraLabels` ((#v-csi-extralabels)) - Extra labels to attach to the deployment. This should be formatted as a YAML object (map) + + - `annotations` ((#v-csi-annotations)) - This value defines additional annotations for the deployment. This should be formatted as a YAML object (map) + + - `driver` ((#v-csi-driver)) + + - `image` ((#v-csi-driver-image)) - Image sets the repo and tag of the vault-secrets-operator-csi image to use for the driver. + + - `pullPolicy` ((#v-csi-driver-image-pullpolicy)) (`string: IfNotPresent`) + + - `repository` ((#v-csi-driver-image-repository)) (`string: hashicorp/vault-secrets-operator-csi`) + + - `tag` ((#v-csi-driver-image-tag)) (`string: 0.0.0-dev`) + + - `extraEnv` ((#v-csi-driver-extraenv)) (`array`) - Defines additional environment variables to be added to the + CSI driver container. + + - `extraArgs` ((#v-csi-driver-extraargs)) (`array: []`) - Extra arguments to pass to the driver. + + - `logging` ((#v-csi-driver-logging)) - logging + + - `level` ((#v-csi-driver-logging-level)) (`string: info`) - Sets the log level for the driver. + Builtin levels are: info, error, debug, debug-extended, trace + Default: info + + - `timeEncoding` ((#v-csi-driver-logging-timeencoding)) (`string: rfc3339`) - Sets the time encoding for the driver. + Options are: epoch, millis, nano, iso8601, rfc3339, rfc3339nano + Default: rfc3339 + + - `stacktraceLevel` ((#v-csi-driver-logging-stacktracelevel)) (`string: panic`) - Sets the stacktrace level for the driver. + Options are: info, error, panic + Default: panic + + - `backoffOnSecretSourceError` ((#v-csi-driver-backoffonsecretsourceerror)) (`object: ""`) - Backoff settings for the CSI driver. These settings control the backoff behavior + when the driver encounters an error while fetching secrets from the SecretSource. + For example given the following settings: + initialInterval: 5s + maxInterval: 60s + randomizationFactor: 0.5 + multiplier: 1.5 + + The backoff retry sequence might be something like: + 5.5s, 7.5s, 11.25s, 16.87s, 25.3125s, 37.96s, 56.95, 60.95s... + + - `initialInterval` ((#v-csi-driver-backoffonsecretsourceerror-initialinterval)) (`duration: 5s`) - Initial interval between retries. + + - `maxInterval` ((#v-csi-driver-backoffonsecretsourceerror-maxinterval)) (`duration: 60s`) - Maximum interval between retries. + + - `maxElapsedTime` ((#v-csi-driver-backoffonsecretsourceerror-maxelapsedtime)) (`duration: 0s`) - Maximum elapsed time without a successful sync from the secret's source. + It's important to note that setting this option to anything other than + its default will result in the secret sync no longer being retried after + reaching the max elapsed time. + + - `randomizationFactor` ((#v-csi-driver-backoffonsecretsourceerror-randomizationfactor)) (`float: 0.5`) - Randomization factor randomizes the backoff interval between retries. + This helps to spread out the retries to avoid a thundering herd. + If the value is 0, then the backoff interval will not be randomized. + It is recommended to set this to a value that is greater than 0. + + - `multiplier` ((#v-csi-driver-backoffonsecretsourceerror-multiplier)) (`float: 1.5`) - Sets the multiplier that is used to increase the backoff interval between retries. + This value should always be set to a value greater than 0. + The value must be greater than zero. + + - `livenessProbe` ((#v-csi-livenessprobe)) + + - `image` ((#v-csi-livenessprobe-image)) - Image sets the repo and tag of the image to use for the liveness probe. + + - `pullPolicy` ((#v-csi-livenessprobe-image-pullpolicy)) (`string: IfNotPresent`) + + - `repository` ((#v-csi-livenessprobe-image-repository)) (`string: registry.k8s.io/sig-storage/livenessprobe`) + + - `tag` ((#v-csi-livenessprobe-image-tag)) (`string: v2.10.0`) + + - `extraArgs` ((#v-csi-livenessprobe-extraargs)) (`array: []`) - Extra arguments to pass to the liveness probe container. + + - `nodeDriverRegistrar` ((#v-csi-nodedriverregistrar)) + + - `image` ((#v-csi-nodedriverregistrar-image)) - Image sets the repo and tag of the image to use for the node driver registrar. + + - `pullPolicy` ((#v-csi-nodedriverregistrar-image-pullpolicy)) (`string: IfNotPresent`) + + - `repository` ((#v-csi-nodedriverregistrar-image-repository)) (`string: registry.k8s.io/sig-storage/csi-node-driver-registrar`) + + - `tag` ((#v-csi-nodedriverregistrar-image-tag)) (`string: v2.8.0`) + + - `extraArgs` ((#v-csi-nodedriverregistrar-extraargs)) (`array: []`) - Extra arguments to pass to the node driver registrar container. + + - `updateStrategy` ((#v-csi-updatestrategy)) (`object: ""`) - Configure update strategy for the DaemonSet + Kubernetes supports types Recreate, and RollingUpdate + ref: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy + Example: + strategy: {} + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + type: RollingUpdate + ### tests ((#h-tests)) - `tests` ((#v-tests)) - # Used by unit tests, and will not be rendered except when using `helm template`, this can be safely ignored. diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/index.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/index.mdx index 4fc560ca50..8a92eb21cd 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/index.mdx @@ -19,6 +19,13 @@ The operator writes the *source* secret data directly to the *destination* Kuber changes made to the *source* are replicated to the *destination* over its lifetime. In this way, an application only needs to have access to the *destination* secret in order to make use of the secret data contained within. + + +Deploy Vault Secrets Operator with the CSI driver to mount +secrets directly to pods without using Kubernetes Secrets. + + + ## Features The following features are supported by the Vault Secrets Operator: diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/installation.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/installation.mdx index 9989eda6ce..2093029225 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/installation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/installation.mdx @@ -41,6 +41,25 @@ Then install the Operator: $ helm install --version 0.10.0 --create-namespace --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator ``` +## CSI driver option + +You can also use the Vault Secrets Operator Helm chart to deploy a DaemonSet of the +[Vault Secrets Operator CSI driver](/vault/docs/platform/k8s/vso/csi) with +the `"csi.enabled"` flag: + +```shell-session +$ helm install \ + --version 0.10.0 \ + --create-namespace \ + --namespace vault-secrets-operator \ + --set "csi.enabled=true" \ + vault-secrets-operator \ + hashicorp/vault-secrets-operator +``` + +Refer to the [Vault Secrets Operator CSI driver](/vault/docs/platform/k8s/vso/csi) +documentation to learn how to use the CSI driver to mount secrets directly to application pods. + ## Updating CRDs when using Helm diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/secret-transformation.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/secret-transformation.mdx index 79efaa9d83..6c3277e116 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/secret-transformation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/vso/secret-transformation.mdx @@ -266,4 +266,5 @@ dig "foo" "nux" "" .Secrets -> `` - [VaultDynamicSecret](/vault/docs/platform/k8s/vso/api-reference#vaultdynamicsecret) - [VaultPKISecret](/vault/docs/platform/k8s/vso/api-reference#vaultpkisecret) - [VaultStaticSecret](/vault/docs/platform/k8s/vso/api-reference#vaultstaticsecret) +- [CSISecrets](/vault/docs/platform/k8s/vso/api-reference#csisecrets) - [SecretTransformation](/vault/docs/platform/k8s/vso/api-reference#secrettransformation) diff --git a/content/vault/v1.21.x (rc)/content/docs/enterprise/audit/filtering.mdx b/content/vault/v1.21.x (rc)/content/docs/enterprise/audit/filtering.mdx index 37472132e9..88d589d340 100644 --- a/content/vault/v1.21.x (rc)/content/docs/enterprise/audit/filtering.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/enterprise/audit/filtering.mdx @@ -13,14 +13,16 @@ As of Vault 1.16.0, you can enable audit devices with a `filter` option to limit the audit entries written to a particular audit log and fine-tune your auditing process. - + Filtering audit logs is an advanced feature. Exclusively enabling filtered devices without configuring an audit fallback may lead to gaps in your audit logs. **Always** test your audit configuration in a non-production environment - before deploying filters to production. And make sure to read the + before deploying filters to production, including the + [performance impact](/vault/docs/concepts/filtering#performance) of your configured + filters. And make sure to read the [Vault security model](/vault/docs/internals/security) and [filtering overview](/vault/docs/concepts/filtering) to familiarize yourself with Vault auditing and filtering basics before enabling filtered audit @@ -169,19 +171,20 @@ The `/var/kv-audit.log` now includes four entries in total: The fallback device captured entries for the other commands. And the original audit file, `vault-audit.log`, continues to capture all audit events. +## Additional resources - - - - [Filtering](/vault/docs/concepts/filtering) + - + - [Filtering](/vault/docs/concepts/filtering) - + - - [Audit API](/vault/api-docs/system/audit#common-configuration-options) + - + - [Audit API](/vault/api-docs/system/audit#common-configuration-options) + + diff --git a/content/vault/v1.21.x (rc)/content/docs/index.mdx b/content/vault/v1.21.x (rc)/content/docs/index.mdx index 6f1596a778..6efce800f5 100644 --- a/content/vault/v1.21.x (rc)/content/docs/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/index.mdx @@ -6,11 +6,10 @@ description: >- common tasks, and best practices. --- -# Documentation +# Vault product documentation -Welcome to the Vault product documentation! + -If you are getting started with Vault, we recommend reading the -[What is Vault](/vault/docs/what-is-vault) docs before diving into our -[Vault Foundations tutorial set](/vault/tutorials/getting-started) -or our [Vault operator quickstart guide](/vault/docs/get-started/operations-qs). \ No newline at end of file +You are currently viewing documentation for an older version of Vault. + + diff --git a/content/vault/v1.21.x (rc)/content/docs/internals/recommended-patterns.mdx b/content/vault/v1.21.x (rc)/content/docs/internals/recommended-patterns.mdx index 1cb7b22eff..98629743d1 100644 --- a/content/vault/v1.21.x (rc)/content/docs/internals/recommended-patterns.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/internals/recommended-patterns.mdx @@ -18,6 +18,7 @@ Help keep your Vault environments operating effectively by implementing the foll | [Improve upgrade cadence](#improve-upgrade-cadence) | Enterprise, Community | | [Test before upgrades](#test-before-upgrades) | Enterprise, Community | | [Rotate audit device logs](#rotate-audit-device-logs) | Enterprise, Community | +| [Monitor limits and maximums](/vault/docs/internals/limits) | Enterprise, Community | | [Monitor metrics](#monitor-metrics) | Enterprise, Community | | [Establish usage baseline](#establish-usage-baseline) | Enterprise, Community | | [Minimize root token use](#minimize-root-token-use) | All | diff --git a/content/vault/v1.21.x (rc)/content/docs/license/product-usage-reporting.mdx b/content/vault/v1.21.x (rc)/content/docs/license/product-usage-reporting.mdx index 9a314122d0..a3e42e7480 100644 --- a/content/vault/v1.21.x (rc)/content/docs/license/product-usage-reporting.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/license/product-usage-reporting.mdx @@ -169,9 +169,15 @@ All of these metrics are numerical, and contain no sensitive values or additiona | `vault.secret.engine.activedirectory.count` | The total number of Active Directory secret engines in Vault. | | `vault.secret.engine.alicloud.count` | The total number of Alicloud secret engines in Vault. | | `vault.secret.engine.aws.count` | The total number of AWS secret engines in Vault. | +| `vault.secret.engine.aws.dynamic.role.count` | The total number of AWS dynamic roles in Vault. | +| `vault.secret.engine.aws.static.role.count` | The total number of AWS static roles in Vault. | `vault.secret.engine.azure.count` | The total number of Azure secret engines in Vault. | +| `vault.secret.engine.azure.dynamic.role.count` | The total number of Azure dynamic roles in Vault. | | `vault.secret.engine.consul.count` | The total number of Consul secret engines in Vault. | | `vault.secret.engine.gcp.count` | The total number of GCP secret engines in Vault. | +| `vault.secret.engine.gcp.impersonated.account.count` | The total number of GCP impersonated accounts in Vault. | +| `vault.secret.engine.gcp.roleset.count` | The total number of GCP rolesets in Vault. | +| `vault.secret.engine.gcp.static.role.count` | The total number of GCP static roles in Vault. | `vault.secret.engine.gcpkms.count` | The total number of GCPKMS secret engines in Vault. | | `vault.secret.engine.kubernetes.count` | The total number of Kubernetes secret engines in Vault. | | `vault.secret.engine.cassandra.count` | The total number of Cassandra secret engines in Vault. | diff --git a/content/vault/v1.21.x (rc)/content/docs/mcp-server/deploy.mdx b/content/vault/v1.21.x (rc)/content/docs/mcp-server/deploy.mdx new file mode 100644 index 0000000000..ae58cd63fc --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/mcp-server/deploy.mdx @@ -0,0 +1,355 @@ +--- +page_title: Deploy the Vault model context protocol (MCP) server +description: |- + Learn how to deploy the Vault MCP server, which helps you interact with HashiCorp Vault APIs. +--- + +# Deploy the Vault MCP server + +The Vault Model Context Protocol (MCP) server enables AI models to interact with Vault and perform actions using up-to-date APIs. This page explains how to install, configure, and integrate the MCP server with your AI client. + +## Overview + +The Vault MCP server is a specialized service that provides AI models with access to Vault APIs. +You can deploy the server using the `stdio` mode for direct communication through standard input/output, or using `streamable-http` for network-based communication. + +The Vault MCP server is still in beta. We recommend that you only run the server locally, without exposing it to other network users. + +### Installation methods + +Choose from three installation options based on your environment and preferences: + +| Method | Best for | Requirements | +|--------|----------|--------------| +| [Docker](#run-in-docker) | Most users, consistent environments | Docker Engine v20.10.21+ or Docker Desktop v4.14.0+. Refer to the [Docker documentation](https://docs.docker.com/desktop) for installation instructions. | +| [Compiled binary](#run-the-compiled-binary) | Lightweight deployments, specific OS needs | Compatible operating system | +| [Source installation](#install-from-source) | Development, customization | Go development environment | + +## Run in Docker + +Docker provides the most reliable and consistent way to run the Vault MCP server across different environments. + +1. Start Docker on your system. +1. Integrate with your AI client: + + + + + +1. Verify [Visual Studio Code](https://code.visualstudio.com/docs) is installed. +1. Verify the [GitHub Copilot extension](https://code.visualstudio.com/docs/copilot/overview) is installed and chats are configured to `Agent` mode. +1. Verify MCP support enabled, refer to the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more information. +1. To use the MCP server in all workspaces, add the following configuration to your user settings JSON file: + + ```json + { + "mcp": { + "servers": { + "vault-mcp-server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", "VAULT_ADDR", + "-e", "VAULT_NAMESPACE", + "-e", "VAULT_TOKEN", + "hashicorp/vault-mcp-server" + ], + "env": { + "VAULT_ADDR": "${input:vault_address}", + "VAULT_NAMESPACE": "${input:vault_namespace}", + "VAULT_TOKEN": "${input:vault_token}" + }, + "type": "stdio" + } + }, + "inputs": [ + { + "type": "promptString", + "id": "vault_address", + "description": "Vault address", + "password": false + }, + { + "type": "promptString", + "id": "vault_namespace", + "description": "Vault Namespace (optional)", + "password": false + }, + { + "type": "promptString", + "id": "vault_token", + "description": "Vault Token", + "password": true + } + ] + } + } + ``` + + Alternatively, to use the server in a specific workspace, create an `mcp.json` file with the following configuration in your workspace's `.vscode` directory: + + ```json +{ + "inputs": [ + { + "type": "promptString", + "id": "vault_address", + "description": "Vault address", + "password": false + }, + { + "type": "promptString", + "id": "vault-namespace", + "description": "Vault Namespace (optional)", + "password": false + }, + { + "type": "promptString", + "id": "vault-token", + "description": "Vault Token", + "password": true + } + ], + "servers": { + "vault-mcp-server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", "VAULT_ADDR", + "-e", "VAULT_NAMESPACE", + "-e", "VAULT_TOKEN", + "hashicorp/vault-mcp-server" + ], + "env": { + "VAULT_ADDR": "${input:vault_address}", + "VAULT_NAMESPACE": "${input:vault_namespace}", + "VAULT_TOKEN": "${input:vault_token}" + }, + "type": "stdio" + } + } +} + ``` + +1. Verify the integration by opening the chat interface and selecting **Agent** from the mode settings. +1. Click the tools icon to verify that Vault MCP server tools appear in the available tools list. + + + + +1. Verify [Cursor](https://www.cursor.com) is installed. +1. Verify the MCP support configured, refer to [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) for more information. +1. To use the MCP server in all workspaces, add the following configuration to your user settings JSON file: + + ```json + { + "mcp": { + "servers": { + "vault": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", "<>", + "-e", "<>", + "-e", "<>", + "hashicorp/vault-mcp-server" + ], + "type": "stdio" + } + } + } + } + ``` + + Alternatively, to use the server in a specific workspace, create an `mcp.json` file with the following configuration in your workspace's `.vscode` directory: + + ```json + { + "servers": { + "vault": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", "<>", + "-e", "<>", + "-e", "<>", + "hashicorp/vault-mcp-server" + ], + "type": "stdio" + } + } + } + ``` + +1. Verify the installation by opening the chat pane and selecting **Chat Settings** from the ellipses menu. +1. Choose **Agent** from the **Default new chat mode** drop-down menu. +1. Select **MCP** from the **Cursor Settings** sidebar to verify that Vault MCP server tools are enabled. + + + + +1. Verify [Claude Desktop](https://support.anthropic.com/en/articles/10065433-installing-claude-for-desktop) is installed. +1. Verify MCP support is configured, refer to [Claude Desktop's MCP documentation](https://modelcontextprotocol.io/quickstart/user) for more information. +1. Create or edit the `mcp.json` file and add the following configuration: + + ```json + { + "mcpServers": { + "servers": { + "vault-mcp-server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", "<>", + "-e", "<>", + "-e", "<>", + "hashicorp/vault-mcp-server" + ], + "type": "stdio" + } + } + } + } + ``` + +1. Verify the integration by opening the chat pane and clicking the **search and tools** slider icon. +1. Click **vault-mcp-server** to verify that all tools are enabled and accessible. + + + + +1. Verify [Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html) is installed. +1. Verify MCP support is configured, refer to [Amazon Q's MCP documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/qdev-mcp.html) for more information. +1. Create or edit the `mcp.json` file with the following configuration: + +```json +{ + "mcpServers": { + "servers": { + "vault-mcp-server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", "<>", + "-e", "<>", + "-e", "<>", + "hashicorp/vault-mcp-server" + ], + "type": "stdio" + } + } + } +} +``` + + + + +## Run the compiled binary + +The compiled binary option provides a lightweight installation without Docker dependencies. This method is ideal when you want to minimize resource usage or work in environments with restricted container access. + +1. Download the binary for your operating system and architecture, visit the [release library](https://releases.hashicorp.com/vault-mcp-server). +1. Add the following configuration to your client settings. Replace `/path/to/vault-mcp-server` with the actual path to your downloaded binary. + + + + ```json + { + "mcp": { + "servers": { + "vault": { + "command": "/path/to/vault-mcp-server", + "args": ["stdio"], + "env": { + "VAULT_ADDR": "<>", + "VAULT_NAMESPACE": "<>", + "VAULT_TOKEN": "<>" + } + } + } + } + } + ``` + + + +## Install from source + +Installing from source gives you access to the latest features and allows for customization. This method requires a Go development environment. + +1. Install the latest stable release. + + ```shell-session + $ go install github.com/hashicorp/vault-mcp-server/cmd/vault-mcp-server@latest + ``` + + Alternatively, you can install the development version on `main`. + + ```shell-session + $ go install github.com/hashicorp/vault-mcp-server/cmd/vault-mcp-server@main + ``` + +1. After installation, add the following configuration to your client. + + ```json + { + "mcp": { + "servers": { + "vault": { + "command": "/path/to/vault-mcp-server", + "args": ["stdio"], + "env": { + "VAULT_ADDR": "<>", + "VAULT_NAMESPACE": "<>", + "VAULT_TOKEN": "<>" + } + } + } + } + } + ``` + + Replace `/path/to/vault-mcp-server` with the actual path to your downloaded binary. The binary location depends on your Go installation and `GOPATH` configuration. + + Use `which vault-mcp-server` to find the installed binary path. + +## Start the server + +You can use the `vault-mcp-server` CLI and specify the transport protocol you want to use to start the server. Refer to the [transport protocols reference](/vault/docs/mcp-server/reference#transport-protocols) for more information. + +Start the server in `stdio` mode. + +```shell-session +$ vault-mcp-server stdio [--log-file /path/to/log] +``` + +Run the following command on the local instance to start the server in `streamable-http` mode: + +```shell-session +$ vault-mcp-server streamable-http \ + [--transport-port 8080] \ + [--transport-host 127.0.0.1] \ + [--mcp-endpoint /mcp] \ + [--log-file /path/to/log] +``` + +Instead of setting values manually, you can also use the supported environment variables. Refer to the [environment variables reference](/vault/docs/mcp-server/reference#environment-variables) for details. + +## Next steps + +- Begin prompting your AI model about Vault operations. Refer to [Prompt an AI model](/vault/docs/mcp-server/prompt-model) for guidance on effective prompting techniques. +- Ask for help with specific Vault operations and workflows. +- Explore advanced configuration options for your specific deployment needs. diff --git a/content/vault/v1.21.x (rc)/content/docs/mcp-server/overview.mdx b/content/vault/v1.21.x (rc)/content/docs/mcp-server/overview.mdx new file mode 100644 index 0000000000..25fa921da6 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/mcp-server/overview.mdx @@ -0,0 +1,53 @@ +--- +layout: docs +page_title: Vault MCP Server +description: >- + Learn about the Vault model context protocol (MCP) server and how it can help you interact with HashiCorp Vault using AI. +--- + +# Vault MCP server + +The Vault MCP Server is a Model Context Protocol (MCP) server implementation that provides integration with HashiCorp Vault for managing secrets and mounts. +This server uses both `stdio` and `StreamableHTTP` transports for MCP communication, making it compatible with Claude for Desktop and other MCP clients. + +@include 'alerts/beta.mdx' + + + +Depending on the query, the MCP server may expose certain Vault data, including Vault secrets, to MCP clients and LLMs interacting with the server. Do not use the MCP server with untrusted MCP clients or LLMs. + +Your use of third-party MCP clients and LLMs is subject solely to the terms of use for those MCP servers and LLMs. IBM is not responsible for the performance of such third party tools. IBM expressly disclaims any and all warranties and liability for third party MCP clients and LLMs, and may not be able to provide support to resolve issues caused by the third party tools. + + + +## What is the Vault MCP server? + +The Model Context Protocol (MCP) is an open standard that enables AI models to securely connect with external tools, applications, and data sources. MCP allows AI models to access information beyond their training data, providing more current and accurate responses. + +The Vault MCP server implements this protocol specifically for interacting with Vault APIs, offering several key benefits: + +- Understanding code bases and automatically invoke Vault based workflows +- Help configure PKI certificates with new or existing codebases +- Perform automated Vault operations using natural language + +## How it works + +When you connect an AI model to the Vault MCP server, the model gains access to specialized tools that can perform the following actions: + +- List, Delete, Create mounts in Vault (KV v1, KV v2) +- List, Delete, Read, Write secrets to KV mounts +- Enable PKI secrets engine +- Issue PKI certificate +- List, Create, Read PKI issuers, roles +- Delete PKI roles +- Comprehensive HTTP middleware stack (CORS, logging, Vault context) +- Session-based Vault client management +- Structured logging with configurable output + +The AI model uses these tools automatically when you ask questions about securely storing secrets. + +The server specifically handles Vault API based interaction. For general Vault questions, AI models use their standard training data and other sources. + +## Additional resources +- [Vault MCP server repository](https://github.com/hashicorp/vault-mcp-server): For source code, issues and contributions. +- [Vault MCP server releases](https://releases.hashicorp.com/vault-mcp-server): Provides links for downloading prebuilt binaries. diff --git a/content/vault/v1.21.x (rc)/content/docs/mcp-server/prompt-model.mdx b/content/vault/v1.21.x (rc)/content/docs/mcp-server/prompt-model.mdx new file mode 100644 index 0000000000..9a99bcfee1 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/mcp-server/prompt-model.mdx @@ -0,0 +1,408 @@ +--- +page_title: Prompt an AI model connected to the Vault MCP server +description: |- + Learn how to prompt your AI model connected to the Vault MCP server to manage HashiCorp Vault secrets, PKI certificates, and system configurations. +--- + +# Prompt a model connected to the Vault MCP server + +This topic provides example prompts for helping you manage HashiCorp Vault after installing the Vault model context protocol (MCP) server. Refer to [Deploy the Vault MCP server](/vault/docs/mcp-server/deploy) for instructions on how to deploy the server. + +@include 'alerts/beta.mdx' + +## Overview + +To trigger the MCP server tools, ask your LLM questions about Vault secrets management, PKI certificate operations, or system administration tasks. The LLM will use the Vault MCP server to perform these operations directly against your Vault instance. Note that for your LLM to use the server, your questions must pertain to specific Vault operations like managing secrets, configuring PKI, or administering mounts. + +## Requirements + +Verify that you have deployed the Vault MCP server and configured your client. Requirements include: + +- A running HashiCorp Vault instance +- Valid Vault authentication token with appropriate permissions +- Vault MCP server deployed and accessible +- MCP client configured (Claude for Desktop, VS Code, etc.) + +Refer to [Deploy the Vault MCP server](/vault/docs/mcp-server/deploy) for instructions. + +## Prompt your MCP client + +Your model may still decide to use other resources to formulate responses, but you can use the following guidelines to help you create prompts that are more likely to be routed through the server: + +- Include specific Vault terminology like "secret engine", "mount path", "PKI role", or "certificate issuance" +- Specify exact paths and mount names when working with secrets (e.g., `/secret/myapp/config`) +- Use clear action words like "create", "read", "write", "delete", "list", or "issue" +- Mention specific secret engine types like "KV v2", "PKI", or "key-value store" +- Reference Vault-specific concepts like TTL, certificate authorities, or namespace + +## Examples + +You can use the following set of prompts as a guide to help you write your own Vault operations. The following responses are returned from the server using ChatGPT 4.1 in GitHub Copilot on VS Code. Your responses may vary. + +### Manage key-value secrets + +In the following example, the server manages secrets in a key-value store: + +#### Prompt + +```text +I need to store database credentials for my application. +Create a secret at secret/myapp/database with username "dbuser" +and password "secure123" +``` + +#### Server workflow + +The server performs the following operations: + +1. **Check mount existence**: Verifies that the `secret/` mount exists +2. **Write secret**: Creates the secret with the specified key-value pairs + +#### API calls + +```json +{ + "mount": "secret", + "path": "myapp/database", + "key": "username", + "value": "dbuser" +} +``` + +```json +{ + "mount": "secret", + "path": "myapp/database", + "key": "password", + "value": "secure123" +} +``` + +#### Sample response + + + +```text +Successfully stored database credentials in Vault: + +**Secret Path**: `secret/myapp/database` +**Keys Stored**: +- username: dbuser +- password: [hidden] + +The secret has been written to your Vault KV v2 store. You can retrieve +these credentials using the path `secret/myapp/database` in your application +or by reading the secret directly from Vault. + +**Security Note**: Ensure your application has appropriate Vault policies +to read from this path while following the principle of least privilege. +``` + + + +### Set up PKI certificate authority + +The following prompt creates a complete PKI infrastructure for SSL/TLS certificates: + +```text +I need to set up a PKI certificate authority for my internal +services. Create a root CA for "example.com" and configure +a role that can issue certificates for subdomains. +``` + +#### PKI setup workflow + +The server performs multiple coordinated operations: + +1. **Enable PKI mount**: Creates a new PKI secrets engine +2. **Create root issuer**: Generates the root certificate authority +3. **Create PKI role**: Configures certificate issuance policies +4. **Issue certificate**: Generates a certificate for validation + +#### PKI API sequence + +```json +{ + "path": "pki_root", + "description": "Root CA for example.com internal services", + "max_ttl": "87600h" +} +``` + +```json +{ + "mount": "pki_root", + "type": "internal", + "common_name": "example.com Root CA", + "issuer_name": "example-root-ca", + "ttl": "87600h" +} +``` + +```json +{ + "mount": "pki_root", + "role_name": "subdomain-role", + "allowed_domains": "example.com", + "allow_subdomains": true, + "allow_bare_domains": false, + "max_ttl": "8760h" +} +``` + +#### PKI setup response + + + +```text +Successfully configured PKI infrastructure for example.com: + +## Root Certificate Authority +- **Mount Path**: `pki_root/` +- **Issuer Name**: `example-root-ca` +- **Common Name**: `example.com Root CA` +- **Validity Period**: 10 years (87600h) + +## Certificate Role Configuration +- **Role Name**: `subdomain-role` +- **Allowed Domains**: `example.com` +- **Subdomain Support**: ✅ Enabled +- **Max Certificate TTL**: 1 year (8760h) +- **Usage Flags**: Server & Client Authentication + +## Next Steps +You can now issue certificates using: +vault write pki_root/issue/subdomain-role \ + common_name="api.example.com" \ + ttl="720h" + +## Certificate Validation +The PKI infrastructure is ready to issue certificates for: +- `*.example.com` (subdomains) +- Custom TTL up to 1 year +- Both server and client authentication use cases +``` + + + +### List and audit secrets + +The following prompt performs security auditing across Vault: + +```text +I need to audit all secrets in my Vault. Show me what +mounts exist and list the secrets in the main KV store. +``` + +#### Audit workflow + +1. **List all mounts**: Discovers available secrets engines +2. **List secrets in KV**: Enumerates stored secrets +3. **Security analysis**: Provides audit recommendations + +#### Audit API calls + +```json +{} +``` + +```json +{ + "mount": "secret", + "path": "" +} +``` + +#### Audit response + + + +```text +# Vault Security Audit Report + +## Available Mounts +| Mount Path | Type | Description | +|------------|----------|---------------------------| +| `secret/`. | kv-v2 | Key-Value secrets engine | +| `pki_root/`| pki. | PKI Certificate Authority | +| `sys/` | system | Vault system backend. | +| `identity/`| identity | Identity secrets engine | + +## Secrets Inventory (secret/ mount) +secret/ +├── myapp/ +│ ├── database +│ ├── api-keys +│ └── certificates +├── shared/ +│ └── service-accounts +└── infrastructure/ + ├── monitoring + └── backup-configs + +## Security Recommendations +- **Access Review**: Verify policies for each secret path +- **Rotation Schedule**: Implement regular secret rotation +- **Audit Logging**: Enable detailed audit logs for compliance +- **Least Privilege**: Ensure applications have minimal required access + +**Total Secrets Found**: 7 secret paths across 3 applications +**Mount Health**: All mounts operational ✅ +``` + + + +### Issue SSL certificates for applications + +The following prompt demonstrates certificate lifecycle management: + +```text +Issue an SSL certificate for my web application at +"api.internal.example.com" valid for 30 days using +the existing PKI role. +``` + +#### Certificate issuance workflow + +1. **Validate role**: Confirms the PKI role exists and policies +2. **Issue certificate**: Generates new SSL certificate +3. **Return artifacts**: Provides certificate, private key, and chain + +#### Certificate API call + +```json +{ + "mount": "pki_root", + "role_name": "subdomain-role", + "common_name": "api.internal.example.com", + "ttl": "720h", + "format": "pem" +} +``` + +#### Certificate response + + + +```text +Successfully issued SSL certificate for api.internal.example.com: + +## Certificate Details +- **Common Name**: `api.internal.example.com` +- **Serial Number**: `39:d4:f7:2c:8a:1b:5e:9f` +- **Validity Period**: 30 days (720h) +- **Key Algorithm**: RSA 2048-bit +- **Signature**: SHA256-RSA + +## Certificate Files +-----BEGIN CERTIFICATE----- +MIIDXTCCAkWgAwIBAgIJAOT7Wq... +[Certificate content] +-----END CERTIFICATE----- + +## Private Key +-----BEGIN PRIVATE KEY----- +MIIEvgIBADANBgkqhkiG9w0BAQ... +[Private key content - handle securely] +-----END PRIVATE KEY----- + +## Certificate Chain +-----BEGIN CERTIFICATE----- +[Intermediate CA certificate] +-----END CERTIFICATE----- + +## Installation Instructions +1. Save certificate to: `/etc/ssl/certs/api.internal.example.com.crt` +2. Save private key to: `/etc/ssl/private/api.internal.example.com.key` +3. Set secure permissions: `chmod 600 /etc/ssl/private/*.key` +4. Update web server configuration to use new certificate +5. Restart web server to apply changes + +**Security**: Store private key securely and never share it. +Certificate expires in 30 days - set up renewal automation. +``` + + + +### Delete and cleanup secrets + +The following prompt demonstrates secure cleanup operations: + +```text +I need to clean up old secrets. Delete the database +credentials from secret/legacy/old-app and remove +the entire legacy mount if it's empty. +``` + +#### Cleanup workflow + +1. **Delete specific secret**: Removes the targeted secret path +2. **List remaining secrets**: Checks if mount is empty +3. **Conditional cleanup**: Removes mount if no secrets remain + +#### Cleanup API calls + +```json +{ + "mount": "secret", + "path": "legacy/old-app" +} +``` + +```json +{ + "mount": "secret", + "path": "legacy/" +} +``` + +#### Cleanup response + + + +```text +Cleanup operations completed successfully: + +## Deleted Resources +- ✅ **Secret Removed**: `secret/legacy/old-app` + - All versions and metadata permanently deleted + - Secret contained 3 keys (username, password, connection_string) + +## Mount Analysis +- **Path**: `secret/legacy/` +- **Status**: Empty (no remaining secrets) +- **Recommendation**: Mount can be safely removed if no longer needed + +## Security Notes +- **Audit Trail**: Deletion logged in Vault audit logs +- **Recovery**: No recovery possible - ensure backups if needed +- **Access Policies**: Review and clean up associated Vault policies + +Would you like me to remove the empty legacy path structure +or keep it for future use? +``` + + + +## Best practices for Vault MCP prompts + +### Effective prompt structure + +- **Be Specific**: Use exact mount paths and secret names +- **Include Context**: Mention the purpose (app credentials, certificates, etc.) +- **Specify Requirements**: TTL values, certificate parameters, security policies +- **Request Validation**: Ask for confirmation of operations before execution + +### Security considerations + +- **Principle of Least Privilege**: Request minimal necessary permissions +- **Audit Trail**: Ensure operations are logged and traceable +- **Secret Lifecycle**: Consider rotation, expiration, and cleanup +- **Access Patterns**: Design secrets structure for application access patterns + +### Common use cases + +- **Application Secrets**: Database credentials, API keys, service tokens +- **PKI Management**: Certificate authorities, SSL certificates, key rotation +- **Infrastructure Automation**: Terraform secrets, CI/CD credentials +- **Compliance**: Audit trails, access reviews, secret inventory \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/docs/mcp-server/reference.mdx b/content/vault/v1.21.x (rc)/content/docs/mcp-server/reference.mdx new file mode 100644 index 0000000000..774a7c94ea --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/mcp-server/reference.mdx @@ -0,0 +1,89 @@ +--- +page_title: Vault MCP server reference +description: Learn about the configuration options and tools available for the Vault MCP server. +--- + +# Vault MCP server reference + +This page contains reference information about the Vault MCP server, including configuration options and tools. + +## Available tools + +The Vault MCP server provides specialized tools that AI models can use to access and perform certain Vault operations. These tools work automatically when you ask relevant questions—you don't need to invoke them manually. + +### Key-Value (kv) tools + +| Tool | Purpose | What it returns | +|----------------|----------------------------------------------|-------------------------------------------------| +| `list_secrets` | List all secrets stored in Vault | A list of secret paths | +| `create_secret`| Create a new secret in Vault | Confirmation of the secret creation | +| `read_secret` | Retrieve the value of a specific secret | The secret value | +| `delete_secret`| Delete a specific secret from Vault | Confirmation of the secret deletion | + +Example prompt: "How can I securely store and access an API key for my application?" + +### Public Key Infrastructure (pki) tools + +| Tool | Purpose | What it returns | +|------------------------|---------------------------------------------|--------------------------------------------------| +| `create_pki_issuer` | Create a new PKI issuer in Vault | Confirmation of the PKI issuer creation | +| `create_pki_role` | Create a new PKI role in Vault | Confirmation of the PKI role creation | +| `delete_pki_role` | Delete a specific PKI role from Vault | Confirmation of the PKI role deletion | +| `enable_pki` | Enable the PKI secrets engine in Vault | Confirmation of the PKI engine enablement | +| `issue_pki_certificate`| Issue a new certificate from a PKI role | The issued certificate details | +| `list_pki_issuers` | List all PKI issuers in Vault | A list of PKI issuers | +| `list_pki_roles` | List all PKI roles in Vault | A list of PKI roles | +| `read_pki_issuer` | Retrieve details of a specific PKI issuer | Details of the PKI issuer | +| `read_pki_role` | Retrieve details of a specific PKI role | Details of the PKI role | + +Example prompt: "Show me how to issue pki certificate using the `app-dev` role." + +### System (sys) tools + +| Tool | Purpose | What it returns | +|------|---------|-----------------| +| `list_mounts` | List all mounts in Vault | A list of mount paths and their configurations | +| `create_mount` | Create a new KV mount (v1 or v2) in Vault | Confirmation of the mount creation | +| `delete_mount` | Delete a specific mount from Vault | Confirmation of the mount deletion | + +Example prompt: "Create a KV mount named "secrets" to store arbitrary secrets" + +## Transport protocols + +You can set one of the following transport protocols when starting the MCP server so that it operates correctly for your environment. + +| Transport | Best for | How it works | Usage | +|------------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------| +| `stdio` | Local development and direct integration with MCP clients | Uses standard input/output for JSON-RPC message communication | Automatically used when no specific transport mode is configured | +| `streamable-http`| Distributed setups, internal environments | HTTP-based transport with support for both direct HTTP requests | Enable by setting `TRANSPORT_MODE=streamable-http` | + +## HTTP mode configuration + +At this stage, the MCP server is intended for local use only. If using the StreamableHTTP transport in production, always configure the MCP_ALLOWED_ORIGINS environment variable to restrict access to trusted origins only. +This helps prevent DNS rebinding attacks and other cross-origin vulnerabilities. + +In HTTP mode, Vault configuration can be provided through multiple methods (**in order of precedence**): + +- HTTP Query: `VAULT_ADDR` +- HTTP Headers: `VAULT_ADDR`, `X-Vault-Token`, and `X-Vault-Namespace` +- Environment Variables: Standard `VAULT_ADDR`, `VAULT_TOKEN`, and `VAULT_NAMESPACE env vars` + +## Environment variables + +You can set the following environment variables to configure the server behavior. + +| Variable | Purpose | Default value | Example | Options | +|--------------------------|--------------------------------------------------------------|---------------------------|--------------------------------|-----------------------------------------| +| `VAULT_ADDR` | Vault server address | `http://127.0.0.1:8200` | `http://vault.example.com:8200`| Any valid Vault server address | +| `VAULT_TOKEN` | Vault authentication token (required) | — | `hvs.xxxxxxxx` | Any valid Vault token | +| `VAULT_NAMESPACE` | Vault namespace (optional) | — | `admin` | Any valid Vault namespace | +| `TRANSPORT_MODE` | Set to `http` to enable HTTP mode | — | `http` | `http` | +| `TRANSPORT_HOST` | Host to bind to for HTTP mode | `127.0.0.1` | `0.0.0.0` | Any valid IP address | +| `TRANSPORT_PORT` | Port for HTTP mode | `8080` | `3000` | Any valid port number | +| `MCP_ENDPOINT` | HTTP server endpoint path | `/mcp` | `/api/mcp` | Any valid endpoint path | +| `MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS | `""` (none) | `http://mcp.client.com:5000`. | Comma-separated list of origins or `""` | +| `MCP_CORS_MODE` | CORS mode: `strict`, `development`, or `disabled` | `strict` | `development` | `strict`, `development`, `disabled` | +| `MCP_TLS_CERT_FILE` | Location of the TLS certificate file | `""` | `/path/to/cert.pem` | Any valid file path | +| `MCP_TLS_KEY_FILE` | Location of the TLS key file | `""` | `/path/to/key.pem` | Any valid file path | +| `MCP_RATE_LIMIT_GLOBAL` | Global rate limit (format: rps:burst) | `10:20` | `100:200` | Any valid rps:burst value | +| `MCP_RATE_LIMIT_SESSION` | Per-session rate limit (format: rps:burst) | `5:10` | `20:40` | Any valid rps:burst value | diff --git a/content/vault/v1.21.x (rc)/content/docs/mcp-server/security-model.mdx b/content/vault/v1.21.x (rc)/content/docs/mcp-server/security-model.mdx new file mode 100644 index 0000000000..504599e3c4 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/mcp-server/security-model.mdx @@ -0,0 +1,107 @@ +--- +page_title: Security model for Vault MCP server +description: |- + Learn about Vault's MCP Server security model to identify potential security threats and follow our recommendations for using the Vault MCP Server securely. +--- + +# Security model for Vault MCP server + +## Purpose of this document + +This document explains the security model for the Vault Model Context Protocol (MCP) server when operating the server locally using the STDIO or streamable HTTP transport. +Understanding this model helps you safely integrate local AI agents with Vault tooling. +This ensures the following outcomes, even in local environments: + +- Tool execution is safe and controlled +- Sensitive operations are protected from accidental misuse or injection +- LLM behavior is constrained and auditable prior to application. + +## Important concepts + +### Model Context Protocol (MCP) + +MCP is a protocol allowing language models (or agents) to call tools programmatically through structured and standardized definitions. + +### MCP host + +An AI application or environment in which AI-driven tasks are performed that operates the MCP client. (e.g. Claude Desktop). + +### MCP client + +The MCP Client handles discovery and communication between the MCP Host and the MCP Server by translating model prompts into executable actions. + +### MCP server + +A service which gets called by the MCP Client to execute various tools, resources and prompts. It provides a server or tool manifest for allowing dynamic discovery of available capabilities. + +### MCP tool + +A server-defined executable function or operation (e.g. "list", "write", "delete") with defined inputs and outputs callable by clients. + +### MCP transport + +The underlying communication of how messages are sent and received via JSON-RPC 2.0. Stdio allows direct tool invocation via standard input/output pipe. Streamable HTTP exposes a local server (e.g., on 127.0.0.1:port) to receive and respond to MCP tool calls. + +## Threat model + + + +Depending on the query, the MCP server may expose certain Vault data, including Vault secrets, to MCP clients and LLMs interacting with the server. Do not use the MCP server with untrusted MCP clients or LLMs. + +Your use of third-party MCP clients and LLMs is subject solely to the terms of use for those MCP servers and LLMs. IBM is not responsible for the performance of such third party tools. IBM expressly disclaims any and all warranties and liability for third party MCP clients and LLMs, and may not be able to provide support to resolve issues caused by the third party tools. + + + +### Hallucination + +AI hallucinations, or the generation of false information, stem from insufficient training data, flawed model assumptions, and biased datasets. They pose serious risks in critical applications where accuracy is vital for correct diagnoses and sound decisions. We recommend users to always validate the output of the LLM model prior to applying any changes in their environment. + +### Prompt injection + +Improper validation or sanitization of user input can allow attackers to inject malicious instructions that the MCP Server will execute. This can lead to code execution, Server Side Request Forgery (SSRF), and various other security breaches. + +### Tool poisoning + +Tool poisoning occurs when the MCP Server inadvertently executes hidden instructions within comprehensive tool descriptions, enabling attackers to instigate unwanted or damaging outcomes + +### Rug pull attack + +In case a remotely accessible MCP Server changes its available tools and descriptions after being deployed, this enables malicious behavior that wasn't present when the tool was initially approved. + +### Tool shadowing + +When multiple MCP servers are connected, a malicious one can override tools from a trusted one, leading to potential security breaches. + +## Threat model exclusions + +The following are not part of the threat model for the Vault MCP Server: + +### Foundational model + +Concerns related to the underlying AI models, training data, and inherent vulnerabilities. + +## Recommendations for securely using the Vault MCP server + +### Ensuring local-only server access + +We recommend running the MCP Server locally (127.0.0.1) through the STDIO or HTTP Streamable transport protocol to limit the exposure of your Vault environment to the public. The default transport is set to STDIO. Users deciding to host the service remotely should add additional security controls at the application and network level. + +### Enabling CORS + +By default, the supported CORS mode is strict and the allowed origins are empty meaning that all cross-origin requests will be blocked unless the server is explicitly configured to allow them. Users should cautiously edit the allowed origins to include the MCP Client and Vault server endpoints. + +### Protect authentication to Vault + +We recommend not disabling the `VAULT_SKIP_VERIFY` option to keep comminication with your Vault environment encrypted. We also recommend to not use a root or shared `VAULT_TOKEN`, the Vault token used should be created by the end-user running the MCP server and have limited permissions associated to it. + +### Rate limiting + +We recommend setting up the global and per session rate limiting to prevent overloading the MCP server or dependent resources such as the Vault instance through excessive requests. + +### Securing in-transit communication + +In case you want to make your MCP Server accessible remotely, we enforce configuring a valid TLS certificate to protect in-transit communication of your data. + +### Disabling privileged operations + +The `ENABLE_VAULT_OPERATIONS` option is used to enable or disable tools that performs privileged opperations. We recommend setting it to false if you don't want to allow the MCP Server to create, edit or remove secrets in Vault. diff --git a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/changelog.mdx b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/changelog.mdx index d30107f0c8..849b49193a 100644 --- a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/changelog.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/changelog.mdx @@ -9,6 +9,12 @@ description: Release notes for the Vault EKM Provider for Microsoft SQL Server. Each version is available to download from the [releases](https://releases.hashicorp.com/vault-mssql-ekm-provider/) page. +## 0.3.0 (August 7th, 2025) + +FEATURES + +* The provider supports pinning the transit key version to use previous key versions after the transit key is rotated. + ## 0.2.2 (August 10th, 2023) BUGS diff --git a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/installation.mdx b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/installation.mdx index d7ed680719..8b69c16154 100644 --- a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/installation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/installation.mdx @@ -50,7 +50,7 @@ EKM provider to use it. -> **Note:** After authenticating to Vault with the AppRole, the EKM provider will re-use the token it receives until it expires, at which point it will authenticate using the AppRole credentials again; it will not attempt to renew -its token. The example AppRole configuraiton here will work for this, but keep +its token. The example AppRole configuration here will work for this, but keep that in mind if you choose to use a different AppRole configuration. 1. Retrieve the AppRole ID and secret ID for use later when configuring SQL Server: @@ -140,8 +140,10 @@ The remaining steps are all run on the database server. ### Configure the EKM provider using SQL -Open Microsoft SQL Server Management Studio, and run the queries below to complete -installation. +Open Microsoft SQL Server Management Studio, and run the queries below to encrypt a +DB using the EKM provider. + +-> **Note:** If restoring a backup encrypted with the EKM provider, refer to steps 1 through 3. 1. Enable the EKM feature and create a cryptographic provider using the folder you just installed the EKM provider into. @@ -201,6 +203,21 @@ installation. Vault is misconfigured, this step is likely to fail. See [troubleshooting](/vault/docs/platform/mssql/troubleshooting) for tips on specific error codes. + The above steps use the latest version of the specified Transit key as the asymmetric Key Encryption Key (KEK). To + use a different version of the Transit key, please specify the version as shown below. + + ```sql + CREATE ASYMMETRIC KEY TransitVaultAsymmetricV1 + FROM PROVIDER TransitVaultProvider + WITH + CREATION_DISPOSITION = OPEN_EXISTING, + PROVIDER_KEY_NAME = 'ekm-encryption-key?version=1'; + ``` + -> **Note:** Specifying the version + of the Transit key can be useful when sharing KEKs across different SQL Server instances, or in cases of restoring + a database backup that was protected by an older Transit key. + **Note:** This requires vault-mssql-ekm-provider version >= 0.3.0. + 1. Create another login from the new asymmetric key: ```sql diff --git a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/rotation.mdx b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/rotation.mdx index d70c42839e..94b06c7434 100644 --- a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/rotation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/rotation.mdx @@ -61,3 +61,15 @@ go ALTER DATABASE ENCRYPTION KEY ENCRYPTION BY SERVER ASYMMETRIC KEY TransitVaultAsymmetricV2; ``` + +The above steps will wrap the DEK with the latest version of the specified Transit key as the asymmetric KEK. To use a different version of the Transit key, please specify the version as shown below. + +```sql +CREATE ASYMMETRIC KEY TransitVaultAsymmetricV1 +FROM PROVIDER TransitVaultProvider +WITH CREATION_DISPOSITION = OPEN_EXISTING, +PROVIDER_KEY_NAME = 'ekm-encryption-key?version=1'; +``` + +-> **Note:** This requires vault-mssql-ekm-provider version >= 0.3.0. + diff --git a/content/vault/v1.21.x (rc)/content/docs/platform/servicenow/configuration.mdx b/content/vault/v1.21.x (rc)/content/docs/platform/servicenow/configuration.mdx index e6233e64e9..613f54450f 100644 --- a/content/vault/v1.21.x (rc)/content/docs/platform/servicenow/configuration.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/platform/servicenow/configuration.mdx @@ -99,10 +99,8 @@ In the ServiceNow UI: 1. Choose a type from the list. 1. Select "External credential store". 1. Provide a fully qualified collection name (FQCN): - - **Yokohama or newer**: in the **Credentials** section of the ServiceNow - webpage, select your credentials and click **ⓘ** for the "Credential - Storage Vault" mid server. Click **Open Record** to add the vault resolver - FQCN: `com.snc.discovery.CredentialResolver` + - **Zurich**: Follow the same setup steps as "Yokohama Patch 7". + - **Yokohama**: Requires "Yokohama Patch 7" for CredentialResolver UI support. - **Xanadu (Q4-2024) or newer**: use `com.snc.discovery.CredentialResolver` - **Versions prior to Xanadu (Q4-2024)**: leave blank or use "None" 1. Provide a meaningful name for the resolver. diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/index.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/index.mdx index 4b9f05825d..71f3a4facb 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/index.mdx @@ -105,6 +105,8 @@ TTL. For more details on rotating root credentials in the DB Secrets engine, refer to the [Rotate Root credentials](/vault/api-docs/secret/databases#rotate-root-credentials) API docs. +@include 'rotation-manager-logging.mdx' + ## Setup Most secrets engines must be configured in advance before they can perform their @@ -397,6 +399,8 @@ or otherwise, it will not be rotated until the next scheduled rotation. !> The `rotation_period` and `rotation_schedule` fields are mutually exclusive. One of them must be set but not both. +Vault logs rotations with reference to the `name` of the role and `error` if the rotation failed. The logs also indicate if the rotation was part of a `periodic function`. + ## Password generation Passwords are generated via [Password Policies](/vault/docs/concepts/password-policies). diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx index e6d82cdb8c..99f11a6799 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx @@ -71,6 +71,8 @@ For the Enterprise Oracle database plugin, see the following table: | Plugin release | Instant Client version | | ---------------| -----------------------| +| 0.12.3+ent | 19.26 | +|----------------|------------------------| | 0.11.0+ent | 19.26 | The following privileges are needed by the plugin for minimum functionality. Additional privileges may be needed diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/snowflake.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/snowflake.mdx index 56805396b0..4db5e5070f 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/snowflake.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/snowflake.mdx @@ -71,10 +71,6 @@ The Snowflake database secrets engine uses `db_name` is the name of a database in your Snowflake instance. - ~> **Note:** The user being utilized should have `ACCOUNT_ADMIN` privileges, and should be different - from the root user you were provided when making your Snowflake account. This allows you to rotate - the root credentials and still be able to access your account. - 1. Configure Vault with keypair authentication. Do not provide templated or hard-coded username or password information in the connection URL if you use key-pair authentication. The Snowflake plugin appropriately constructs the diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/gcp.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/gcp.mdx index bd034ca102..fcc9a5286f 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/gcp.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/gcp.mdx @@ -694,7 +694,7 @@ if you need to limit Vault API exposure. 1. [Authenticate a workload](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#authenticate) in GCP by granting the identity pool access to a dedicated service account using service account impersonation. Filter requests using the unique `sub` claim issued by plugin identity tokens so the GCP Auth engine can -impersonate the service account. `sub` claims have the form: `plugin-identity::secret:`. +impersonate the service account. `sub` claims have the form: `plugin-identity::secret:`. 1. Configure the GCP secrets engine with the OIDC audience value and service account email. diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/ldap.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/ldap.mdx index 4fa8ac41e8..ff323171a0 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/ldap.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/ldap.mdx @@ -158,6 +158,8 @@ TTL. For more details on rotating root credentials in the LDAP plugin, refer to the [Root credential rotation](/vault/api-docs/secret/ldap#rotate-root) API docs. +@include 'rotation-manager-logging.mdx' + ## Static credentials ### Setup @@ -194,11 +196,18 @@ role, the response will include the time before the next rotation (`ttl`). The `binddn` account used by Vault should be rotated using the `rotate-root` endpoint to generate a password only Vault will know. +As with the rotation manager, Vault logs rotations with reference to the +`name` of the role and `error` if the rotation failed. The logs also indicate +if the rotation was part of a `periodic function`. + ### Manual rotation Static roles can be manually rotated using the `rotate-role` endpoint. When manually rotated the rotation period will start over. +Logging for manual rotation records the same information as other rotation +logging with an additional reference that the rotation happened `on user request`. + ### Deleting static roles Passwords are not rotated upon deletion of a static role. The password should be manually diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx index 1cdfbd1fc1..535abd0356 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx @@ -5,7 +5,7 @@ description: >- Automatically back up the data in your Vault cluster. --- -## Automate Vault cluster snapshots +# Automate Vault cluster snapshots @include 'alerts/enterprise-only.mdx' @@ -15,8 +15,8 @@ local or cloud storage. ## Before you start -- **You must a working knowledge of how Vault saves data**. -- **You must have a valid Vault cluster configuration using integratd storage**. +- **You must have a working knowledge of how Vault saves data**. +- **You must have a valid Vault cluster configuration using integrated storage**. - **You must know, and be able to contact your unseal/recovery key holders**. - **You must have permission to access encrypted data in backed storage**. - **You should have a secure location, away from your Vault cluster @@ -32,7 +32,7 @@ maintenance, we recommend saving your autosnapshot settings to a JSON file. ### Local storage example The following JSON file, `local-snapshot.json`, defines an automated snapshot -configuration that uses local storage with custom file and path prefixs. The +configuration that uses local storage with custom file and path prefixes. The configuration also sets a 120 minute snapshot frequency, a retention window of 7 snapshots before deleting, and limits the amount of local storage consumed by the snapshot files so Vault stops writing snapshot data if the combined file @@ -100,7 +100,7 @@ $ vault write \ ``` For example, to configure automated snapshots with local storage in an -unreplicated envionrment: +unreplicated environment: @@ -142,7 +142,7 @@ $ curl \ ``` For example, to configure automated snapshots with local storage in an -unreplicated envionrment called `local-snaps`: +unreplicated environment called `local-snaps`: diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/index.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/index.mdx index 7721fce13e..44439cf295 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/index.mdx @@ -31,8 +31,8 @@ Step-by-step instructions: - [Save a snapshot](/vault/docs/sysadmin/snapshots/save) - [Restore a snapshot](/vault/docs/sysadmin/snapshots/restore) -- [Recover discrete secrets in a replicated evironment](/vault/docs/sysadmin/snapshots/reocver-a-secret/replicated-cluster) -- [Recover discrete secrets in a non-replicated evironment](/vault/docs/sysadmin/snapshots/reocver-a-secret/single-cluster) +- [Recover discrete secrets in a replicated environment](/vault/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster) +- [Recover discrete secrets in a non-replicated environment](/vault/docs/sysadmin/snapshots/recover-a-secret/single-cluster) - [Automate snapshots](/vault/docs/sysadmin/snapshots/recover-a-secret) - [Recover discrete secrets](/vault/docs/sysadmin/snapshots/recover-a-secret) @@ -53,7 +53,7 @@ Detailed tutorials: - [Vault with integrated storage reference architecture](/vault/tutorials/day-one-raft/raft-reference-architecture) - Learn about architectural and operational best practices for deploying Vault - with integraged storage backends in a production environment. + with integrated storage backends in a production environment. - [Configure Vault cluster with integrated storage](/vault/tutorials/raft/raft-storage#automated-snapshots) - Follow a detailed walkthrough for configuring and using automated snapshots. diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/index.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/index.mdx index 70da50a713..05deb0dade 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/index.mdx @@ -18,7 +18,7 @@ can access the data and assign a snapshot ID. Then you can use the snapshot ID to read, list, and recover individual paths from the snapshot. To recover the data, Vault reads the secret at the path from the snapshot to -retrieve that version of the data and sends it to the assocaited plugin backend +retrieve that version of the data and sends it to the associated plugin backend to perform the necessary recover operations. The plugin backend uses the provided data and its own information to create or update data at the specified path in live storage. @@ -39,7 +39,7 @@ supported plugins and paths. Secret restoration has limitations in replicated environments: -- If the active node changes, the loaded snapshot status changes to`error` and +- If the active node changes, the loaded snapshot status changes to `error` and Vault cannot use it for recover operations. You must unload and reload the snapshot to use it again. - Disaster recovery secondaries cannot load snapshots. diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx index a30b5a9e37..7ca61d1fd6 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx @@ -31,7 +31,7 @@ Load the snapshot holding the secret you want to recover: - For performance replication clusters, you can load snapshots on any cluster, but secondary clusters can only perform snapshot operations on paths that - correspond to local mounts. You must use the primary performance node to peform + correspond to local mounts. You must use the primary performance node to perform snapshot operations on shared paths. diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/restore.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/restore.mdx index 29305366ac..442e312dfa 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/restore.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/restore.mdx @@ -11,10 +11,10 @@ Manually restore data for a Vault cluster leader node with a saved snapshot. ## Before you start -- **You must a working knowledge of how Vault saves data**. -- **You must have a valid Vault cluster configuration using integratd storage**. +- **You must have a working knowledge of how Vault saves data**. +- **You must have a valid Vault cluster configuration using integrated storage**. - **You must know, and be able to contact your unseal/recovery key holders**. In - addition to the new root token generated during reinitalization, you need the + addition to the new root token generated during reinitialization, you need the original cluster unseal keys to unseal Vault after restoring the snapshot. - **You must have permission to access encrypted data in backed storage**. @@ -114,7 +114,7 @@ $ curl \ Have each person with an unseal key share run `vault operator unseal` with their original unseal -key until reaching the number of key shares required by your origial quroum +key until reaching the number of key shares required by your original quorum configuration to unseal your Vault cluster: @@ -138,7 +138,7 @@ Unseal Key (will be hidden): Have each person with an unseal key share run [`v1/sys/unseal`](/vault/api-docs/system/unseal) with their original unseal -key until reaching the number of key shares required by your origial quorum +key until reaching the number of key shares required by your original quorum configuration to unseal your Vault cluster: ```shell-session diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/save.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/save.mdx index 05660d69af..23eb37c056 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/save.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/save.mdx @@ -21,8 +21,8 @@ tutorial to learn how you can automate your upgrades with autopilot. ## Before you start -- **You must a working knowledge of how Vault saves data**. -- **You must have a valid Vault cluster configuration using integratd storage**. +- **You must have a working knowledge of how Vault saves data**. +- **You must have a valid Vault cluster configuration using integrated storage**. - **You must know, and be able to contact your unseal/recovery key holders**. - **You must have permission to access encrypted data in backed storage**. - **You should have a secure location, away from your Vault cluster @@ -71,7 +71,7 @@ $ curl \ ## Save a DR replication cluster snapshot -Take a snapshot of a cluster participating in disater recovery replication. +Take a snapshot of a cluster participating in disaster recovery replication. diff --git a/content/vault/v1.21.x (rc)/content/docs/upgrade/lts-upgrade.mdx b/content/vault/v1.21.x (rc)/content/docs/updates/lts-tracker.mdx similarity index 79% rename from content/vault/v1.21.x (rc)/content/docs/upgrade/lts-upgrade.mdx rename to content/vault/v1.21.x (rc)/content/docs/updates/lts-tracker.mdx index f4d5464b22..b5f0b27ab5 100644 --- a/content/vault/v1.21.x (rc)/content/docs/upgrade/lts-upgrade.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/updates/lts-tracker.mdx @@ -1,11 +1,11 @@ --- layout: docs -page_title: LTS Vault upgrades +page_title: LTS Vault change tracker description: >- - General guidance for LTS upgrades + General guidance and important changes at a glance for LTS upgrades --- -# Long-term support Vault upgrades +# LTS Vault change tracker [Long-term support](/vault/docs/enterprise/) offers extended maintenance through minor releases for select, major Vault Enterprise versions. @@ -23,7 +23,7 @@ Functional changes affect how Vault works including new requirements, new defaults, new behavior, and breaking changes. In some cases, we recommend specific actions before or after upgrading to mitigate the impact of a functional change. -Unresolved nown issues may have suggested workarounds or mitagation stratagies +Unresolved nown issues may have suggested workarounds or mitagation strategies you should consider before upgrading. -@include 'release-notes/change-summary/lts/1_16-to-1_19.mdx' +@include '../../../global/partials/important-changes/summary-tables/lts/1_16-to-1_19.mdx' diff --git a/content/vault/v1.21.x (rc)/content/partials/alerts/beta.mdx b/content/vault/v1.21.x (rc)/content/partials/alerts/beta.mdx index 9075f50bca..8e0c93b87d 100644 --- a/content/vault/v1.21.x (rc)/content/partials/alerts/beta.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/alerts/beta.mdx @@ -1,6 +1,6 @@ Beta functionality is stable but possibly incomplete and subject to change. - **We strongly discourage using beta features in production deployments of Vault** + **We strongly discourage using beta features in production deployments of Vault.** \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/partials/cli/audit/args/file/mode.mdx b/content/vault/v1.21.x (rc)/content/partials/cli/audit/args/file/mode.mdx index d285751b46..f8cf60f2b0 100644 --- a/content/vault/v1.21.x (rc)/content/partials/cli/audit/args/file/mode.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/cli/audit/args/file/mode.mdx @@ -3,7 +3,8 @@ **`mode (string : "0600")`** The `chmod`-style octal permissions for the audit file. Set `mode` to "0000" to -prevent Vault from modifying the file mode. +prevent Vault from modifying the file mode. File audit devices cannot use file +modes with executable permissions (e.g., 0777, 0755). -**Example**: `mode="0755"` +**Example**: `mode="0644"` diff --git a/content/vault/v1.21.x (rc)/content/partials/global-settings/both/client-cert.mdx b/content/vault/v1.21.x (rc)/content/partials/global-settings/both/client-cert.mdx index 049d484623..0d35f29382 100644 --- a/content/vault/v1.21.x (rc)/content/partials/global-settings/both/client-cert.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/global-settings/both/client-cert.mdx @@ -4,7 +4,7 @@ Path to a PEM-encoded CA certificate file on the local disk. Used for TLS communication with the server. **The specified certificate must match to the -private key specified with `-client-cert`**. +private key specified with `-client-key`**. **Examples**: diff --git a/content/vault/v1.21.x (rc)/content/partials/kubernetes-supported-versions.mdx b/content/vault/v1.21.x (rc)/content/partials/kubernetes-supported-versions.mdx index 37efe4b033..ff2de18675 100644 --- a/content/vault/v1.21.x (rc)/content/partials/kubernetes-supported-versions.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/kubernetes-supported-versions.mdx @@ -4,10 +4,10 @@ The following [Kubernetes minor releases][k8s-releases] are currently supported. The latest version is tested against each Kubernetes version. It may work with other versions of Kubernetes, but those are not supported. +* 1.33 * 1.32 * 1.31 * 1.30 * 1.29 -* 1.28 [k8s-releases]: https://kubernetes.io/releases/ diff --git a/content/vault/v1.21.x (rc)/content/partials/rotation-manager-logging.mdx b/content/vault/v1.21.x (rc)/content/partials/rotation-manager-logging.mdx new file mode 100644 index 0000000000..75c26c62b3 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/rotation-manager-logging.mdx @@ -0,0 +1,12 @@ +### Rotation logging + +The rotation manager emits logs to the standard `vault.log` on any successful or +failed rotation. + +In the case of success, Vault notes: + +- the rotated credential as the first parameter, `rotationID`. +- the anticipated time of the next rotation as `expire_time`. + +In the case of failure, Vault sets `rotationID` to `err` and may emit additional +logs depending on the configured log level. diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/disabled-mount-warning.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/disabled-mount-warning.mdx index 768709dd0f..7bee52a261 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/disabled-mount-warning.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/disabled-mount-warning.mdx @@ -1,9 +1,9 @@ You cannot read, list, or recover information from a snapshot for disabled - mount paths. Even if you reenable the same plugin at the same path, Vault + mount paths. Even if you re-enable the same plugin at the same path, Vault treats it as a new mount with different internal identifiers and cannot - associate the reenabled mount with the underlying storage entries within the + associate the re-enabled mount with the underlying storage entries within the snapshot. diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/load-snapshot/api/auto.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/load-snapshot/api/auto.mdx index 8a457e5a9c..084a86a74a 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/load-snapshot/api/auto.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/load-snapshot/api/auto.mdx @@ -1,4 +1,4 @@ -Use the `/sys/storage/raft/snapshot-load` endpoint with the snapshot +Use the `/sys/storage/raft/snapshot-auto/snapshot-load` endpoint with the snapshot configuration name and cloud storage URL to load a snapshot file and assign a snapshot ID: @@ -7,7 +7,7 @@ $ curl \ --request POST \ --header "X-Vault-Token: ${VAULT_TOKEN}" \ --data '{"url": ""}' \ - ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load/ + ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/snapshot-load/ ``` For example: @@ -19,7 +19,7 @@ $ curl \ --request POST \ --header "X-Vault-Token: ${VAULT_TOKEN}" \ --data '{"url": "https://bucket.example.com/vault-snapshots/primary/paris-backup.snap"}' \ - ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load/paris-primary | jq + ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/snapshot-load/paris-primary | jq { "data": { diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-requirements/load-snapshots.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-requirements/load-snapshots.mdx index 4c84229b65..ef7a582859 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-requirements/load-snapshots.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-requirements/load-snapshots.mdx @@ -1,10 +1,8 @@ - **You must have an integrated storage snapshot**. You can only restore data - from [automatically](/vault/docs/sysadmin/snapshots/automat) or + from [automatically](/vault/docs/sysadmin/snapshots/automate) or [manually](/vault/docs/sysadmin/snapshots/save) saved snapshots for integrated storage. - **You must have a snapshot from the cluster targeted for restoration**. -- **You must have access to the unseal keys, or the people with unseal keys, for - the target cluster** - **The cluster must have [mlock](/vault/docs/configuration#disable_mlock) disabled**. -- **The cluster cannot have anoter snapshot loaded**. +- **The cluster cannot have another snapshot loaded**. diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-secret-support.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-secret-support.mdx index a15afddbb4..b7908024ab 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-secret-support.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-secret-support.mdx @@ -1,6 +1,7 @@ -| Plugin | Path | Supported snapshot operations | Vault version | -|-----------|----------------------------|-------------------------------|---------------| -| cubbyhole | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 | -| kv (v1) | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 | -| databases | `/static-roles/:role_name` | `recover`, `read`, `list` | 1.20.4 | -| databases | `/static-creds/:role_name` | `read` | 1.20.4 | \ No newline at end of file +| Plugin | Path | Supported snapshot operations | Min Vault version +|-----------|----------------------------|-------------------------------|------------------ +| cubbyhole | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 +| kv (v1) | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 +| ssh | `/config/ca` | `recover`, `read` | 1.20.3 +| databases | `/static-roles/:role_name` | `recover`, `read`, `list` | 1.20.4 +| databases | `/static-creds/:role_name` | `read` | 1.20.4 \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/api.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/api.mdx index 80f6c4ee68..e8b74dccc3 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/api.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/api.mdx @@ -1,9 +1,10 @@ - -In the following examples, we set the HTTP method to `RECOVER`. Vault also supports -using the `PUT` or `POST` HTTP method for recover operations. If the request contains -the `X-Vault-Recover-Snapshot-Id` header, then Vault will treat the request as a -recover operation. - + + +If you cannot use the explicit `RECOVER` HTTP method, you can also use `PUT` or +`POST` for recover operations if you include the `X-Vault-Recover-Snapshot-Id` +header and set it to the relevant snapshot ID. + + Use the `X-Vault-Recover-Snapshot-Id` header and the snapshot ID to read from the secret path and write the recovered data to the corresponding mount path on diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/verify/api.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/verify/api.mdx index e00a2c66a2..fb9f2f29a8 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/verify/api.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/verify/api.mdx @@ -1,6 +1,6 @@ To verify secret recovery, read the secret from the expected path. For example, -if you recovered secrets at `telemetry-systems/api-key` from a key/value plugin -mounted at the default path, call the `/kv/data/{secret_path}` endpoint: +if you recovered secrets at `telemetry-systems/api-key` from a key/value version +1 plugin mounted at the default path, call the `/kv/{secret_path}` endpoint: ```shell-session $ curl \ diff --git a/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/fsm/saturation.mdx b/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/fsm/saturation.mdx new file mode 100644 index 0000000000..64d3451bdf --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/fsm/saturation.mdx @@ -0,0 +1,8 @@ +### vault.raft.thread.fsm.saturation ((#vault-raft-thread-fsm-saturation)) + +Metric type | Value | Description +----------- | ----------- | ----------- +gauge | percentage | Approximate proportion of time the raft FSM goroutine could not accept new work + +High saturation of the raft goroutines can increase latency in the rest of the +system and cause cluster instability. \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/main/saturation.mdx b/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/main/saturation.mdx new file mode 100644 index 0000000000..7a00edefcb --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/main/saturation.mdx @@ -0,0 +1,8 @@ +### vault.raft.thread.main.saturation ((#vault-raft-thread-main-saturation)) + +Metric type | Value | Description +----------- | ----------- | ----------- +gauge | percentage | Approximate proportion of time the main raft goroutine could not accept new work + +High saturation of the raft goroutines can increase latency in the rest of the +system and cause cluster instability. \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/partials/vso/common-links.mdx b/content/vault/v1.21.x (rc)/content/partials/vso/common-links.mdx index bc034f392a..71813b46ba 100644 --- a/content/vault/v1.21.x (rc)/content/partials/vso/common-links.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/vso/common-links.mdx @@ -1,4 +1,6 @@ [va-spec]: /vault/docs/platform/k8s/vso/api-reference#vaultauthspec [vag-spec]: /vault/docs/platform/k8s/vso/api-reference#vaultauthglobalspec +[kv-spec]: /vault/docs/platform/k8s/vso/api-reference#vaultstaticsecret +[dyn-spec]: /vault/docs/platform/k8s/vso/api-reference#vaultdynamicsecret [helm]: /vault/docs/platform/k8s/vso/helm [auth]: /vault/docs/platform/k8s/vso/sources/vault/auth diff --git a/content/vault/v1.21.x (rc)/data/docs-nav-data.json b/content/vault/v1.21.x (rc)/data/docs-nav-data.json index dc41d673cd..74eaa97ea9 100644 --- a/content/vault/v1.21.x (rc)/data/docs-nav-data.json +++ b/content/vault/v1.21.x (rc)/data/docs-nav-data.json @@ -289,13 +289,17 @@ "title": "Deprecation notices", "path": "updates/deprecation" }, + { + "title": "LTS Vault tracker", + "path": "updates/lts-tracker" + }, { "title": "Change tracker", "path": "updates/change-tracker" }, { "title": "Full changelog", - "href": "https://raw.githubusercontent.com/hashicorp/vault/refs/heads/main/CHANGELOG.md" + "href": "https://github.com/hashicorp/vault/blob/main/CHANGELOG.md" } ] }, @@ -731,14 +735,6 @@ "title": "Overview", "path": "deploy/kubernetes" }, - { - "title": "Agent Injector vs. Vault CSI Provider", - "path": "deploy/kubernetes/injector-csi" - }, - { - "title": "Migrate Consul to Raft storage", - "path": "deploy/kubernetes/consul-to-raft" - }, { "title": "Helm Chart", "routes": [ @@ -834,46 +830,8 @@ ] }, { - "title": "Agent Injector", - "routes": [ - { - "title": "Overview", - "path": "deploy/kubernetes/injector" - }, - { - "title": "Annotations", - "path": "deploy/kubernetes/injector/annotations" - }, - { - "title": "Installation", - "path": "deploy/kubernetes/injector/installation" - }, - { - "title": "Examples", - "path": "deploy/kubernetes/injector/examples" - } - ] - }, - { - "title": "Vault CSI Provider", - "routes": [ - { - "title": "Overview", - "path": "deploy/kubernetes/csi" - }, - { - "title": "Installation", - "path": "deploy/kubernetes/csi/installation" - }, - { - "title": "Configurations", - "path": "deploy/kubernetes/csi/configurations" - }, - { - "title": "Examples", - "path": "deploy/kubernetes/csi/examples" - } - ] + "title": "Integrations comparison", + "path": "deploy/kubernetes/comparisons" }, { "title": "Vault Secrets Operator", @@ -941,6 +899,24 @@ "title": "Helm Chart", "path": "deploy/kubernetes/vso/helm" }, + { + "title": "Use VSO with CSI", + "badge": { + "text": "ENT", + "type": "filled", + "color": "neutral" + }, + "routes": [ + { + "title": "Overview", + "path": "deploy/kubernetes/vso/csi" + }, + { + "title": "Setup", + "path": "deploy/kubernetes/vso/csi/setup" + } + ] + }, { "title": "Examples", "path": "deploy/kubernetes/vso/examples" @@ -958,6 +934,52 @@ "path": "deploy/kubernetes/vso/openshift" } ] + }, + { + "title": "Vault Secrets Store CSI provider", + "routes": [ + { + "title": "Overview", + "path": "deploy/kubernetes/csi" + }, + { + "title": "Installation", + "path": "deploy/kubernetes/csi/installation" + }, + { + "title": "Configuration", + "path": "deploy/kubernetes/csi/configurations" + }, + { + "title": "Examples", + "path": "deploy/kubernetes/csi/examples" + } + ] + }, + { + "title": "Vault Agent Injector", + "routes": [ + { + "title": "Overview", + "path": "deploy/kubernetes/injector" + }, + { + "title": "Annotations", + "path": "deploy/kubernetes/injector/annotations" + }, + { + "title": "Installation", + "path": "deploy/kubernetes/injector/installation" + }, + { + "title": "Examples", + "path": "deploy/kubernetes/injector/examples" + } + ] + }, + { + "title": "Migrate Consul to Raft storage", + "path": "deploy/kubernetes/consul-to-raft" } ] } @@ -978,10 +1000,6 @@ "title": "Manual upgrade for HA deployments", "path": "upgrade/vault-ha-upgrade" }, - { - "title": "LTS Vault upgrades", - "path": "upgrade/lts-upgrade" - }, { "title": "Rollback an upgrade", "path": "upgrade/rollback" @@ -1946,6 +1964,36 @@ } ] }, + { + "title": "Vault MCP Server", + "badge": { + "text": "BETA", + "type": "outlined", + "color": "highlight" + }, + "routes": [ + { + "title": "Overview", + "path": "mcp-server/overview" + }, + { + "title": "Deploy server", + "path": "mcp-server/deploy" + }, + { + "title": "Prompt model", + "path": "mcp-server/prompt-model" + }, + { + "title": "Reference", + "path": "mcp-server/reference" + }, + { + "title": "Security model", + "path": "mcp-server/security-model" + } + ] + }, { "divider": true }, @@ -2670,12 +2718,20 @@ ] }, { - "title": "Audit Devices", + "title": "Audit logging", "routes": [ { "title": "Overview", "path": "audit" }, + { + "title": "Auditing schema", + "path": "audit/schema" + }, + { + "title": "Best practices", + "path": "audit/best-practices" + }, { "title": "File", "path": "audit/file" @@ -3062,4 +3118,4 @@ "title": "Glossary", "path": "glossary" } -] +] \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/img/vault-client-workflows.png b/content/vault/v1.21.x (rc)/img/vault-client-workflows.png new file mode 100755 index 0000000000..180cffe286 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/vault-client-workflows.png differ diff --git a/content/vault/v1.21.x (rc)/img/vault-clients.png b/content/vault/v1.21.x (rc)/img/vault-clients.png new file mode 100755 index 0000000000..670f87f39d Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/vault-clients.png differ diff --git a/content/vault/v1.21.x (rc)/img/vso_csi_secrets_flow.png b/content/vault/v1.21.x (rc)/img/vso_csi_secrets_flow.png new file mode 100644 index 0000000000..90de81dcac Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/vso_csi_secrets_flow.png differ diff --git a/content/vault/v1.21.x (rc)/img/vso_secrets_flow.png b/content/vault/v1.21.x (rc)/img/vso_secrets_flow.png new file mode 100644 index 0000000000..c574142a84 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/vso_secrets_flow.png differ diff --git a/content/vault/v1.21.x (rc)/redirects.jsonc b/content/vault/v1.21.x (rc)/redirects.jsonc index a36b2cb975..750b21d7a6 100644 --- a/content/vault/v1.21.x (rc)/redirects.jsonc +++ b/content/vault/v1.21.x (rc)/redirects.jsonc @@ -1,92 +1,94 @@ /** * Copyright (c) HashiCorp, Inc. * SPDX-License-Identifier: BUSL-1.1 - */ + * + * Refer to the redirect docs for examples and regex information: + * + * https://github.com/hashicorp/web-unified-docs/blob/main/docs/redirects.md + **/ + [ - // example redirect: - // { - // "source": "/vault/docs/some/path", - // "destination": "/vault/docs/some/other/path", - // "permanent": true, - // }, + /***************************************************************************** + * Pre-2023 redirects + *****************************************************************************/ + { "source": "/vault/docs/plugins/plugin-portal", "destination": "/vault/integrations", "permanent": true }, + + + /***************************************************************************** + * ~2023 IA update: Combine agent and new proxy docs under /docs/agent-and-proxy + *****************************************************************************/ + + // Redirect from deleted overview to first available method { "source": "/vault/docs/agent-and-proxy/autoauth/methods", "destination": "/vault/docs/agent-and-proxy/autoauth/methods/alicloud", "permanent": true }, + + // Redirect /agent/autoauth/* paths to /agent-and-proxy/autoauth/* { - "source": "/vault/docs/agent/autoauth/:slug(.*)", - "destination": "/vault/docs/agent-and-proxy/autoauth/:slug", - "permanent": true - }, - { - "source": "/vault/docs/agent/template", - "destination": "/vault/docs/agent-and-proxy/agent/template", - "permanent": true - }, - { - "source": "/vault/docs/agent/winsvc", - "destination": "/vault/docs/agent-and-proxy/agent/winsvc", + "source": "/vault/docs/agent/autoauth/:slug*", + "destination": "/vault/docs/agent-and-proxy/autoauth/:slug*", "permanent": true }, + + // Redirect the other docs/agent/* paths to /agent-and-proxy/agent/* { - "source": "/vault/docs/agent/versions", - "destination": "/vault/docs/agent-and-proxy/agent/versions", - "permanent": true - }, - { - "source": "/vault/docs/agent/apiproxy", - "destination": "/vault/docs/agent-and-proxy/agent/apiproxy", - "permanent": true - }, - { - "source": "/vault/docs/agent", - "destination": "/vault/docs/agent-and-proxy/agent", - "permanent": true - }, - { - "source": "/vault/docs/agent/caching", - "destination": "/vault/docs/agent-and-proxy/agent/caching", - "permanent": true - }, - { - "source": "/vault/docs/agent/caching/:slug(.*)", - "destination": "/vault/docs/agent-and-proxy/agent/caching/:slug", - "permanent": true - }, - { - "source": "/vault/docs/:version(v1\\.(?:4|5|6|7|8|9|10|11|12|13)\\.x)/agent-and-proxy/agent", - "destination": "/vault/docs/:version/agent/", - "permanent": true - }, - { - "source": "/vault/docs/:version(v1\\.(?:4|5|6|7|8|9|10|11|12|13)\\.x)/agent-and-proxy/agent/template", - "destination": "/vault/docs/:version/agent/template", + "source": "/vault/docs/agent/:slug((?!autoauth$).*)", + "destination": "/vault/docs/agent-and-proxy/agent/:slug", "permanent": true }, + + /** + Backfacing redirects for agent-and-proxy/autoauth/* to legacy URLs + + - Source: {version}/agent-and-proxy/autoauth/* (new URL) + Target: {version}/agent/autoauth/* + Range: 1.4.x through 1.13.x + **/ { - "source": "/vault/docs/:version(v1\\.(?:4|5|6|7|8|9|10|11|12|13)\\.x)/agent-and-proxy/agent/caching", - "destination": "/vault/docs/:version/agent/caching", + "source": "/vault/docs/:version(v1\\.(?:[4-9]|1[0-3])\\.x)/agent-and-proxy/autoauth/:slug*", + "destination": "/vault/docs/:version/agent/autoauth/:slug*", "permanent": true }, + + /** + Backfacing redirects for agent-and-proxy/agent/* to legacy URLs + + - Source: {version}/agent-and-proxy/proxy/apiproxy (new URL) + Target: {version}/agent/apiproxy + Range: 1.4.x - 1.13.x + - Source: {version}/agent-and-proxy/agent/* (new URL) + Target: {version}/agent/* + Range: 1.4.x - 1.13.x + - Source: {version}/agent-and-proxy/agent/caching/* (new URL) + Target: {version}/agent/* + Range: 1.8.x - 1.13.x + - Source: {version}/agent-and-proxy/agent/winsvc (new URL) + Target: {version}/agent/winsvc + Range: 1.7.x - 1.13.x + - Source: {version}/agent-and-proxy/agent/generate-config (new URL) + Target: {version}/agent/template-config + Range: 1.8.x - 1.9.x + **/ { - "source": "/vault/docs/:version(v1\\.(?:4|5|6|7|8|9|10|11|12|13)\\.x)/agent-and-proxy/autoauth/:slug(.*)", - "destination": "/vault/docs/:version/agent/autoauth/:slug", + "source": "/vault/docs/:version(v1\\.(?:[4-9]|1[0-3])\\.x)/agent-and-proxy/agent/:slug((?!autoauth$|caching$|winsvc$|generate-config$).*)", + "destination": "/vault/docs/:version/agent/:slug", "permanent": true }, { - "source": "/vault/docs/:version(v1\\.(?:8|9|10|11|12|13)\\.x)/agent-and-proxy/agent/caching/:slug(.*)", - "destination": "/vault/docs/:version/agent/caching/:slug", + "source": "/vault/docs/:version(v1\\.(?:8|9|1[0-3])\\.x)/agent-and-proxy/agent/caching/:slug*", + "destination": "/vault/docs/:version/agent/caching/:slug*", "permanent": true }, { - "source": "/vault/docs/:version(v1\\.(?:7|8|9|10|11|12|13)\\.x)/agent-and-proxy/agent/winsvc", + "source": "/vault/docs/:version(v1\\.(?:[7-9]|1[0-3])\\.x)/agent-and-proxy/agent/winsvc", "destination": "/vault/docs/:version/agent/winsvc", "permanent": true }, @@ -95,21 +97,35 @@ "destination": "/vault/docs/:version/agent/template-config", "permanent": true }, + + + /***************************************************************************** + 2024 | Active Directory plugin EOL + *****************************************************************************/ + + // Redirect AD guides to the replacement plugin (LDAP) { - "source": "/vault/docs/v1.13.x/agent-and-proxy/agent/versions", - "destination": "/vault/docs/v1.13.x/agent/versions", + "source": "/vault/api-docs/secret/ad", + "destination": "/vault/api-docs/secret/ldap", "permanent": true }, { - "source": "/vault/docs/v1.13.x/agent-and-proxy/agent/apiproxy", - "destination": "/vault/docs/v1.13.x/agent/apiproxy", + "source": "/vault/docs/secrets/ad", + "destination": "/vault/docs/secrets/ldap", "permanent": true }, + + // Redirect the AD migration guide to the last supported version { - "source": "/vault/api-docs/system/plugins-reload-backend", - "destination": "/vault/api-docs/system/plugins-reload", + "source": "/vault/docs/secrets/ad/migration-guide", + "destination": "/vault/docs/v1.18.x/secrets/ad/migration-guide", "permanent": true }, + + + /***************************************************************************** + 2024-2025 | IA update: Deprecation redirects + *****************************************************************************/ { "source": "/vault/docs/deprecation/faq", "destination": "/vault/docs/deprecation", @@ -120,36 +136,34 @@ "destination": "/vault/docs/updates/deprecation", "permanent": true }, + + + + /***************************************************************************** + 2024-2025 | IA update: CLI content refresh + *****************************************************************************/ { - "source": "/vault/docs/concepts/lease-explosions", - "destination": "/vault/docs/configuration/prevent-lease-explosions", - "permanent": true - }, - { - "source": "/vault/docs/troubleshoot/lease-explosions", - "destination": "/vault/docs/configuration/prevent-lease-explosions", - "permanent": true - }, - { - "source": "/vault/docs/concepts/lease-count-quota-exceeded", - "destination": "/vault/docs/troubleshoot/lease-count-quota-exceeded", + "source": "/vault/api-docs/system/plugins-reload-backend", + "destination": "/vault/api-docs/system/plugins-reload", "permanent": true }, { - "source": "/vault/docs/command/web", + "source": "/vault/docs/commands/web", "destination": "/vault/docs/ui/web-cli", "permanent": true }, { - "source": "/vault/docs/:version(v1\\.(?:8|9)\\.x)/agent-and-proxy/agent/generate-config", - "destination": "/vault/docs/:version/agent/template-config", - "permanent": true - }, - { - "source": "/vault/docs/faq/ssct", - "destination": "/vault/docs/v1.10.x/faq/ssct", + "source": "/vault/docs/commands/hcp", + "destination": "/vault/docs/commands/hcp/connect", "permanent": true }, + + + /***************************************************************************** + 2025 | IA update: Upgrade guides + *****************************************************************************/ + + // Standard redirects { "source": "/vault/docs/upgrading", "destination": "/vault/docs/upgrade", @@ -171,60 +185,154 @@ "permanent": true }, { - "source": "/vault/docs/upgrading/deduplication/:slug(.*)", - "destination": "/vault/docs/secrets/identity/deduplication/:slug", + "source": "/vault/docs/upgrading/deduplication/:slug*", + "destination": "/vault/docs/secrets/identity/deduplication/:slug*", "permanent": true }, + + /** + Versioned redirects for /upgrading/upgrade-to-{version} to versioned URLs + + NOTE: Before v1.9, the upgrade guide for version X of Vault was published + under version X+1 of the docs and every patch update had its own upgrade + guide. For simplicity, we redirect version-specific upgrade guides prior to + 1.9 to the versioned instance of that guide under the 1.9.x docs + + - Source: /upgrading/upgrade-to-{version}.{patch} + Target: v1.9.x/upgrading/upgrade-to-{version}.{patch} + Range: 0.5.* - 0.11.*, 1.0.* - 1.8.* (page name) + - Source: /upgrading/upgrade-to-{version}.x + Target: {version}.x/upgrading/upgrade-to-{version}.x + Range: 1.9.x - 1.18.x + - Source: /upgrading/upgrade-to-19.x + Target: v1.19.x/updates/important-changes + Range: 1.19.x + **/ + + // Redirect 0.5.* through 0.11.* guides to their v1.9.x instance { - "source": "/vault/docs/upgrading/upgrade-to-:version(0\\.(?:5|6|7|8|9|10|11)).:patch(.*)", + "source": "/vault/docs/upgrading/upgrade-to-:version(0\\.(?:[5-9]|10|11)).:patch(.*)", "destination": "/vault/docs/v1.9.x/upgrading/upgrade-to-:version.:patch", "permanent": true }, + // Redirect 1.0.* through 1.8.* guides to their v1.9.x instance { - "source": "/vault/docs/upgrading/upgrade-to-:version(1\\.(?:0|1|2|3|4|5|6|7|8)).:patch(.*)", + "source": "/vault/docs/upgrading/upgrade-to-:version(1\\.(?:[0-8])).:patch(.*)", "destination": "/vault/docs/v1.9.x/upgrading/upgrade-to-:version.:patch", "permanent": true }, + // Redirect 1.9.x through 1.18.x guides to the instance under the corresponding + // docset version { - "source": "/vault/docs/upgrading/upgrade-to-:version(1\\.(?:9|10|11|12|13|14|15|16|17|18)\\.x)", + "source": "/vault/docs/upgrading/upgrade-to-:version(1\\.(?:9|1[0-8])\\.x)", "destination": "/vault/docs/v:version/upgrading/upgrade-to-:version", "permanent": true }, + // The URL changed with version 1.19.x { "source": "/vault/docs/upgrading/upgrade-to-1.19.x", "destination": "/vault/docs/v1.19.x/updates/important-changes", "permanent": true }, - { - "source": "/vault/docs/v:version(1\\.(?:9|10|11|12|13|14|15|16|17|18)\\.x)/updates/important-changes", + + /** + Backfacing redirects for /updates/important-changes to legacy URLs + + - Source: {version}/updates/important-changes (new URL) + Target: {version}/upgrading/upgrade-to-{version} + Range: 1.9.x through 1.18.x + **/ + { + "source": "/vault/docs/v:version(1\\.(?:9|1[0-8])\\.x)/updates/important-changes", "destination": "/vault/docs/v:version/upgrading/upgrade-to-:version", "permanent": true }, + + + /***************************************************************************** + 2025 | IA update - Relase notes + *****************************************************************************/ + + /** + Versioned redirects for /release-notes/{version}.{patch} to versioned URLs + + NOTE: Release notes started with 1.5.0 and before v1.9, the release notes + for version X of Vault was published under version X+1 of the docs. For + simplicity, we redirect version-specific release notes from 1.5 through to + 1.9 to the versioned instance of that guide under the 1.9.x docs + + - Source: /release-notes/{version}.{patch} + Target: v1.9.x/release-notes/{version}.{patch} + Range: 1.5.x - 1.8.x + - Source: /release-notes/{version}.{patch} + Target: {version}.x/release-notes/{version}.{patch} + Range: 1.9.x - 1.18.x + - Source: /upgrading/upgrade-to-19.x + Target: v1.19.x/release-notes/1.19.0 + Range: 1.19.x + **/ + + // Redirect 1.5.0 through 1.8.0 guides to their v1.9.x instance + { + "source": "/vault/docs/release-notes/:version(1\\.[5-8]).:patch(.*)", + "destination": "/vault/docs/v1.9.x/release-notes/:version.:patch", + "permanent": true + }, + + // Redirect the guides for 1.9.0 through 1.18.0 to the instance under the + // corresponding docset version { - "source": "/vault/docs/release-notes/1.19.0", - "destination": "/vault/docs/v1.19.x/updates/release-notes", + "source": "/vault/docs/release-notes/:version(1\\.(?:9|1[0-8])).:patch(.*)", + "destination": "/vault/docs/v:version.x/release-notes/:version.:patch", "permanent": true }, + + // The URL changed with version 1.19.x { - "source": "/vault/docs/v:version(1\\.(?:4|5|6|7|8|9|10|11|12|13|14|15|17|18)).x/updates/release-notes", - "destination": "/vault/docs/v:version.x/release-notes/:version.0", + "source": "/vault/docs/release-notes/1.19.0", + "destination": "/vault/docs/v1.19.x/updates/release-notes", "permanent": true }, + + /** + Backfacing redirects for /updates/release-notes to legacy URLs + + - Source: {version}.x/updates/release-notes (new URL) + Target: 1.9.x/release-notes/{version}.0 + Range: 1.5 through 1.9 (1.4 does not have release notes) + - Source: {version}.x/updates/release-notes (new URL) + Target: {version}.x/release-notes/{version}.0 + Range: 1.10 through 1.18.x, except 1.16.x + - Source: 1.16.x/updates/release-notes (new URL) + Target: 1.16.x/release-notes/1.16.1 + Range: 1.16 only (1.16.x GAed with 1.16.1 instead of 1.16.0) + **/ + + // Redirect 1.4.x through 1.9.x to the v1.9.x version of the old URL { - "source": "/vault/docs/v1.16.x/updates/release-notes", - "destination": "/vault/docs/v1.16.x/release-notes/1.16.1", + "source": "/vault/docs/v:version(1\\.[5-9]).x/updates/release-notes", + "destination": "/vault/docs/v1.9.x/release-notes/:version.0", "permanent": true }, + + // Redirect 1.10.x through 1.18.x, except 1.16.x { - "source": "/vault/docs/release-notes/:version(1\\.(?:4|5|6|7|8|9|10|11|12|13|14|15|17|18)).0", + "source": "/vault/docs/v:version(1\\.1(?:[0-5]|[7-8])).x/updates/release-notes", "destination": "/vault/docs/v:version.x/release-notes/:version.0", "permanent": true }, + + // Redirect 1.16.x separately since 1.16.x GAed with 1.16.1 instead of 1.16.0 { - "source": "/vault/docs/release-notes/1.16.1", + "source": "/vault/docs/v1.16.x/updates/release-notes", "destination": "/vault/docs/v1.16.x/release-notes/1.16.1", "permanent": true }, + + + /***************************************************************************** + 2025 | IA update - About Vault pages + *****************************************************************************/ { "source": "/vault/docs/what-is-vault", "destination": "/vault/docs/about-vault/what-is-vault", @@ -241,50 +349,83 @@ "permanent": true }, { - "source": "/vault/docs/v:version(1\\.(?:4|5|6|7|8|9|10|11|12|13|14|15|16|17|18)\\.x)/partners", - "destination": "/vault/docs/v:version/interoperability-matrix", + "source": "/vault/docs/partnerships", + "destination": "/vault/docs/partners/program", "permanent": true }, { - "source": "/vault/docs/partnerships", - "destination": "/vault/docs/partners/program", + "source": "/vault/docs/browser-support", + "destination": "/vault/docs/ui/browser-support", + "permanent": true + }, + + /** + Backfacing redirects for /partners to legacy URLs + + - Source: {version}/partners (new URL) + Target: {version}/interoperability-matrix + Range: 1.11 through 1.18 + **/ + { + "source": "/vault/docs/v:version(1\\.1[1-8]\\.x)/partners/:slug*", + "destination": "/vault/docs/v:version/interoperability-matrix", "permanent": true }, + + /***************************************************************************** + 2025 | IA update - Get Vault + Deploy Vault + *****************************************************************************/ { "source": "/vault/docs/run-as-service", "destination": "/vault/docs/deploy/run-as-service", "permanent": true }, { - "source": "/vault/docs/install/:slug(.*)", - "destination": "/vault/docs/get-vault/:slug", + "source": "/vault/docs/install/:slug*", + "destination": "/vault/docs/get-vault/:slug*", "permanent": true }, { - "source": "/vault/docs/platform/aws/:slug(.*)", - "destination": "/vault/docs/deploy/aws/:slug", + "source": "/vault/docs/platform/aws/:slug*", + "destination": "/vault/docs/deploy/aws/:slug*", "permanent": true }, { - "source": "/vault/docs/platform/k8s/:slug(.*)", - "destination": "/vault/docs/deploy/kubernetes/:slug", + "source": "/vault/docs/platform/k8s/:slug*", + "destination": "/vault/docs/deploy/kubernetes/:slug*", "permanent": true }, + + /** + Version-tracking redirects for defunct path: /platform/k8s/*: + + - Source: {version}/platform/k8s/* + Target: {version}/deploy/kybernetes/* + Range: 1.19.x onward + **/ { - "source": "/vault/api-docs/secret/ad", - "destination": "/vault/api-docs/secret/ldap", + "source": "/vault/docs/v:version(1\\.(?:19|2[0-9])\\.x)/platform/k8s/:slug*", + "destination": "/vault/docs/v:version/deploy/kubernetes/:slug*", "permanent": true }, + + /***************************************************************************** + 2025 | IA update - Leasing redirects + *****************************************************************************/ + + // Concept docs { - "source": "/vault/docs/secrets/ad", - "destination": "/vault/docs/secrets/ldap", + "source": "/vault/docs/concepts/lease-explosions", + "destination": "/vault/docs/configuration/prevent-lease-explosions", "permanent": true }, { - "source": "/vault/docs/secrets/ad/migration-guide", - "destination": "/vault/docs/v1.18.x/secrets/ad/migration-guide", + "source": "/vault/docs/concepts/lease-count-quota-exceeded", + "destination": "/vault/docs/troubleshoot/lease-count-quota-exceeded", "permanent": true }, + + // Enterprise docs { "source": "/vault/docs/enterprise/license", "destination": "/vault/docs/license", @@ -315,39 +456,96 @@ "destination": "/vault/docs/license", "permanent": true }, + + // Troubleshooting docs + { + "source": "/vault/docs/troubleshoot/lease-explosions", + "destination": "/vault/docs/configuration/prevent-lease-explosions", + "permanent": true + }, + + /***************************************************************************** + FAQ redirects + *****************************************************************************/ + { + "source": "/vault/docs/faq/ssct", + "destination": "/vault/docs/v1.10.x/faq/ssct", + "permanent": true + }, + + + /***************************************************************************** + 2025 | IA update - Sys admin redirects + *****************************************************************************/ + + // Redirect the enterprise/ and concepts/ URLs for snapshots to the new + // sysadmin/ folder { "source": "/vault/docs/enterprise/automated-integrated-storage-snapshots", "destination": "/vault/docs/sysadmin/snapshots/automation-overview", "permanent": true }, { - "source": "/vault/docs/v:version(1\\.(?:7|8|9|10|11|12|13|14|15|16|17|18|19)\\.x)/sysadmin/snapshots/automation-overview", + "source": "/vault/docs/concepts/integrated-storage/snapshot-recover", + "destination": "/vault/docs/sysadmin/snapshots/recover-a-secret", + "permanent": true + }, + + /** + Backfacing redirects: + + - Source: {version}/sysadmin/snapshots/automation-overview (new URL) + Target: {version}/enterprise/automated-integrated-storage-snapshots + Range: 1.7 through 1.19 + **/ + { + "source": "/vault/docs/v:version(1\\.(?:[7-9]|1[0-9])\\.x)/sysadmin/snapshots/automation-overview", "destination": "/vault/docs/v:version/enterprise/automated-integrated-storage-snapshots", "permanent": true }, + + /***************************************************************************** + 2025 | R&D - client count refresh + *****************************************************************************/ + { "source": "/vault/docs/concepts/client-count/usage-metrics", "destination": "/vault/docs/concepts/client-count/client-usage", "permanent": true }, + + /** + Backfacing redirects: + + - Source: {version}/concepts/client-count/client-usage (new URL) + Target: {version}/concepts/client-count/usage-metrics + Range: 1.18 and 1.19 + **/ { - "source": "/vault/docs/:version(v1\\.*\\.x)/v:ver(1\\.*\\.x)/:slug(.*)", - "destination": "/vault/docs/:version/:slug", - "permanent": true - }, - { - "source": "/vault/docs/commands/web", - "destination": "/vault/docs/ui/web-cli", + "source": "/vault/docs/:version(v1\\.1[8-9]\\.x)/concepts/client-count/client-usage", + "destination": "/vault/docs/:version/concepts/client-count/usage-metrics", "permanent": true }, + + /***************************************************************************** + N/A | One-off corrections/moves + *****************************************************************************/ + { - "source": "/vault/docs/browser-support", - "destination": "/vault/docs/ui/browser-support", + "source": "/vault/docs/upgrade/lts-upgrade", + "destination": "/vault/docs/updates/lts-tracker", "permanent": true }, + + + /***************************************************************************** + Temporary bandaids + *****************************************************************************/ + + // Corrected double-versioned URLs to just take the first version in the string { - "source": "/vault/docs/commands/hcp", - "destination": "/vault/docs/commands/hcp/connect", + "source": "/vault/docs/:version(v1\\.*\\.x)/v:ver(1\\.*\\.x)/:slug*", + "destination": "/vault/docs/:version/:slug*", "permanent": true } -] +] \ No newline at end of file