---
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 "shared/data/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.