diff --git a/website/content/docs/secrets/kv/kv-v2.mdx b/website/content/docs/secrets/kv/kv-v2.mdx deleted file mode 100644 index 3c182ecf7326..000000000000 --- a/website/content/docs/secrets/kv/kv-v2.mdx +++ /dev/null @@ -1,630 +0,0 @@ ---- -layout: docs -page_title: KV - Secrets Engines -description: The KV secrets engine can store arbitrary secrets. ---- - -# KV secrets engine - version 2 - -The `kv` secrets engine is used to store arbitrary secrets within the -configured physical storage for Vault. - -Key names must always be strings. If you write non-string values directly via -the CLI, they will be converted into strings. However, you can preserve -non-string values by writing the key/value pairs to Vault from a JSON file or -using the HTTP API. - -This secrets engine honors the distinction between the `create` and `update` -capabilities inside ACL policies. The `patch` capability is also supported -which is used to represent partial updates whereas the `update` capability -represents full overwrites. - -## Setup - -Most secrets engines must be configured in advance before they can perform their -functions. These steps are usually completed by an operator or configuration -management tool. - -A v2 `kv` secrets engine can be enabled by: - -```shell-session -$ vault secrets enable -version=2 kv -``` - -Or, you can pass `kv-v2` as the secrets engine type: - -```shell-session -$ vault secrets enable kv-v2 -``` - -Additionally, when running a dev-mode server, the v2 `kv` secrets engine is enabled by default at the -path `secret/` (for non-dev servers, it is currently v1). It can be disabled, moved, or enabled multiple times at -different paths. Each instance of the KV secrets engine is isolated and unique. - -## Upgrading from version 1 - -An existing version 1 kv store can be upgraded to a version 2 kv store via the CLI or API, as shown below. This will start an upgrade process to upgrade the existing key/value data to a versioned format. The mount will be inaccessible during this process. This process could take a long time, so plan accordingly. - -Once upgraded to version 2, the former paths at which the data was accessible will no longer suffice. You will need to adjust user policies to add access to the version 2 paths as detailed in the [ACL Rules section below](/vault/docs/secrets/kv/kv-v2#acl-rules). Similarly, users/applications will need to update the paths at which they interact with the kv data once it has been upgraded to version 2. - -An existing version 1 kv can be upgraded to a version 2 KV store with the CLI command: - -```shell-session -$ vault kv enable-versioning secret/ -Success! Tuned the secrets engine at: secret/ -``` - -or via the API: - -```shell-session -$ cat payload.json -{ - "options": { - "version": "2" - } -} -``` - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - --data @payload.json \ - http://127.0.0.1:8200/v1/sys/mounts/secret/tune -``` - -## ACL rules - -The version 2 kv store uses a prefixed API, which is different from the -version 1 API. Before upgrading from a version 1 kv the ACL rules -should be changed. Also different paths in the version 2 API can be ACL'ed -differently. - -Writing and reading versions are prefixed with the `data/` path. This policy -that worked for the version 1 kv: - -```plaintext -path "secret/dev/team-1/*" { - capabilities = ["create", "update", "read"] -} -``` - -Should be changed to: - -```plaintext -path "secret/data/dev/team-1/*" { - capabilities = ["create", "update", "read"] -} -``` - -There are different levels of data deletion for this backend. To grant a policy -the permissions to delete the latest version of a key: - -```plaintext -path "secret/data/dev/team-1/*" { - capabilities = ["delete"] -} -``` - -To allow the policy to delete any version of a key: - -```plaintext -path "secret/delete/dev/team-1/*" { - capabilities = ["update"] -} -``` - -To allow a policy to undelete data: - -```plaintext -path "secret/undelete/dev/team-1/*" { - capabilities = ["update"] -} -``` - -To allow a policy to destroy versions: - -```plaintext -path "secret/destroy/dev/team-1/*" { - capabilities = ["update"] -} -``` - -To allow a policy to list keys: - -```plaintext -path "secret/metadata/dev/team-1/*" { - capabilities = ["list"] -} -``` - -To allow a policy to view metadata for each version: - -```plaintext -path "secret/metadata/dev/team-1/*" { - capabilities = ["read"] -} -``` - -To allow a policy to permanently remove all versions and metadata for a key: - -```plaintext -path "secret/metadata/dev/team-1/*" { - capabilities = ["delete"] -} -``` - -The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are -not supported for policies used with the version 2 kv store. See the [Policies Concepts](/vault/docs/concepts/policies) -for a description of these parameters. - -See the [API Specification](/vault/api-docs/secret/kv/kv-v2) for more -information. - -## Usage - -After the secrets engine is configured and a user/machine has a Vault token with -the proper permission, it can generate credentials. The `kv` secrets engine -allows for writing keys with arbitrary values. - -The path-like KV-v1 syntax for referencing a secret (`secret/foo`) can still -be used in KV-v2, but we recommend using the `-mount=secret` flag syntax to -avoid mistaking it for the actual path to the secret (`secret/data/foo` is the -real path). - -### Writing/Reading arbitrary data - -1. Write arbitrary data: - - ```shell-session - $ vault kv put -mount=secret my-secret foo=a bar=b - Key Value - --- ----- - created_time 2019-06-19T17:20:22.985303Z - custom_metadata - deletion_time n/a - destroyed false - version 1 - ``` - -1. Read arbitrary data: - - ```shell-session - $ vault kv get -mount=secret my-secret - ====== Metadata ====== - Key Value - --- ----- - created_time 2019-06-19T17:20:22.985303Z - custom_metadata - deletion_time n/a - destroyed false - version 1 - - ====== Data ====== - Key Value - --- ----- - foo a - bar b - ``` - -1. Write another version, the previous version will still be accessible. The - `-cas` flag can optionally be passed to perform a check-and-set operation. If - not set the write will be allowed. In order for a write to be successful, `cas` must be set to - the current version of the secret. If set to 0 a write will only be allowed if - the key doesn’t exist as unset keys do not have any version information. Also - remember that soft deletes do not remove any underlying version data from storage. - In order to write to a soft deleted key, the cas parameter must match the key's - current version. - - ```shell-session - $ vault kv put -mount=secret -cas=1 my-secret foo=aa bar=bb - Key Value - --- ----- - created_time 2019-06-19T17:22:23.369372Z - custom_metadata - deletion_time n/a - destroyed false - version 2 - ``` - -1. Reading now will return the newest version of the data: - - ```shell-session - $ vault kv get -mount=secret my-secret - ====== Metadata ====== - Key Value - --- ----- - created_time 2019-06-19T17:22:23.369372Z - custom_metadata - deletion_time n/a - destroyed false - version 2 - - ====== Data ====== - Key Value - --- ----- - foo aa - bar bb - ``` - -1. Partial updates can be accomplished using the `vault kv patch` command. A - command will initially attempt an HTTP `PATCH` request which requires the - `patch` ACL capability. The `PATCH` request will fail if the token used - is associated with a policy that does not contain the `patch` capability. In - this case the command will perform a read, local update, and subsequent write - which require both the `read` and `update` ACL capabilities. - - The `-cas` flag can optionally be passed to perform a check-and-set operation. - It will only be used in the case of the initial `PATCH` request. The - read-then-write flow will use the `version` value from the secret returned by - the read to perform a check-and-set operation in the subsequent write. - - ```shell-session - $ vault kv patch -mount=secret -cas=2 my-secret bar=bbb - Key Value - --- ----- - created_time 2019-06-19T17:23:49.199802Z - custom_metadata - deletion_time n/a - destroyed false - version 3 - ``` - -1. The `vault kv patch` command also supports a `-method` flag which can be - used to specify HTTP `PATCH` or read-then-write. The supported values are - `patch` and `rw` for HTTP `PATCH` and read-then-write, respectively. - - Perform a patch using the `patch` method: - - ```shell-session - $ vault kv patch -mount=secret -method=patch -cas=2 my-secret bar=bbb - Key Value - --- ----- - created_time 2019-06-19T17:23:49.199802Z - custom_metadata - deletion_time n/a - destroyed false - version 3 - ``` - - Perform a patch using the read-then-write method: - - ```shell-session - $ vault kv patch -mount=secret -method=rw my-secret bar=bbb - Key Value - --- ----- - created_time 2019-06-19T17:23:49.199802Z - custom_metadata - deletion_time n/a - destroyed false - version 3 - ``` - -2. Reading after a patch will return the newest version of the data in which - only the specified fields were updated: - - ```shell-session - $ vault kv get -mount=secret my-secret - ====== Metadata ====== - Key Value - --- ----- - created_time 2019-06-19T17:23:49.199802Z - custom_metadata - deletion_time n/a - destroyed false - version 3 - - ====== Data ====== - Key Value - --- ----- - foo aa - bar bbb - ``` - -3. Previous versions can be accessed with the `-version` flag: - - ```shell-session - $ vault kv get -mount=secret -version=1 my-secret - ====== Metadata ====== - Key Value - --- ----- - created_time 2019-06-19T17:20:22.985303Z - custom_metadata - deletion_time n/a - destroyed false - version 1 - - ====== Data ====== - Key Value - --- ----- - foo a - bar b - ``` - -You can also use [Vault's password policy](/vault/docs/concepts/password-policies) feature to generate arbitrary values. - -1. Write a password policy: - - ```shell-session - $ vault write sys/policies/password/example policy=-< - - ```plaintext - ========= Secret Path ========= - secret/data/my-generated-secret - - ======= Metadata ======= - Key Value - --- ----- - created_time 2023-05-10T14:32:32.37354939Z - custom_metadata - deletion_time n/a - destroyed false - version 1 - ``` - - - -1. Read the generated data: - - ```shell-session - $ vault kv get -mount=secret my-generated-secret - ========= Secret Path ========= - secret/data/my-generated-secret - - ======= Metadata ======= - Key Value - --- ----- - created_time 2023-05-10T14:32:32.37354939Z - custom_metadata - deletion_time n/a - destroyed false - version 1 - - ====== Data ====== - Key Value - --- ----- - password !hh&be1e4j16dVc0ggae - ``` - -### Deleting and destroying data - -When deleting data the standard `vault kv delete` command will perform a -soft delete. It will mark the version as deleted and populate a `deletion_time` -timestamp. Soft deletes do not remove the underlying version data from storage, -which allows the version to be undeleted. The `vault kv undelete` command -handles undeleting versions. - -A version's data is permanently deleted only when the key has more versions than -are allowed by the max-versions setting, or when using `vault kv destroy`. When -the destroy command is used the underlying version data will be removed and the -key metadata will be marked as destroyed. If a version is cleaned up by going -over max-versions the version metadata will also be removed from the key. - -See the commands below for more information: - -1. The latest version of a key can be deleted with the delete command, this also - takes a `-versions` flag to delete prior versions: - - ```shell-session - $ vault kv delete -mount=secret my-secret - Success! Data deleted (if it existed) at: secret/data/my-secret - ``` - -1. Versions can be undeleted: - - ```shell-session - $ vault kv undelete -mount=secret -versions=2 my-secret - Success! Data written to: secret/undelete/my-secret - - $ vault kv get -mount=secret my-secret - ====== Metadata ====== - Key Value - --- ----- - created_time 2019-06-19T17:23:21.834403Z - custom_metadata - deletion_time n/a - destroyed false - version 2 - - ====== Data ====== - Key Value - --- ----- - my-value short-lived-s3cr3t - ``` - -1. Destroying a version permanently deletes the underlying data: - - ```shell-session - $ vault kv destroy -mount=secret -versions=2 my-secret - Success! Data written to: secret/destroy/my-secret - ``` - -### Key metadata - -All versions and key metadata can be tracked with the metadata command & API. -Deleting the metadata key will cause all metadata and versions for that key to -be permanently removed. - -See the commands below for more information: - -1. All metadata and versions for a key can be viewed: - - ```shell-session - $ vault kv metadata get -mount=secret my-secret - ========== Metadata ========== - Key Value - --- ----- - cas_required false - created_time 2019-06-19T17:20:22.985303Z - current_version 2 - custom_metadata - delete_version_after 0s - max_versions 0 - oldest_version 0 - updated_time 2019-06-19T17:22:23.369372Z - - ====== Version 1 ====== - Key Value - --- ----- - created_time 2019-06-19T17:20:22.985303Z - deletion_time n/a - destroyed false - - ====== Version 2 ====== - Key Value - --- ----- - created_time 2019-06-19T17:22:23.369372Z - deletion_time n/a - destroyed true - ``` - -1. The metadata settings for a key can be configured: - - ```shell-session - $ vault kv metadata put -mount=secret -max-versions 2 -delete-version-after="3h25m19s" my-secret - Success! Data written to: secret/metadata/my-secret - ``` - - Delete-version-after settings will apply only to new versions. Max versions - changes will be applied on next write: - - ```shell-session - $ vault kv put -mount=secret my-secret my-value=newer-s3cr3t - Key Value - --- ----- - created_time 2019-06-19T17:31:16.662563Z - custom_metadata - deletion_time 2019-06-19T20:56:35.662563Z - destroyed false - version 4 - ``` - - Once a key has more versions than max versions the oldest versions - are cleaned up: - - ```shell-session - $ vault kv metadata get -mount=secret my-secret - ========== Metadata ========== - Key Value - --- ----- - cas_required false - created_time 2019-06-19T17:20:22.985303Z - current_version 4 - custom_metadata - delete_version_after 3h25m19s - max_versions 2 - oldest_version 3 - updated_time 2019-06-19T17:31:16.662563Z - - ====== Version 3 ====== - Key Value - --- ----- - created_time 2019-06-19T17:23:21.834403Z - deletion_time n/a - destroyed true - - ====== Version 4 ====== - Key Value - --- ----- - created_time 2019-06-19T17:31:16.662563Z - deletion_time 2019-06-19T20:56:35.662563Z - destroyed false - ``` - - A secret's key metadata can contain custom metadata used to describe the secret. - The data will be stored as string-to-string key-value pairs. - The `-custom-metadata` flag can be repeated to add multiple key-value pairs. - - The `vault kv metadata put` command can be used to fully overwrite the value of `custom_metadata`: - - ```shell-session - $ vault kv metadata put -mount=secret -custom-metadata=foo=abc -custom-metadata=bar=123 my-secret - Success! Data written to: secret/metadata/my-secret - - $ vault kv get -mount=secret my-secret - ====== Metadata ====== - Key Value - --- ----- - created_time 2019-06-19T17:22:23.369372Z - custom_metadata map[bar:123 foo:abc] - deletion_time n/a - destroyed false - version 2 - - ====== Data ====== - Key Value - --- ----- - foo aa - bar bb - ``` - - The `vault kv metadata patch` command can be used to partially overwrite the value of `custom_metadata`. - The following invocation will update `custom_metadata` sub-field `foo` but leave `bar` untouched: - - ```shell-session - $ vault kv metadata patch -mount=secret -custom-metadata=foo=def my-secret - Success! Data written to: secret/metadata/my-secret - ``` - - ```shell-session - $ vault kv get -mount=secret my-secret - ====== Metadata ====== - Key Value - --- ----- - created_time 2019-06-19T17:22:23.369372Z - custom_metadata map[bar:123 foo:def] - deletion_time n/a - destroyed false - version 2 - - ====== Data ====== - Key Value - --- ----- - foo aa - bar bb - ``` - -1. Permanently delete all metadata and versions for a key: - - ```shell-session - $ vault kv metadata delete -mount=secret my-secret - Success! Data deleted (if it existed) at: secret/metadata/my-secret - ``` - -## Tutorial - -Refer to the [Versioned Key Value Secrets -Engine](/vault/tutorials/secrets-management/versioned-kv) -tutorial to learn how to use KV secrets engine v2 to version or roll back secrets. - -## API - -The KV secrets engine has a full HTTP API. Please see the -[KV secrets engine API](/vault/api-docs/secret/kv/kv-v2) for more -details. diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/custom-metadata.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/custom-metadata.mdx new file mode 100644 index 000000000000..849a6277e583 --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/cookbook/custom-metadata.mdx @@ -0,0 +1,149 @@ +--- +layout: docs +page_title: Write custom metadata +description: >- + Write custom metadata fields to your kv v2 plugin. +--- + +# Write custom metadata in key/value v2 + +Write custom metadata to a `kv` v2 secret path. + + + +- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). +- Your authentication token has `create` and `update` permissions for the `kv` + v2 plugin. + + + + + + + +Use [`vault kv metadata put`](/vault/docs/command/kv/metadata) to set custom +metadata fields for a `kv` mount path. Repeat the `-custom-metadata` flag for +each key/value metadata entry: + +```shell-session +$ vault kv metadata put \ + -custom-metadata \ + -mount \ + +``` + +For example: + + + +```shell-session +$ vault kv metadata put \ + -custom-metadata "use=API keys for different dev environments" \ + -custom-metadata "renew-date=2026-11-14" \ + -mount shared \ + dev/square-api + +Success! Data written to: shared/metadata/dev/square-api +``` + + + +The `custom_metadata` metadata field now includes a map with the two custom +fields: + + + +```shell-session +$ vault kv metadata get -mount shared dev/square-api + +======== Metadata Path ======== +shared/metadata/dev/square-api + +========== Metadata ========== +Key Value +--- ----- +cas_required false +created_time 2024-11-13T21:51:50.898782695Z +current_version 9 +custom_metadata map[use:API keys for different dev environments renew-date:2026-11-14] +delete_version_after 0s +max_versions 10 +oldest_version 4 +updated_time 2024-11-15T03:10:26.749233814Z + +====== Version 1 ====== +Key Value +--- ----- +created_time 2024-11-13T21:51:50.898782695Z +deletion_time n/a +destroyed false +``` + + + + + + + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Select the **Metadata** tab. +- Click **Edit metadata >**. +- Set a new key name and value under **Custom metadata**. +- Use the **Add** button to set additional key/value pairs. +- Click **Update**. + +![Partial screenshot of the Vault GUI showing the "Edit Secret Metadata" screen](/img/gui/kv/custom-metadata.png) + + + + + +1. Create a JSON file with the metadata you want to write to the your `kv` v2 + plugin. Use the `custom_metadata` field to define the custom metadata fields + and initial values. + +1. Make a `POST` call to + [`/{plugin_mount_path}/metadata/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#create-update-metadata) + with the JSON data file: + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @metadata.json \ + ${VAULT_ADDR}/v1//metadata/ + ``` + +For example: + + + +```json +{ + "custom_metadata": { + "use": "API keys for different dev environments", + "renew-date": "2026-11-14" + } +} +``` + + + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @metadata.json \ + ${VAULT_ADDR}/v1/shared/metadata/dev/square-api +``` + +`/{plugin_mount_path}/metadata/{secret_path}` does not return data on success. + + + + + + diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/delete-data.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/delete-data.mdx new file mode 100644 index 000000000000..d2819d304b0d --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/cookbook/delete-data.mdx @@ -0,0 +1,144 @@ +--- +layout: docs +page_title: Soft delete data +description: >- + Use soft deletes to control the lifecycle of versioned key/value data in the + kv v2 plugin. +--- + +# Soft delete key/value data + +Use soft deletes to flag data at a secret path as unavailable while leaving the +data recoverable. You can revert soft deletes as long as the `destroyed` field +is `false` in the metadata. + + + +- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). +- Your authentication token has `create` and `update` permissions for the `kv` + v2 plugin. + + + + + + + +Use [`vault kv delete`](/vault/docs/command/kv/delete) with the `-versions` flag to +soft delete one or more version of key/value data and set `deletion_time` in the +metadata: + +```shell-session +$ vault kv delete \ + -mount \ + -versions \ + +``` + +For example: + + + +```shell-session +$ vault kv delete -mount shared -versions 1,4 dev/square-api + +Success! Data deleted (if it existed) at: shared/data/dev/square-api +``` + + + +The `deletion_time` metadata field for versions 1 and 4 now has the timestamp +of when Vault marked the versions as deleted: + + + +```shell-session +$ vault kv metadata get -mount shared dev/square-api + +======== Metadata Path ======== +shared/metadata/dev/square-api + +========== Metadata ========== +Key Value +--- ----- +cas_required false +created_time 2024-11-13T21:51:50.898782695Z +current_version 4 +custom_metadata +delete_version_after 0s +max_versions 5 +oldest_version 0 +updated_time 2024-11-14T22:32:42.29534643Z + +====== Version 1 ====== +Key Value +--- ----- +created_time 2024-11-13T21:51:50.898782695Z +deletion_time 2024-11-15T00:45:04.057772212Z +destroyed false + +... + +====== Version 4 ====== +Key Value +--- ----- +created_time 2024-11-14T22:32:42.29534643Z +deletion_time 2024-11-15T00:45:04.057772712Z +destroyed false +``` + + + + + + + + + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Select the appropriate data version from the **Version** dropdown. +- Click **Delete**. +- Select **Delete this version** to delete the selected version or + **Delete latest version** to delete the most recent data. +- Click **Confirm**. + +![Partial screenshot of the Vault GUI showing the "Delete version?" confirmation modal for data at the path dev/square-api](/img/gui/kv/delete-version.png) + + + + + +Make a `POST` call to +[`/{plugin_mount_path}/delete/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#delete-secret-versions) +with the data versions you want to soft delete: + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data '{"versions":[]} \ + ${VAULT_ADDR}/v1//delete/ +``` + +For example: + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data '{"versions":[5,8]}' \ + ${VAULT_ADDR}/v1/shared/delete/dev/square-api | jq + +``` + +`/{plugin_mount_path}/delete/{secret_path}` does not return data on success. + + + + + + \ No newline at end of file diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/destroy-data.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/destroy-data.mdx new file mode 100644 index 000000000000..8bcd2b4052f1 --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/cookbook/destroy-data.mdx @@ -0,0 +1,139 @@ +--- +layout: docs +page_title: Permanently delete data +description: >- + Permanently delete versioned key/value data in the kv v2 plugin. +--- + +# Destroy key/value data + +The standard `vault kv delete` command performs soft deletes. Use the CLI or GUI +to permanently delete (destroy) data so Vault purges the underlying data and +sets the `destroyed` metadata field to `true`. + + + + +- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). +- Your authentication token has `create` and `update` permissions for the `kv` + v2 plugin. + + + + + + + + +Use [`vault kv destroy`](/vault/docs/command/kv/destroy) with the `-versions` flag to +permanently delete one or more version of key/value data: + +```shell-session +$ vault kv destroy \ + -mount \ + -versions \ + +``` + +For example: + + + +```shell-session +$ vault kv destroy -mount shared -versions 2,3 dev/square-api + +Success! Data written to: shared/destroy/dev/square-api +``` + + + +The `destroyed` metadata field for versions 2 and 3 is now `true` + + + +```shell-session +$ vault kv metadata get -mount shared dev/square-api + +======== Metadata Path ======== +shared/metadata/dev/square-api + +========== Metadata ========== +Key Value +--- ----- +cas_required false +created_time 2024-11-13T21:51:50.898782695Z +current_version 4 +custom_metadata +delete_version_after 0s +max_versions 5 +oldest_version 0 +updated_time 2024-11-14T22:32:42.29534643Z + +... + +====== Version 2 ====== +Key Value +--- ----- +created_time 2024-11-13T21:52:10.326204209Z +deletion_time n/a +destroyed true + +====== Version 3 ====== +Key Value +--- ----- +created_time 2024-11-13T21:58:32.128442898Z +deletion_time n/a +destroyed true +``` + + + + + + + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Select the appropriate data version from the **Version** dropdown. +- Click **Destroy**. +- Click **Confirm**. + +![Partial screenshot of the Vault GUI showing the "Destroy version?" confirmation modal for data at the path dev/square-api](/img/gui/kv/destroy-version.png) + + + + + +Make a `POST` call to +[`/{plugin_mount_path}/destroy/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#destroy-secret-versions) +with the data versions you want to destroy: + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data '{"versions":[]} \ + ${VAULT_ADDR}/v1//destroy/ +``` + +For example: + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data '{"versions":[4,7]}' \ + ${VAULT_ADDR}/v1/shared/destroy/dev/square-api | jq + +``` + +`/{plugin_mount_path}/destroy/{secret_path}` does not return data on success. + + + + + + diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/max-versions.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/max-versions.mdx new file mode 100644 index 000000000000..f7763f94db4a --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/cookbook/max-versions.mdx @@ -0,0 +1,143 @@ +--- +layout: docs +page_title: Set max data versions +description: >- + Use max-versions to automatically destroy older data versions in the kv v2 + plugin. +--- + +# Set max data versions in key/value v2 + +Limit the number of active versions for a `kv` v2 secret path so Vault +permanently deletes (destroys) older data versions automatically. + + + +- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). +- Your authentication token has `create` and `update` permissions for the `kv` + v2 plugin. + + + + + + + +Use [`vault kv metadata put`](/vault/docs/command/kv/metadata) to change the max +number of versions allowed for a `kv` mount path: + +```shell-session +$ vault kv metadata put \ + -max-versions \ + -mount \ + +``` + +For example: + + + +```shell-session +$ vault kv metadata put \ + -max-versions 5 \ + -mount shared \ + dev/square-api + +Success! Data written to: shared/metadata/dev/square-api +``` + + + +Vault now auto-deletes data when the number of versions exceeds 5: + + + +```shell-session +$ vault kv metadata get -mount shared dev/square-api + +======== Metadata Path ======== +shared/metadata/dev/square-api + +========== Metadata ========== +Key Value +--- ----- +cas_required false +created_time 2024-11-13T21:51:50.898782695Z +current_version 4 +custom_metadata +delete_version_after 0s +max_versions 5 +oldest_version 0 +updated_time 2024-11-14T22:32:42.29534643Z + +====== Version 1 ====== +Key Value +--- ----- +created_time 2024-11-13T21:51:50.898782695Z +deletion_time n/a +destroyed false +``` + + + + + + + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Select the **Metadata** tab. +- Click **Edit metadata >**. +- Update the **Maximum number of versions** field. +- Click **Update**. + +![Partial screenshot of the Vault GUI showing the "Edit Secret Metadata" screen](/img/gui/kv/edit-metadata.png) + + + + + +1. Create a JSON file with the metadata field `max_versions` set to the maximum + number of versions you want to allow. + +1. Make a `POST` call to + [`/{plugin_mount_path}/metadata/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#create-update-metadata) + with the JSON data file: + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @metadata.json \ + ${VAULT_ADDR}/v1//metadata/ + ``` + +For example: + + + +```json +{ + "max_versions": 10 +} +``` + + + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @metadata.json \ + ${VAULT_ADDR}/v1/shared/metadata/dev/square-api +``` + +`/{plugin_mount_path}/metadata/{secret_path}` does not return data on success. + + + + + + \ No newline at end of file diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/patch-data.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/patch-data.mdx new file mode 100644 index 000000000000..1e746acbe588 --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/cookbook/patch-data.mdx @@ -0,0 +1,190 @@ +--- +layout: docs +page_title: Patch data +description: >- + Make partial updates or add new keys to versioned data in the kv v2 plugin +--- + +# Patch versioned key/value data + +Use the patch process to update specific values or add new key/value pairs to +an existing data path in the `kv` v2 plugin. + + + +- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). +- Your authentication token has appropriate permissions for the `kv` v2 plugin: + - **`patch`** permission to make direct updates with `PATCH` actions. + - **`create`**+**`update`** permission to make indirect updates by combining + `GET` and `POST` actions. + + + + + + + + +Use the [`vault kv patch`](/vault/docs/command/kv/patch) command and set the +`-cas` flag to the expected data version to perform a check-and-set operation +before applying the patch: + +```shell-session +$ vault kv patch \ + -cas \ + -max-versions \ + -mount \ + \ + = +``` + +For example: + + + +```shell-session +$ vault kv patch -cas 2 -mount shared dev/square-api prod=5678 + +======= Secret Path ======= +shared/data/dev/square-api + +======= Metadata ======= +Key Value +--- ----- +created_time 2024-11-13T21:52:10.326204209Z +custom_metadata +deletion_time n/a +destroyed false +version 2 +``` + + + +If the `-cas` version is older than the current version of data at the target +path, the patch fails: + + + +```shell-session +$ vault kv patch -cas 1 -mount shared dev/square-api prod=5678 + +Error writing data to shared/data/dev/square-api: Error making API request. + +URL: PATCH http://192.168.0.1:8200/v1/shared/data/dev/square-api +Code: 400. Errors: + +* check-and-set parameter did not match the current version +``` + + + +To **force** a patch, you can exclude the `-cas` flag **or** use the +`read+write` patch method with the `-method` flag. For example: + +```shell-session +$ vault kv patch -method rw -mount shared dev/square-api prod=5678 + +======= Secret Path ======= +shared/data/dev/square-api + +======= Metadata ======= +Key Value +--- ----- +created_time 2024-11-13T21:58:32.128442898Z +custom_metadata +deletion_time n/a +destroyed false +version 3 +``` + +Instead of using an HTTP `PATCH` action, the `read+write` method uses a sequence +of `GET` and `POST` operations to fetch the most recent version of data stored +at the targeted path, perform an in-memory update to the targeted keys, then +push the update to the plugin. + + + + + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Click **Create new version +** on the key/value page. +- Edit the values you want to update. +- Click **Save**. + +![Partial screenshot of the Vault GUI showing two editable key/value pairs at the path dev/square-api](/img/gui/kv/patch-data.png) + + + + + +1. Create a JSON file with the key/value data you want to patch. Use the +`options` field to set optional flags and `data` to define the key/value pairs +you want to update. + +1. Make a `PATCH` call to + [`/{plugin_mount_path}/data/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#patch-secret) + with the JSON data file and the `Content-Type` header set to + `application/merge-patch+json`: + ```shell-session + $ curl \ + --request PATCH \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --header "Content-Type: application/merge-patch+json" \ + --data @data.json \ + ${VAULT_ADDR}/v1//data/ + ``` + + +For example: + + + +```json +{ + "options": { + "cas": 4 + }, + "data": { + "smoke": "efgh" + } +} +``` + + + + + +```shell-session +$ curl \ + --request PATCH \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --header "Content-Type: application/merge-patch+json" \ + --data @data.json \ + ${VAULT_ADDR}/v1/shared/data/dev/square-api | jq + +{ + "request_id": "6f3bae46-6444-adeb-372a-7f100b4117f9", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "created_time": "2024-11-15T02:52:24.287700164Z", + "custom_metadata": null, + "deletion_time": "", + "destroyed": false, + "version": 5 + }, + "wrap_info": null, + "warnings": null, + "auth": null, + "mount_type": "kv" +} +``` + + + + + + diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/read-data.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/read-data.mdx new file mode 100644 index 000000000000..19763bd7f077 --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/cookbook/read-data.mdx @@ -0,0 +1,146 @@ +--- +layout: docs +page_title: Read data +description: >- + Read versioned key/value data from the kv v2 plugin +--- + +# Read versioned key/value data + +Read versioned data from an existing data path in the `kv` v2 plugin. + + + +- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). +- Your authentication token has `read` permissions for the `kv` v2 plugin. + + + + + + + +Use [`vault kv get`](/vault/docs/command/kv/read) to read **all** the current +key/value pairs on the given path: + +```shell-session +$ vault kv get \ + -mount \ + +``` + +For example: + + + +```shell-session +$ vault kv get -mount shared dev/square-api + +======= Secret Path ======= +shared/data/dev/square-api + +======= Metadata ======= +Key Value +--- ----- +created_time 2024-11-13T21:58:32.128442898Z +custom_metadata +deletion_time n/a +destroyed false +version 3 + +===== Data ===== +Key Value +--- ----- +prod 5678 +sandbox 1234 +``` + + + +Use the `-field` flag to target specific key value pairs on the given path: + +```shell-session +$ vault kv get \ + -mount \ + -field \ + +``` + +For example: + + + +```shell-session +$ vault kv get -mount shared -field prod dev/square-api + +5678 +``` + + + + + + + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Click the eye icon to view the desired key value. + +![Partial screenshot of the Vault GUI showing two key/value pairs at the path dev/square-api. The "prod" key is visible](/img/gui/kv/read-data.png) + + + + + +Call the [`/{plugin_mount_path}/data/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#read-secret-version) +endpoint to read all the key/value pairs at the secret path: + +```shell-session +$ curl \ + --request GET \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1//data/ +``` + +For example: + + + +```shell-session +$ curl \ + --request GET \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1/shared/data/dev/square-api | jq + +{ + "request_id": "992da4a2-f2d1-5786-ea53-1e8ea6440a7c", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "data": { + "prod": "5679", + "sandbox": "1234", + "smoke": "abcd" + }, + "metadata": { + "created_time": "2024-11-15T02:41:02.556301319Z", + "custom_metadata": null, + "deletion_time": "", + "destroyed": false, + "version": 7 + } + }, + "wrap_info": null, + "warnings": null, + "auth": null, + "mount_type": "kv" +} +``` + + + + + + diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/undelete-data.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/undelete-data.mdx new file mode 100644 index 000000000000..176eea4deb4a --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/cookbook/undelete-data.mdx @@ -0,0 +1,136 @@ +--- +layout: docs +page_title: Restore soft deleted data +description: >- + Revert soft deletes to restore versioned key/value data in the kv v2 plugin. +--- + +# Restore soft deleted key/value data + +You can restore data from soft deletes in the `kv` v2 plugin as long as the +`destroyed` metadata field for the targeted version is `false`. + + + +- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). +- Your authentication token has `create` and `update` permissions for the `kv` + v2 plugin. + + + + + + + +Use [`vault kv undelete`](/vault/docs/command/kv/undelete) with the `-versions` +flag to restore soft deleted version of key/value data: + +```shell-session +$ vault kv undelete \ + -mount \ + -versions \ + +``` + +For example: + + + +```shell-session +$ vault kv undelete -mount shared -versions 1,4 dev/square-api + +Success! Data deleted (if it existed) at: shared/data/dev/square-api +``` + + + +The `deletion_time` metadata field for versions 1 and 4 is now `n/a`: + + + +```shell-session +$ vault kv metadata get -mount shared dev/square-api + +======== Metadata Path ======== +shared/metadata/dev/square-api + +========== Metadata ========== +Key Value +--- ----- +cas_required false +created_time 2024-11-13T21:51:50.898782695Z +current_version 4 +custom_metadata +delete_version_after 0s +max_versions 5 +oldest_version 0 +updated_time 2024-11-14T22:32:42.29534643Z + +====== Version 1 ====== +Key Value +--- ----- +created_time 2024-11-13T21:51:50.898782695Z +deletion_time n/a +destroyed false + +... + +====== Version 4 ====== +Key Value +--- ----- +created_time 2024-11-14T22:32:42.29534643Z +deletion_time n/a +destroyed false +``` + + + + + + + + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Select the appropriate data version from the **Version** dropdown. +- Click **Undelete**. + +![Partial screenshot of the Vault GUI showing the deleted version message](/img/gui/kv/undelete-data.png) + + + + + +Make a `POST` call to +[`/{plugin_mount_path}/undelete/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#undelete-secret-versions) +with the data versions you want to restore: + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data '{"versions":[]} \ + ${VAULT_ADDR}/v1//undelete/ +``` + +For example: + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data '{"versions":[5,8]}' \ + ${VAULT_ADDR}/v1/shared/undelete/dev/square-api | jq + +``` + +`/{plugin_mount_path}/undelete/{secret_path}` does not return data on success. + + + + + + \ No newline at end of file diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/write-data.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/write-data.mdx new file mode 100644 index 000000000000..1250f25f171d --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/cookbook/write-data.mdx @@ -0,0 +1,157 @@ +--- +layout: docs +page_title: Write new data +description: >- + Write new versioned data to the kv v2 plugin +--- + +# Write new key/value data + +Write new versions of data to a new or existing data path in the `kv` v2 plugin. + + + +- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). +- Your authentication token has `create` and `update` permissions for the `kv` + v2 plugin. + + + + + + + + + +The Vault CLI forcibly converts `kv` keys and values data to strings before +writing data. To preserve non-string data, write your key/value pairs to Vault +from a JSON file or use the plugin API. + + + +Use [`vault kv put`](/vault/docs/command/kv/put) to save a new version of +key/value data to an new or existing secret path: + +```shell-session +$ vault kv put \ + -mount \ + \ + +``` + +For example: + + + +```shell-session +$ vault kv put \ + -mount shared \ + dev/square-api \ + sandbox=1234 prod=5679 smoke=abcd + +======= Secret Path ======= +shared/data/dev/square-api + +======= Metadata ======= +Key Value +--- ----- +created_time 2024-11-15T01:52:23.434633061Z +custom_metadata +deletion_time n/a +destroyed false +version 5 +``` + + + + + + + +The Vault GUI forcibly converts non-string keys to strings before writing data. +To preserve non-string values, use the JSON toggle to write your key/value data +as JSON. + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Click **Create new version +**. +- Set a new key name and value. +- Use the **Add** button to set additional key/value pairs. +- Click **Save** to write the new version data. + +![Partial screenshot of the Vault GUI showing the "Create New Version" screen](/img/gui/kv/write-data.png) + + + + + +1. Create a JSON file with the key/value data you want to write to Vault. Use +the `options` field to set optional flags and `data` to define the key/value +pairs. + +1. Make a `POST` call to + [`/{plugin_mount_path}/data/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#create-update-secret) + with the JSON data: + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @data.json \ + ${VAULT_ADDR}/v1//data/ + ``` + + +For example: + + + + +```json +{ + "options": { + "cas": 4 + }, + "data": { + "sandbox": "1234", + "prod": "5679", + "smoke": "abcd" + } +} +``` + + + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/shared/data/dev/square-api | jq + +{ + "request_id": "0c872d86-0def-4261-34d9-b796039ec02f", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "created_time": "2024-11-15T02:41:02.556301319Z", + "custom_metadata": null, + "deletion_time": "", + "destroyed": false, + "version": 5 + }, + "wrap_info": null, + "warnings": null, + "auth": null, + "mount_type": "kv" +} +``` + + + + + + diff --git a/website/content/docs/secrets/kv/kv-v2/index.mdx b/website/content/docs/secrets/kv/kv-v2/index.mdx new file mode 100644 index 000000000000..19c292478cb5 --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/index.mdx @@ -0,0 +1,64 @@ +--- +layout: docs +page_title: Key/Value v2 +description: >- + Store arbitrary static secrets in Vault with the Key/Value v2 secrets engine + plugin. +--- + +# Key/Value v2 plugin + +The key/value (`kv`) secrets engine stores and versions arbitrary static secrets +stored in Vault physical storage. + +The `kv` v2 plugin uses soft deletes to make data inaccessible while allowing +data recovery. When an entry is permanently deleted, Vault purges the underlying +version data and marks the key metadata as destroyed. + + + + + + +Step-by-step instructions: + +- [Upgrade from `kv` v1](/vault/docs/secrets/kv/kv-v2/upgrade) +- [Set up the `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup) + + + + + +Basic examples: + +- [Read data](/vault/docs/secrets/kv/kv-v2/cookbook/read-data) +- [Set max data versions](/vault/docs/secrets/kv/kv-v2/cookbook/max-versions) +- [Write data](/vault/docs/secrets/kv/kv-v2/cookbook/write-data) +- [Patch and update data](/vault/docs/secrets/kv/kv-v2/cookbook/patch-data) +- [Soft delete data](/vault/docs/secrets/kv/kv-v2/cookbook/delete-data) +- [Restore soft deleted data](/vault/docs/secrets/kv/kv-v2/cookbook/undelete-data) +- [Destroy data](/vault/docs/secrets/kv/kv-v2/cookbook/destroy-data) +- [Write custom metadata](/vault/docs/secrets/kv/kv-v2/cookbook/custom-metadata) + + + + + +Technical references: + +- [KV v2 CLI commands](/vault/docs/command/kv) +- [KV v2 plugin API docs](/vault/api-docs/secret/kv/kv-v2) + + + + + +Detailed tutorials: + +- [Versioned Key Value Secrets Engine](/vault/tutorials/secrets-management/versioned-kv) - + Learn how to compare data in the KV v2 secrets engine and protect data from + accidental deletion. + + + + \ No newline at end of file diff --git a/website/content/docs/secrets/kv/kv-v2/random-string.mdx b/website/content/docs/secrets/kv/kv-v2/random-string.mdx new file mode 100644 index 000000000000..858ae231c00c --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/random-string.mdx @@ -0,0 +1,330 @@ +--- +layout: docs +page_title: Save random strings +description: >- + Use password policies and the key/value v2 plugins to generate and store + random strings in Vault. +--- + +# Save random strings to the key/value v2 plugin + +Use [password policies](/vault/docs/concepts/password-policies) to generate +random strings and save the strings to your key/value v2 plugin. + +## Before you start + +- **You must have `read`, `create`, and `update` permission for password policies. +- **You must have `create` and `update` permission for your `kv` v2 plugin**. + + +## Step 1: Create a password policy file + +Create an HCL file with a password policy with the desired randomization and +generation rules. + +For example, the following password policy requires a string 20 characters long +that includes: + +- at least one lowercase character +- at least one uppercase character +- at least one number +- at least two special characters + +```hcl +length=20 + +rule "charset" { + charset = "abcdefghijklmnopqrstuvwxyz" + min-chars = 1 +} + +rule "charset" { + charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + min-chars = 1 +} + +rule "charset" { + charset = "0123456789" + min-chars = 1 +} + +rule "charset" { + charset = "!@#$%^&*STUVWXYZ" + min-chars = 2 +} +``` + + +## Step 2: Save the password policy + + + + + +Use `vault write` to save policies to the password policies endpoint +(`sys/policies/password/`): + +```shell-session +$ vault write sys/policies/password/ policy=@ +``` + +For example: + + + +```shell-session +$ vault write sys/policies/password/randomize policy=@password-rules.hcl + +Success! Data written to: sys/policies/password/randomize +``` + + + + + + + +Escape your password policy file and make a `POST` call to +[`/sys/policies/password/{policy_name}`](/vault/api-docs/system/policies-password#create-update-password-policy) +with your password creation rules: + +```shell-session +$ jq -Rs '{ "policy": . | gsub("[\\r\\n\\t]"; "") }' | + curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + "$( +``` + +For example: + + + +```shell-session +$ jq -Rs '{ "policy": . | gsub("[\\r\\n\\t]"; "") }' ./password-rules.hcl | + curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data "$( + +`/sys/policies/password/{policy_name}` does not return data on success. + + + + + + + +## Step 3: Save a random string to `kv` v2 + + + + + +Use `vault read` and the `generate` endpoint of the new password policy to +generate a new random string and write it to the `kv` plugin with +`vault kv put`: + +```shell-session +$ vault kv put \ + -mount \ + \ + =$( \ + vault read -field password \ + sys/policies/password//generate \ + ) +``` + +For example: + + + +```shell-session +$ vault kv put \ + -mount shared \ + /dev/seeds \ + seed1=$( \ + vault read -field password \ + sys/policies/password/randomize/generate \ + ) + +==== Secret Path ==== +shared/data/dev/seeds + +======= Metadata ======= +Key Value +--- ----- +created_time 2024-11-15T23:15:31.929717548Z +custom_metadata +deletion_time n/a +destroyed false +version 1 +``` + + + + + + + +Use the +[`/sys/policies/password/{policy_name}/generate`](/vault/api-docs/system/policies-password#generate-password-from-password-policy) +endpoint of the new password policy to generate a random string and write it to +the `kv` plugin with a `POST` call to +[`/{plugin_mount_path}/data/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#create-update-secret): + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data \ + "{ + \"data\": { + \"\": \"$( + vault read -field password sys/policies/password//generate + )\" + } + }" \ + ${VAULT_ADDR}/v1//data/ +``` + +For example: + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data \ + "{ + \"data\": { + \"seed1\": \"$( + vault read -field password sys/policies/password/randomize/generate + )\" + } + }" \ + ${VAULT_ADDR}/v1/shared/data/dev/seeds | jq + +{ + "request_id": "f9fad221-74e7-72c4-3f5a-9364944c37d9", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "created_time": "2024-11-15T23:33:08.549750507Z", + "custom_metadata": null, + "deletion_time": "", + "destroyed": false, + "version": 1 + }, + "wrap_info": null, + "warnings": null, + "auth": null, + "mount_type": "kv" +} +``` + + + + + + + +## Step 4: Verify the data in Vault + + + + + +Use [`vault kv get`](/vault/docs/command/kv/read) with the `-field` flag to read +the randomized string from the relevant secret path: + +```shell-session +$ vault kv get \ + -mount \ + -field \ + +``` + +For example: + + + +```shell-session +$ vault kv get -mount shared -field seed1 dev/seeds + +g0bc0b6W3ii^SXa@*ie5 +``` + + + + + + + +@include 'gui-page-instructions/select-kv-mount.mdx' + +- Click through the path segments to select the relevant secret path. +- Click the eye icon to view the desired key value. + +![Partial screenshot of the Vault GUI showing the randomized string stored at the path dev/seeds.](/img/gui/kv/random-string.png) + + + + + +Call the [`/{plugin_mount_path}/data/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#read-secret-version) +endpoint to read all the key/value pairs at the secret path: + +```shell-session +$ curl \ + --request GET \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1//data/ +``` + +For example: + + + +```shell-session +$ curl \ + --request GET \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1/shared/data/dev/seeds | jq + +{ + "request_id": "c1202e8d-aff9-2d81-0929-4a558a193b4c", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "data": { + "seed1": "g0bc0b6W3ii^SXa@*ie5" + }, + "metadata": { + "created_time": "2024-11-15T23:33:08.549750507Z", + "custom_metadata": null, + "deletion_time": "", + "destroyed": false, + "version": 1 + } + }, + "wrap_info": null, + "warnings": null, + "auth": null, + "mount_type": "kv" +} +``` + + + + + + diff --git a/website/content/docs/secrets/kv/kv-v2/setup.mdx b/website/content/docs/secrets/kv/kv-v2/setup.mdx new file mode 100644 index 000000000000..1d386496450a --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/setup.mdx @@ -0,0 +1,278 @@ +--- +layout: docs +page_title: Set up the key/value v2 plugin +description: >- + Enable and configure the key/value v2 plugins to store arbitrary static + secrets in Vault. +--- + +# Set up the key/value v2 plugin + +Use `vault secrets enable` to enable an instance of the `kv` plugin. To specify +version 2, use the `-version` flag or specific `kv-v2` as the plugin type: + +Additionally, when running a dev-mode server, the v2 `kv` secrets engine is enabled by default at the +path `demo/` (for non-dev servers, it is currently v1). It can be disabled, moved, or enabled multiple times at +different paths. Each instance of the KV secrets engine is isolated and unique. + + +## Before you start + +- **You must have permission to update ACL policies**. +- **You must have permission to enable plugins**. + + + +## Step 1: Enable the plugin + + + + + + +Use `vault secrets enable` to establish a new instance of the `kv` plugin. + +To specify key/value version 2, use the `-version` flag or use `kv-v2` as the +plugin type. + + +**Option 1**: Use the `-version` flag: + +```shell-session +$ vault secrets enable -path -version=2 kv +``` + +**Option 2**: Use the `kv-v2` plugin type: + +```shell-session +$ vault secrets enable -path kv-v2 +``` + + + + + +@include 'gui-page-instructions/enable-secrets-plugin.mdx' + +- Select the "KV" plugin. + +- Enter a unique path for the plugin and provide the relevant configuration + data. + + + + + +1. Create a JSON file with the type and configuration information for your `kv` +v2 instance. Use the `options` field to set optional flags. + +1. Make a `POST` call to + [`/sys/mounts/{plugin_mount_path}`](/vault/api-docs/system/mounts#enable-secrets-engine) + with the JSON data: + ```shell-session + $ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/sys/mounts/ + ``` + + +For example: + + + + +```json +{ + "type": "kv", + "options": { + "version": "2" + } +} +``` + + + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @data.json \ + ${VAULT_ADDR}/v1/sys/mounts/shared | jq +``` + + + +`/sys/mounts/{plugin_mount_path}` does not return data on success. + + + + + + + +## Step 2: Create an ACL policy file + + + + ACL policies for `kv` plugins do not support the `allowed_parameters`, + `denied_parameters`, and `required_parameters` policy fields. + + + +Create a policy definition file based on your needs. + +For example, assume there are API keys stored on the path `/dev/square-api` for +a `kv` plugin mounted at `shared/`. The following policy lets clients read and +patch the latest version of API keys and read metadata for any version of the +API keys: + +```hcl +# Grants permission to read and patch the latest version of API keys +path "shared/data/dev/square-api/*" { + + capabilities = ["read", "patch"] +} + +# Grants permission to read metadata for any version of the API keys +path "shared/metadata/dev/square-api/" { + + capabilities = ["read"] +} +``` + + + + + +@include 'policies/path-prefixes.mdx' + + + + + +@include 'policies/policy-permissions.mdx' + + + + + +If you are unsure about the required permissions, use the Vault CLI to run a +command with placeholder data and the `-output-policy` flag against an existing +`kv` plugin to generate a minimal policy. + + + +```shell-session +$ vault kv patch \ + -output-policy \ + -mount \ + test-path \ + test=test +``` + + + +For example: + + + +```shell-session +$ vault kv patch \ + -output-policy \ + -mount private \ + test-path \ + test=test + +path "private/data/test-path" { + capabilities = ["patch"] +} +``` + + + +## Step 3: Save the ACL policy + + + + + +Use `vault policy write` to create a new ACL policy with the policy definition +file: + +```shell-session +$ vault policy write +``` + +For example: + + + +```shell-session +$ vault policy write "KV-access-policy" ./kv-policy.hcl +``` + + + + + + + +@include 'gui-page-instructions/create-acl-policy.mdx' + +- Provide a name for the policy and upload the policy definition file. + + + +If you expect to modify policies with the Vault API, avoid spaces and special +characters in the policy name. The policy name becomes part of the API endpoint +path. + + + + + + + +Escape your policy file and make a `POST` call to +[`/sys/policy/{policy_name}`](/vault/api-docs/system/policy#create-update-policy) +with your policy details: + +```shell-session +$ jq -Rs '{ "policy": . | gsub("[\\r\\n\\t]"; "") }' | + curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + "$( +``` + +For example: + + + +```shell-session +$ jq -Rs '{ "policy": . | gsub("[\\r\\n\\t]"; "") }' ./kv-policy.hcl | + curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data "$( + +`/sys/mounts/{plugin_mount_path}` does not return data on success. + + + + + + + +## Next steps + +- [Create an authentication mapping for the plugin](/vault/docs/concepts/policies#associating-policies) diff --git a/website/content/docs/secrets/kv/kv-v2/upgrade.mdx b/website/content/docs/secrets/kv/kv-v2/upgrade.mdx new file mode 100644 index 000000000000..e56655606f81 --- /dev/null +++ b/website/content/docs/secrets/kv/kv-v2/upgrade.mdx @@ -0,0 +1,108 @@ +--- +layout: docs +page_title: Upgrade to key/value v2 +description: >- + Upgrade existing v1 key/value plugins to leverage kv v2 features. +--- + +# Upgrade `kv` version 1 plugins + +You can upgrade existing version 1 key/value stores to version 2 to use +versioning. + + + + You cannot access v1 plugin mounts during the upgrade, which may take a long + time for plugins that contain significant data. + + + +## Before you start + +- **You must have permission to update ACL policies**. +- **You must have permission to tune the `kv1` v1 plugin**. + + + +## Step 1: Update ACL rules + +The `kv` v2 plugin uses different API path prefixes than `kv` v1. You must +upgrade the relevant ACL policies **before** upgrading the plugin by changing +v1 paths for read, write, or update policies to include the v2 path prefix, +`data/`. + +For example, the following `kv` v1 policy: + +```hcl +path "shared/dev/square-api/*" { + capabilities = ["create", "update", "read"] +} +``` + +becomes: + +```hcl +path "secret/dev/square-api/*" { + capabilities = ["create", "update", "read"] +} +``` + + + + You can assign different ACL policies to different `kv` v2 paths. + + + + + +## Step 2: Upgrade the plugin instance + + + + + +Use the `enable-versioning` subcommand to upgrade from v1 to v2: + +```shell-session +$ vault kv enable-versioning +``` + +For example: + + + +```shell-session +$ vault kv enable-versioning shared/ +Success! Tuned the secrets engine at: shared/ +``` + + + + + + + +Make a `POST` call to +[`/sys/mounts/{plugin_mount_path}`](/vault/api-docs/system/mounts#enable-secrets-engine) +with `options.version` set to `2` to update the plugin version: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data '{\"options\": {\"version\": \"2\"}}' \ + http://${VAULT_ADDR}/v1/sys/mounts/${KV_MOUNT_PATH}/tune +``` + + + + + + + +## Related resources + +- [KV v2 plugin API docs](/vault/api-docs/secret/kv/kv-v2) +- [Tutorial: Versioned Key Value Secrets Engine](/vault/tutorials/secrets-management/versioned-kv) - + Learn how to compare data in the KV v2 secrets engine and protect data from + accidental deletion. \ No newline at end of file diff --git a/website/content/partials/gui-page-instructions/select-kv-mount.mdx b/website/content/partials/gui-page-instructions/select-kv-mount.mdx new file mode 100644 index 000000000000..aa162c153fb4 --- /dev/null +++ b/website/content/partials/gui-page-instructions/select-kv-mount.mdx @@ -0,0 +1,10 @@ +- Open the data page for your `kv` plugin: + + 1. Open the GUI for your Vault instance. + + 1. Login under the namespace for the plugin or select the namespace from the + selector at the bottom of the left-hand menu and re-authenticate. + + 1. Select **Secrets Engines** from the left-hand menu. + + 1. Select the mount path for your `kv` plugin. \ No newline at end of file diff --git a/website/content/partials/policies/path-prefixes.mdx b/website/content/partials/policies/path-prefixes.mdx new file mode 100644 index 000000000000..ed889e19b359 --- /dev/null +++ b/website/content/partials/policies/path-prefixes.mdx @@ -0,0 +1,6 @@ +Path prefix | Policy effect +----------- | -------------------- +`data` | Permissions apply to the **latest** version of the data. +`undelete` | Clients can use un-delete commands and endpoints on any version of the data. +`destroy` | Clients can use destroy commands and endpoints on any version of the data. +`metadata` | Clients can use metadata commands and endpoints on any version of the data. \ No newline at end of file diff --git a/website/content/partials/policies/policy-permissions.mdx b/website/content/partials/policies/policy-permissions.mdx new file mode 100644 index 000000000000..62cacb6851b5 --- /dev/null +++ b/website/content/partials/policies/policy-permissions.mdx @@ -0,0 +1,21 @@ +Permission | HTTP action | Result +----------- | ------------- | ----------- +`create` | `POST`/`PUT` | Clients can write **new** data to the path. +`delete` | `DELETE` | Clients can remove data from the path. +`deny` | N/A | **Clients cannot access the path**.
`deny` takes precedence over all other permission (including `sudo`). +`list` | `LIST` | Clients can list data from the path. Not all plugins support `list`. +`patch` | `PATCH` | Clients can update or write explicit key/value pairs to an **existing** the path. +`read` | `GET` | Clients can read data from the path. +`subscribe` | N/A | Clients can request access to event streams from the plugin at the path. Not all plugins support `subscribe`. +`sudo` | N/A | Clients can access the root-protected path when paired with the relevant permission verb. +`update` | `POST`/`PUT` | Clients can **fully** overwrite data on an existing the path. + + + +Data returned for a `list` operation **is not** filtered against ACL policies. +**Do not** encode sensitive information in key names. + + + + + diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index e36349e89eae..546597d77229 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1573,7 +1573,7 @@ ] }, { - "title": "Key Value", + "title": "Key/Value", "routes": [ { "title": "Overview", @@ -1585,7 +1585,62 @@ }, { "title": "KV version 2", - "path": "secrets/kv/kv-v2" + "routes": + [ + { + "title": "Overview", + "path": "secrets/kv/kv-v2" + }, + { + "title": "Upgrade from v1", + "path": "secrets/kv/kv-v2/upgrade" + }, + { + "title": "Setup", + "path": "secrets/kv/kv-v2/setup" + }, + { + "title": "Save random strings", + "path": "secrets/kv/kv-v2/random-string" + }, + { + "title": "Cookbook", + "routes": [ + { + "title": "Read data", + "path": "secrets/kv/kv-v2/cookbook/read-data" + }, + { + "title": "Set max data versions", + "path": "secrets/kv/kv-v2/cookbook/max-versions" + }, + { + "title": "Write data", + "path": "secrets/kv/kv-v2/cookbook/write-data" + }, + { + "title": "Patch/update data", + "path": "secrets/kv/kv-v2/cookbook/patch-data" + }, + { + "title": "Soft delete data", + "path": "secrets/kv/kv-v2/cookbook/delete-data" + }, + { + "title": "Restore soft deleted data", + "path": "secrets/kv/kv-v2/cookbook/undelete-data" + }, + { + "title": "Destroy data", + "path": "secrets/kv/kv-v2/cookbook/destroy-data" + }, + { + "title": "Write custom metadata", + "path": "secrets/kv/kv-v2/cookbook/custom-metadata" + } + ] + } + ] } ] }, diff --git a/website/public/img/gui/kv/custom-metadata.png b/website/public/img/gui/kv/custom-metadata.png new file mode 100644 index 000000000000..53fc1b98cfee Binary files /dev/null and b/website/public/img/gui/kv/custom-metadata.png differ diff --git a/website/public/img/gui/kv/delete-version.png b/website/public/img/gui/kv/delete-version.png new file mode 100644 index 000000000000..a22eb597d7ce Binary files /dev/null and b/website/public/img/gui/kv/delete-version.png differ diff --git a/website/public/img/gui/kv/destroy-version.png b/website/public/img/gui/kv/destroy-version.png new file mode 100644 index 000000000000..c7f1b371a061 Binary files /dev/null and b/website/public/img/gui/kv/destroy-version.png differ diff --git a/website/public/img/gui/kv/edit-metadata.png b/website/public/img/gui/kv/edit-metadata.png new file mode 100644 index 000000000000..75c6375c2c49 Binary files /dev/null and b/website/public/img/gui/kv/edit-metadata.png differ diff --git a/website/public/img/gui/kv/patch-data.png b/website/public/img/gui/kv/patch-data.png new file mode 100644 index 000000000000..38cbe953598f Binary files /dev/null and b/website/public/img/gui/kv/patch-data.png differ diff --git a/website/public/img/gui/kv/random-string.png b/website/public/img/gui/kv/random-string.png new file mode 100644 index 000000000000..e14d7553282b Binary files /dev/null and b/website/public/img/gui/kv/random-string.png differ diff --git a/website/public/img/gui/kv/read-data.png b/website/public/img/gui/kv/read-data.png new file mode 100644 index 000000000000..a6b397c0b0a6 Binary files /dev/null and b/website/public/img/gui/kv/read-data.png differ diff --git a/website/public/img/gui/kv/undelete-data.png b/website/public/img/gui/kv/undelete-data.png new file mode 100644 index 000000000000..432afa47fc7c Binary files /dev/null and b/website/public/img/gui/kv/undelete-data.png differ diff --git a/website/public/img/gui/kv/write-data.png b/website/public/img/gui/kv/write-data.png new file mode 100644 index 000000000000..edfa228c1fc1 Binary files /dev/null and b/website/public/img/gui/kv/write-data.png differ