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.

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:

path "secret/dev/team-1/*" {
  capabilities = ["create", "update", "read"]
}

becomes:

path "secret/data/dev/team-1/*" {
  capabilities = ["create", "update", "read"]
}

Tip

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:

$ vault kv enable-versioning <kv_v1_mount_path>

For example:

$ vault kv enable-versioning secret/
Success! Tuned the secrets engine at: secret/

Create a payload file for the request body to set version:

{
  "options": {
      "version": "2"
  }
}

Call the TuneMountConfiguration endpoint with the payload file:

$ curl                            \
    --header "X-Vault-Token: ..." \
    --request POST                \
    --data @payload.json          \
    http://${VAULT_ADDR}/v1/sys/mounts/${KV_MOUNT_PATH}/tune

KV v2 plugin API docs
Tutorial: Versioned Key Value Secrets Engine - Learn how to compare data in the KV v2 secrets engine and protect data from accidental deletion.

Upgrade kv version 1 plugins

Before you start

Step 1: Update ACL rules

Step 2: Upgrade the plugin instance

Related resources