upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-02-03 20:40:45 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

[DOCS] Refresh kv docs (#28919)

Browse source 
* refresh kv docs

* apply feedback and add missing API instructions
This commit is contained in:
Sarah Chavis 2024-11-15 17:06:26 -08:00 committed by GitHub
parent 52ba156d47
commit cb0448a785
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
26 changed files with 2078 additions and 632 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

630
website/content/docs/secrets/kv/kv-v2.mdx
View file

@ -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 <nil>
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 <nil>
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 <nil>
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 <nil>
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 <nil>
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 <nil>
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 <nil>
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 <nil>
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 <nil>
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=-<<EOF
length=20
rule "charset" {
charset = "abcdefghij0123456789"
min-chars = 1
}
rule "charset" {
charset = "!@#$%^&*STUVWXYZ"
min-chars = 1
}
EOF
```
1. Write data using the `example` policy:
```shell-session
$ vault kv put -mount=secret my-generated-secret \
password=$(vault read -field password sys/policies/password/example/generate)
```
**Example output:**
<CodeBlockConfig hideClipboard>
```plaintext
========= Secret Path =========
secret/data/my-generated-secret
======= Metadata =======
Key Value
--- -----
created_time 2023-05-10T14:32:32.37354939Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
```
</CodeBlockConfig>
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 <nil>
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 <nil>
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 <nil>
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 <nil>
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 <nil>
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.

149
website/content/docs/secrets/kv/kv-v2/cookbook/custom-metadata.mdx Normal file
View file

@ -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.
<Tip title="Assumptions">
- 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.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
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 <key_value_pair> \
-mount <mount_path> \
<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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
```
</CodeBlockConfig>
The `custom_metadata` metadata field now includes a map with the two custom
fields:
<CodeBlockConfig hideClipboard="true" highlight="14">
```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
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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)
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>/metadata/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```json
{
"custom_metadata": {
"use": "API keys for different dev environments",
"renew-date": "2026-11-14"
}
}
```
</CodeBlockConfig>
<CodeBlockConfig hideClipboard="true">
```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.
</CodeBlockConfig>
</Tab>
</Tabs>

144
website/content/docs/secrets/kv/kv-v2/cookbook/delete-data.mdx Normal file
View file

@ -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.
<Tip title="Assumptions">
- 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.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
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 <mount_path> \
-versions <target_versions> \
<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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
```
</CodeBlockConfig>
The `deletion_time` metadata field for versions 1 and 4 now has the timestamp
of when Vault marked the versions as deleted:
<CodeBlockConfig hideClipboard="true" highlight="22,31">
```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 <nil>
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
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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)
</Tab>
<Tab heading="API" group="api">
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":[<target_versions>]} \
${VAULT_ADDR}/v1/<plugin_mount_path>/delete/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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.
</CodeBlockConfig>
</Tab>
</Tabs>

139
website/content/docs/secrets/kv/kv-v2/cookbook/destroy-data.mdx Normal file
View file

@ -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`.
<Tip title="Assumptions">
- 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.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
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 <mount_path> \
-versions <target_versions> \
<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ vault kv destroy -mount shared -versions 2,3 dev/square-api
Success! Data written to: shared/destroy/dev/square-api
```
</CodeBlockConfig>
The `destroyed` metadata field for versions 2 and 3 is now `true`
<CodeBlockConfig hideClipboard="true" highlight="25,32">
```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 <nil>
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
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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)
</Tab>
<Tab heading="API" group="api">
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":[<target_versions>]} \
${VAULT_ADDR}/v1/<plugin_mount_path>/destroy/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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.
</CodeBlockConfig>
</Tab>
</Tabs>

143
website/content/docs/secrets/kv/kv-v2/cookbook/max-versions.mdx Normal file
View file

@ -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.
<Tip title="Assumptions">
- 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.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
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 <max_versions> \
-mount <mount_path> \
<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ vault kv metadata put \
-max-versions 5 \
-mount shared \
dev/square-api
Success! Data written to: shared/metadata/dev/square-api
```
</CodeBlockConfig>
Vault now auto-deletes data when the number of versions exceeds 5:
<CodeBlockConfig hideClipboard="true" highlight="14">
```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 <nil>
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
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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)
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>/metadata/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```json
{
"max_versions": 10
}
```
</CodeBlockConfig>
<CodeBlockConfig hideClipboard="true">
```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.
</CodeBlockConfig>
</Tab>
</Tabs>

190
website/content/docs/secrets/kv/kv-v2/cookbook/patch-data.mdx Normal file
View file

