add patch section to kv-v2 api and CLI docs (hashicorp#12689)

* add data patch section to kv-v2 api docs * fix trucated output for kv put command with cas cmd in kv-v2 docs * wip vault kv patch CLI docs * add new flags to 'vault kv patch' CLI command docs * fix cas_required formatting Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * fix cas formatting Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * additional format fixes Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
qk4l · Feb 4, 2022 · f3854a8 · f3854a8
1 parent 764fdfb
commit f3854a8
Show file tree

Hide file tree

Showing 3 changed files with 165 additions and 15 deletions.
diff --git a/website/content/api-docs/secret/kv/kv-v2.mdx b/website/content/api-docs/secret/kv/kv-v2.mdx
@@ -194,6 +194,71 @@ $ curl \
 }
 ```
 
+## Patch Secret
+
+This endpoint provides the ability to patch an _existing_ secret at the specified
+location. The secret must neither be deleted nor destroyed. The calling token must
+have an ACL policy granting the `patch` capability. Currently, only
+[JSON merge patch](https://datatracker.ietf.org/doc/html/draft-ietf-appsawg-json-merge-patch-07)
+is supported and must be specified using a `Content-Type` header value of
+`application/merge-patch+json`. A new version will be created upon successfully
+applying a patch with the provided data.
+
+| Method  | Path                 |
+| :------ | :------------------- |
+| `PATCH` | `/secret/data/:path` |
+
+### Parameters
+
+- `options` `(Map: <optional>)` – An object that holds option settings.
+
+- `cas` `(int: <optional>)` - This flag is required if `cas_required` is set to true on either
+  the secret or the engine's config. In order for a write to be successful, `cas` must be set
+  to the current version of the secret. A patch operation must be attempted on an existing
+  key, thus the provided `cas` value must be greater than 0.
+
+- `data` `(Map: <required>)` – The contents of the data map will be applied as a partial
+  update to the existing entry via a JSON merge patch to the existing entry.
+
+### Sample Payload
+
+```json
+{
+  "options": {
+    "cas": 1
+  },
+  "data": {
+    "foo": "a",
+    "bar": {
+      "baz": "b",
+    },
+  }
+}
+```
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --header "Content-Type: application/merge-patch+json"
+    --request PATCH \
+    --data @payload.json \
+    https://127.0.0.1:8200/v1/secret/data/my-secret
+```
+
+### Sample Response
+
+```json
+{
+  "data": {
+    "created_time": "2021-09-10T15:26:08.684999Z",
+    "deletion_time": "",
+    "destroyed": false,
+    "version": 2
+  }
+}
+
 ## Delete Latest Version of Secret
 
 This endpoint issues a soft delete of the secret's latest version at the

diff --git a/website/content/docs/commands/kv/patch.mdx b/website/content/docs/commands/kv/patch.mdx
@@ -54,9 +54,6 @@ $ echo "abcd1234" | vault kv patch secret/foo bar=-
 
 ## Usage
 
-There are no flags beyond the [standard set of flags](/docs/commands)
-included on all commands.
-
 ### Output Options
 
 - `-field` `(string: "")` - Print only the field with the given name. Specifying
@@ -67,3 +64,18 @@ included on all commands.
 - `-format` `(string: "table")` - Print the output in the given format. Valid
   formats are "table", "json", or "yaml". This can also be specified via the
   `VAULT_FORMAT` environment variable.
+
+### Command Options
+
+- `-method` `(string: "patch")` - Specifies the patch method to use. Valid
+  methods are `patch` and `rw`. The `patch` method uses an HTTP `PATCH` request
+  to apply the partial update. The `rw` method will fetch the secret's data,
+  perform an in-memory update, and write the updated data.
+
+- `-cas` `(int: 0)` - Specifies the value to use for the Check-And-Set operation.
+  This flag will only be used for the `patch` method. This flag is required if
+  `cas_required` is set to `true` on either the secret or the engine's config.
+  In order for a `patch` to be successful, `-cas` must be set to the current
+  version of the secret. This flag will be ignored for the `rw` method.
+  Instead, its value will be derived from fetching the current version of the
+  secret.
diff --git a/website/content/docs/secrets/kv/kv-v2.mdx b/website/content/docs/secrets/kv/kv-v2.mdx
@@ -15,7 +15,9 @@ non-string values by writing the key/value pairs to Vault from a JSON file or
 using the HTTP API.
 
 This secrets engine honors the distinction between the `create` and `update`
-capabilities inside ACL policies.
+capabilities inside ACL policies. The `patch` capability is also supported
+which is used to represent partial updates whereas the `update` capability
+represents full overwrites.
 
 ## Setup
 
@@ -168,7 +170,7 @@ allows for writing keys with arbitrary values.
 1. Write arbitrary data:
 
    ```text
