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 to make indirect updates by combining GET and POST actions.

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.

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.

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

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