@ -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.
<Tip title="Assumptions">
- 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.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
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 <target_version> \
-max-versions <max_versions> \
-mount <mount_path> \
<secret_path> \
<key_name>=<key_value>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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 <nil>
deletion_time n/a
destroyed false
version 2
```
</CodeBlockConfig>
If the `-cas` version is older than the current version of data at the target
path, the patch fails:
<CodeBlockConfig hideClipboard="true">
```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
```
</CodeBlockConfig>
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 <nil>
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.
</Tab>
<Tab heading="GUI" group="gui">
@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)
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>/data/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```json
{
"options": {
"cas": 4
},
"data": {
"smoke": "efgh"
}
}
```
</CodeBlockConfig>
<CodeBlockConfig hideClipboard="true">
```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"
}
```
</CodeBlockConfig>
</Tab>
</Tabs>

146
website/content/docs/secrets/kv/kv-v2/cookbook/read-data.mdx Normal file
View file

@ -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.
<Tip title="Assumptions">
- 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.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
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 <mount_path> \
<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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 <nil>
deletion_time n/a
destroyed false
version 3
===== Data =====
Key Value
--- -----
prod 5678
sandbox 1234
```
</CodeBlockConfig>
Use the `-field` flag to target specific key value pairs on the given path:
```shell-session
$ vault kv get \
-mount <mount_path> \
-field <field_name> \
<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ vault kv get -mount shared -field prod dev/square-api
5678
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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)
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>/data/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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"
}
```
</CodeBlockConfig>
</Tab>
</Tabs>

136
website/content/docs/secrets/kv/kv-v2/cookbook/undelete-data.mdx Normal file
View file

@ -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`.
<Tip title="Assumptions">
- 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.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
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 <mount_path> \
-versions <target_versions> \
<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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
```
</CodeBlockConfig>
The `deletion_time` metadata field for versions 1 and 4 is now `n/a`:
<CodeBlockConfig hideClipboard="true" highlight="22,31">
```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 <nil>
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
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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)
</Tab>
<Tab heading="API" group="api">
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":[<target_versions>]} \
${VAULT_ADDR}/v1/<plugin_mount_path>/undelete/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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.
</CodeBlockConfig>
</Tab>
</Tabs>

157
website/content/docs/secrets/kv/kv-v2/cookbook/write-data.mdx Normal file
View file

@ -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.
<Tip title="Assumptions">
- 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.
</Tip>
<Tabs>
<Tab heading="CLI" group="cli">
<Note>
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.
</Note>
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 <mount_path> \
<secret_path> \
<list_of_kv_values>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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 <nil>
deletion_time n/a
destroyed false
version 5
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
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)
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>/data/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```json
{
"options": {
"cas": 4
},
"data": {
"sandbox": "1234",
"prod": "5679",
"smoke": "abcd"
}
}
```
</CodeBlockConfig>
<CodeBlockConfig hideClipboard="true">
```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"
}
```
</CodeBlockConfig>
</Tab>
</Tabs>

64
website/content/docs/secrets/kv/kv-v2/index.mdx Normal file
View file

@ -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.
<Tabs>
<Tab heading="How-to guides" group="how-to">
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)
</Tab>
<Tab heading="Cookbook" group="cook">
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)
</Tab>
<Tab heading="Reference" group="ref">
Technical references:
- [KV v2 CLI commands](/vault/docs/command/kv)
- [KV v2 plugin API docs](/vault/api-docs/secret/kv/kv-v2)
</Tab>
<Tab heading="Tutorials" group="tutorial">
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.
</Tab>
</Tabs>

330
website/content/docs/secrets/kv/kv-v2/random-string.mdx Normal file
View file

@ -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
<Tabs>
<Tab heading="CLI" group="cli">
Use `vault write` to save policies to the password policies endpoint
(`sys/policies/password/<policy_name>`):
```shell-session
$ vault write sys/policies/password/<policy_name> policy=@<policy_file>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ vault write sys/policies/password/randomize policy=@password-rules.hcl
Success! Data written to: sys/policies/password/randomize
```
</CodeBlockConfig>
</Tab>
<Tab heading="API" group="api">
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]"; "") }' <path_to_policy_file> |
curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
"$(</dev/stdin)" \
${VAULT_ADDR}/v1/sys/policies/password/<policy_name>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ jq -Rs '{ "policy": . | gsub("[\\r\\n\\t]"; "") }' ./password-rules.hcl |
curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data "$(</dev/stdin)" \
${VAULT_ADDR}/v1/sys/policies/password/randomize | jq
```
</CodeBlockConfig>
`/sys/policies/password/{policy_name}` does not return data on success.
</Tab>
</Tabs>
## Step 3: Save a random string to `kv` v2
<Tabs>
<Tab heading="CLI" group="cli">
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 <mount_path> \
<secret_path> \
<key_name>=$( \
vault read -field password \
sys/policies/password/<policy_name>/generate \
)
```
For example:
<CodeBlockConfig hideClipboard="true">
```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 <nil>
deletion_time n/a
destroyed false
version 1
```
</CodeBlockConfig>
</Tab>
<Tab heading="API" group="api">
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\": {
\"<key_name>\": \"$(
vault read -field password sys/policies/password/<policy_name>/generate
)\"
}
}" \
${VAULT_ADDR}/v1/<plugin_mount_path>/data/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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"
}
```
</CodeBlockConfig>
</Tab>
</Tabs>
## Step 4: Verify the data in Vault
<Tabs>
<Tab heading="CLI" group="cli">
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 <mount_path> \
-field <field_name> \
<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ vault kv get -mount shared -field seed1 dev/seeds
g0bc0b6W3ii^SXa@*ie5
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@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)
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>/data/<secret_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```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"
}
```
</CodeBlockConfig>
</Tab>
</Tabs>

