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.

Assumptions

You have set up a kv v2 plugin.
Your authentication token has appropriate permissions for the kv v2 plugin:
- patch permission to make direct updates with PATCH actions.
- create+update permission if you want to make indirect updates with the Vault CLI by combining GET and POST actions.
You know the keys or subkeys you want to patch.

Use the vault kv patch command and set the -cas flag to the expected data version to perform a check-and-set operation before applying the patch:

$ vault kv patch                 \
   -cas <target_version>         \
   -max-versions <max_versions>  \
   -mount <mount_path>           \
   <secret_path>                 \
   <key_name>=<key_value>

For example:

$ 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

If the -cas version is older than the current version of data at the target path, the patch fails:

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

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

Appropriate Vault Enterprise license required

Open the data page for your kv plugin:
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. Select the mount path for your kv plugin.
5. Click through the path segments to select the relevant secret path.
6. Select the Secret tab

Click Patch latest 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

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.

Make a PATCH call to /{plugin_mount_path}/data/{secret_path} with the JSON data file and the Content-Type header set to application/merge-patch+json:

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

{
  "options": {
    "cas": 4
  },
  "data": {
    "smoke": "efgh"
  }
}

$ 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"
}