-   $ vault kv put secret/my-secret my-value=s3cr3t
+   $ vault kv put secret/my-secret foo=a bar=b
    Key              Value
    ---              -----
    created_time     2019-06-19T17:20:22.985303Z
@@ -192,7 +194,7 @@ allows for writing keys with arbitrary values.
    ====== Data ======
    Key         Value
    ---         -----
-   my-value    s3cr3t
+   foo         a
    ```
 
 1. Write another version, the previous version will still be accessible. The
@@ -203,13 +205,13 @@ allows for writing keys with arbitrary values.
    cas parameter.
 
    ```text
-   $ vault kv put -cas=1 secret/my-secret my-value=new-s3cr3t
-   e
-   -
-   Z
-   a
-   e
-   2
+   $ vault kv put -cas=1 secret/my-secret foo=aa bar=bb
+   Key              Value
+   ---              -----
+   created_time     2019-06-19T17:22:23.369372Z
+   deletion_time    n/a
+   destroyed        false
+   version          2
    ```
 
 1. Reading now will return the newest version of the data:
@@ -227,7 +229,77 @@ allows for writing keys with arbitrary values.
    ====== Data ======
    Key         Value
    ---         -----
-   my-value    new-s3cr3t
+   foo         aa
+   bar         bb
+   ```
+
+1. Partial updates can be accomplished using the `vault kv patch` command. An
+   command will initially attempt an HTTP `PATCH` request which requires the
+   `patch` ACL capability. The `PATCH` request will fail if the the token used
+   is associated with a policy that does not contain the `patch` capability. In
+   this case the command will perform a read, local update, and subsequent write
+   which require both the `read` and `update` ACL capabilities.
+
+   The `-cas` flag can optionally be passed to perform a check-and-set operation.
+   It will only be used in the case of the initial `PATCH` request. The
+   read-then-write flow will use the `version` value from the secret returned by
+   the read to perform a check-and-set operation in the subsequent write.
+
+   ```text
+   $ vault kv patch -cas=2 secret/my-secret bar=bbb
+   Key              Value
+   ---              -----
+   created_time     2019-06-19T17:23:49.199802Z
+   deletion_time    n/a
+   destroyed        false
+   version          3
+   ```
+
+1. The `vault kv patch` command also supports a `-method` flag which can be
+   used to specify HTTP `PATCH` or read-then-write. The supported values are
+   `patch` and `rw` for HTTP `PATCH` and read-then-write, respectively.
+
+   Perform a patch using the `patch` method:
+
+      ```text
+      $ vault kv patch -method=patch -cas=2 secret/my-secret bar=bbb
+      Key              Value
+      ---              -----
+      created_time     2019-06-19T17:23:49.199802Z
+      deletion_time    n/a
+      destroyed        false
+      version          3
+      ```
+
+   Perform a patch using the read-then-write method:
+   ```text
+   $ vault kv patch -method=rw secret/my-secret bar=bbb
+   Key              Value
+   ---              -----
+   created_time     2019-06-19T17:23:49.199802Z
+   deletion_time    n/a
+   destroyed        false
+   version          3
+   ```
+
+1. Reading after a patch will return the newest version of the data in which
+   only the specified fields were updated:
+
+   ```text
+   $ vault kv get secret/my-secret
+   ====== Metadata ======
+   Key              Value
+   ---              -----
+   created_time     2019-06-19T17:23:49.199802Z
+   deletion_time    n/a
+   destroyed        false
+   version          3
+
+   ====== Data ======
+   Key         Value
+   ---         -----
+   foo         aa
+   bar         bbb
    ```
 
 1. Previous versions can be accessed with the `-version` flag:
@@ -245,7 +317,8 @@ allows for writing keys with arbitrary values.
    ====== Data ======
    Key         Value
    ---         -----
-   my-value    s3cr3t
+   foo         a
+   bar         b
    ```
 
 ### Deleting and Destroying Data