278
website/content/docs/secrets/kv/kv-v2/setup.mdx Normal file
View file

@ -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
<Tabs>
<Tab heading="CLI" group="cli">
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 <mount_path> -version=2 kv
```
**Option 2**: Use the `kv-v2` plugin type:
```shell-session
$ vault secrets enable -path <mount_path> kv-v2
```
</Tab>
<Tab heading="GUI" group="gui">
@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.
</Tab>
<Tab heading="API" group="api">
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/<plugin_mount_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```json
{
"type": "kv",
"options": {
"version": "2"
}
}
```
</CodeBlockConfig>
<CodeBlockConfig hideClipboard="true">
```shell-session
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data @data.json \
${VAULT_ADDR}/v1/sys/mounts/shared | jq
```
</CodeBlockConfig>
`/sys/mounts/{plugin_mount_path}` does not return data on success.
</Tab>
</Tabs>
## Step 2: Create an ACL policy file
<Note>
ACL policies for `kv` plugins do not support the `allowed_parameters`,
`denied_parameters`, and `required_parameters` policy fields.
</Note>
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"]
}
```
<Tabs>
<Tab heading="Available path prefixes">
@include 'policies/path-prefixes.mdx'
</Tab>
<Tab heading="Available permissions">
@include 'policies/policy-permissions.mdx'
</Tab>
</Tabs>
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.
<CodeBlockConfig highlight="2">
```shell-session
$ vault kv patch \
-output-policy \
-mount <existing_mount_path> \
test-path \
test=test
```
</CodeBlockConfig>
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ vault kv patch \
-output-policy \
-mount private \
test-path \
test=test
path "private/data/test-path" {
capabilities = ["patch"]
}
```
</CodeBlockConfig>
## Step 3: Save the ACL policy
<Tabs>
<Tab heading="CLI" group="cli">
Use `vault policy write` to create a new ACL policy with the policy definition
file:
```shell-session
$ vault policy write <name> <path_to_policy_file>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ vault policy write "KV-access-policy" ./kv-policy.hcl
```
</CodeBlockConfig>
</Tab>
<Tab heading="GUI" group="gui">
@include 'gui-page-instructions/create-acl-policy.mdx'
- Provide a name for the policy and upload the policy definition file.
<Tip>
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.
</Tip>
</Tab>
<Tab heading="API" group="api">
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]"; "") }' <path_to_policy_file> |
curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
"$(</dev/stdin)" \
${VAULT_ADDR}/v1/sys/policy/<policy_name>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ jq -Rs '{ "policy": . | gsub("[\\r\\n\\t]"; "") }' ./kv-policy.hcl |
curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data "$(</dev/stdin)" \
${VAULT_ADDR}/v1/sys/policy/kv-access | jq
```
</CodeBlockConfig>
`/sys/mounts/{plugin_mount_path}` does not return data on success.
</Tab>
</Tabs>
## Next steps
- [Create an authentication mapping for the plugin](/vault/docs/concepts/policies#associating-policies)

108
website/content/docs/secrets/kv/kv-v2/upgrade.mdx Normal file
View file

@ -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.
<Warning>
You cannot access v1 plugin mounts during the upgrade, which may take a long
time for plugins that contain significant data.
</Warning>
## 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"]
}
```
<Tip>
You can assign different ACL policies to different `kv` v2 paths.
</Tip>
## Step 2: Upgrade the plugin instance
<Tabs>
<Tab heading="CLI" group="cli">
Use the `enable-versioning` subcommand to upgrade from v1 to v2:
```shell-session
$ vault kv enable-versioning <kv_v1_mount_path>
```
For example:
<CodeBlockConfig hideClipboard="true">
```shell-session
$ vault kv enable-versioning shared/
Success! Tuned the secrets engine at: shared/
```
</CodeBlockConfig>
</Tab>
<Tab heading="API" group="api">
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
```
</Tab>
</Tabs>
## 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.

10
website/content/partials/gui-page-instructions/select-kv-mount.mdx Normal file
View file

@ -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.

6
website/content/partials/policies/path-prefixes.mdx Normal file
View file

@ -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.

21
website/content/partials/policies/policy-permissions.mdx Normal file
View file

@ -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**.<br/>`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.
<Warning>
Data returned for a `list` operation **is not** filtered against ACL policies.
**Do not** encode sensitive information in key names.
</Warning>

59
website/data/docs-nav-data.json
View file

@ -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"
}
]
}
]
}
]
},

BIN
website/public/img/gui/kv/custom-metadata.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
website/public/img/gui/kv/delete-version.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
website/public/img/gui/kv/destroy-version.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
website/public/img/gui/kv/edit-metadata.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
website/public/img/gui/kv/patch-data.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
website/public/img/gui/kv/random-string.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
website/public/img/gui/kv/read-data.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
website/public/img/gui/kv/undelete-data.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
website/public/img/gui/kv/write-data.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 20 KiB