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.326204209Zcustom_metadata    <nil>deletion_time      n/adestroyed          falseversion            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=5678Error 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-apiCode: 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.128442898Zcustom_metadata    <nil>deletion_time      n/adestroyed          falseversion            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"}