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:

$ vault secrets enable -path <mount_path> -version=2 kv

Option 2: Use the kv-v2 plugin type:

$ vault secrets enable -path <mount_path> kv-v2

Open the Enable a Secrets Engine page:
1. Open the GUI for your Vault instance.
2. 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.
3. Select Secrets Engines from the left-hand menu.
4. Click Enable new engine + on the Secrets Engines page.

Select the "KV" plugin.
Enter a unique path for the plugin and provide the relevant configuration data.

Create a JSON file with the type and configuration information for your kv v2 instance. Use the options field to set optional flags.

Make a POST call to /sys/mounts/{plugin_mount_path} with the JSON data:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @data.json                         \
  ${VAULT_ADDR}/v1/sys/mounts/<plugin_mount_path>

For example:

{
  "type": "kv",
  "options": {
    "version": "2"
  }
}

$ 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

Note

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:

# 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"]
}

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.

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.

Warning

Data returned for a list operation is not filtered against ACL policies. Do not encode sensitive information in key names.

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.

$ vault kv patch                  \
    -output-policy                \
    -mount <existing_mount_path>  \
    test-path                     \
    test=test

For example:

$ 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:

$ vault policy write <name> <path_to_policy_file>

For example:

$ vault policy write "KV-access-policy" ./kv-policy.hcl

Open the Create ACL Policy page:
1. Open the GUI for your Vault instance.
2. Login under the namespace for the policy or select the namespace from the selector at the bottom of the left-hand menu and re-authenticate.
3. Select Policies from the left-hand menu.
4. Select ACL Policies from the left-hand menu.
5. Click Create ACL policy + on the ACL Policies page.

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.

Escape your policy file and make a POST call to /sys/policy/{policy_name} with your policy details:

$ 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:

$ 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

/sys/mounts/{plugin_mount_path} does not return data on success.

Next steps

Create an authentication mapping for the plugin