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:
- Recommended read permission for subkeys of the secret path to read the key for the key/value pair to update.
- patch permission to make direct updates with PATCH actions.
- CLI only create+update permission to make indirect updates by combining GET and POST actions. CLI only

Use the vault read command to retrieve secret subkeys to list keys and select to update its value.

$ vault read <mount_path>/subkeys/<secret_path>

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:

If they key is unknown, a read request may be performed to return the secret's subkeys path. The secret entry at this path will be retrieved and stripped of all data by replacing underlying values of leaf keys (i.e. non-map keys or map keys with no underlying subkeys) with nil.

$  vault read shared/subkeys/dev/square-api     

Key         Value
---         -----
metadata    map[created_time:2024-11-13T21:52:10.326204209Z custom_metadata:<nil> deletion_time: destroyed:false version:1]
subkeys     map[prod:<nil>]

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