From 31f764b82b886dc350d9d755815feb434bc3e2a8 Mon Sep 17 00:00:00 2001 From: Violet Hynes Date: Fri, 17 Mar 2023 12:21:55 -0400 Subject: [PATCH] Update KV-V2 docs to explicitly call out the secret mount path as a parameter (#19607) * Update KV-V2 docs to explicitly call out the secret mount path as a parameter * Missed some angular brackets * remove wishy language --- website/content/api-docs/secret/kv/kv-v2.mdx | 142 +++++++++++++------ 1 file changed, 96 insertions(+), 46 deletions(-) diff --git a/website/content/api-docs/secret/kv/kv-v2.mdx b/website/content/api-docs/secret/kv/kv-v2.mdx index 9786117c6..2c23422a9 100644 --- a/website/content/api-docs/secret/kv/kv-v2.mdx +++ b/website/content/api-docs/secret/kv/kv-v2.mdx @@ -11,22 +11,20 @@ versioned mode. For general information about the usage and operation of the kv secrets engine, please see the [Vault kv documentation](/vault/docs/secrets/kv). -~> Note: This documentation assumes the kv secrets engine is enabled at the -`/secret` path in Vault and that versioning has been enabled. Since it is -possible to enable secrets engines at any location, please update your API calls -accordingly. - ## Configure the KV Engine This path configures backend level settings that are applied to every key in the key-value store. -| Method | Path | -| :----- | :--------------- | -| `POST` | `/secret/config` | +| Method | Path | +|:-------|:-----------------------------| +| `POST` | `/:secret-mount-path/config` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount to config, + such as `secret`. This is specified as part of the URL. + - `max_versions` `(int: 0)` – The number of versions to keep per key. This value applies to all keys, but a key's metadata setting can overwrite this value. Once a key has more than the configured allowed versions, the oldest version @@ -65,9 +63,14 @@ $ curl \ This path retrieves the current configuration for the secrets backend at the given path. -| Method | Path | -| :----- | :--------------- | -| `GET` | `/secret/config` | +| Method | Path | +|:-------|:-----------------------------| +| `GET` | `/:secret-mount-path/config` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount to read the config, + of, such as `secret`. This is specified as part of the URL. ### Sample Request @@ -97,12 +100,14 @@ specific. The `custom_metadata` field is part of the secret's key metadata and is included in the response whether or not the calling token has `read` access to the associated [metadata endpoint](/vault/api-docs/secret/kv/kv-v2#read-secret-metadata). -| Method | Path | -| :----- | :------------------------------------------- | -| `GET` | `/secret/data/:path?version=:version-number` | +| Method | Path | +|:-------|:---------------------------------------------------------| +| `GET` | `/:secret-mount-path/data/:path?version=:version-number` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to read, such as `secret`. This is specified as part of the URL. - `path` `(string: )` – Specifies the path of the secret to read. This is specified as part of the URL. - `version` `(int: 0)` - Specifies the version to return. If not set the latest @@ -145,12 +150,18 @@ the value does not yet exist, the calling token must have an ACL policy granting the `create` capability. If the value already exists, the calling token must have an ACL policy granting the `update` capability. -| Method | Path | -| :----- | :------------------- | -| `POST` | `/secret/data/:path` | +| Method | Path | +|:-------|:---------------------------------| +| `POST` | `/:secret-mount-path/data/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to update, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to update. + This is specified as part of the URL. + - `options` `(Map: )` – An object that holds option settings. - `cas` `(int: )` - This flag is required if `cas_required` is set @@ -216,12 +227,18 @@ 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` | +| Method | Path | +|:--------|:---------------------------------| +| `PATCH` | `/:secret-mount-path/data/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to patch, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to patch. + This is specified as part of the URL. + - `options` `(Map: )` – An object that holds option settings. - `cas` `(int: )` - This flag is required if `cas_required` is set to true on either @@ -283,12 +300,14 @@ at the requested 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 `null`. -| Method | Path | -| :----- | :---------------------- | -| `GET` | `/secret/subkeys/:path` | +| Method | Path | +|:-------|:------------------------------------| +| `GET` | `/:secret-mount-path/subkeys/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to read, such as `secret`. This is specified as part of the URL. - `path` `(string: )` – Specifies the path of the secret to read. This is specified as part of the URL. - `version` `(int: 0)` - Specifies the version to return. If not set the latest @@ -348,10 +367,12 @@ delete can be undone using the `undelete` path. | Method | Path | | :------- | :------------------- | -| `DELETE` | `/secret/data/:path` | +| `DELETE` | `/:secret-mount-path/data/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to delete, such as `secret`. This is specified as part of the URL. - `path` `(string: )` – Specifies the path of the secret to delete. This is specified as part of the URL. @@ -371,12 +392,14 @@ marks the versions as deleted and will stop them from being returned from reads, but the underlying data will not be removed. A delete can be undone using the `undelete` path. -| Method | Path | -| :----- | :--------------------- | -| `POST` | `/secret/delete/:path` | +| Method | Path | +|:-------|:-----------------------------------| +| `POST` | `/:secret-mount-path/delete/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to delete, such as `secret`. This is specified as part of the URL. - `path` `(string: )` – Specifies the path of the secret to delete. This is specified as part of the URL. - `versions` `([]int: )` - The versions to be deleted. The versioned @@ -406,12 +429,15 @@ $ curl \ Undeletes the data for the provided version and path in the key-value store. This restores the data, allowing it to be returned on get requests. -| Method | Path | -| :----- | :----------------------- | -| `POST` | `/secret/undelete/:path` | +| Method | Path | +|:-------|:-------------------------------------| +| `POST` | `/:secret-mount-path/undelete/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to undelete, such as `secret`. This is specified as part of the URL. + - `path` `(string: )` – Specifies the path of the secret to undelete. This is specified as part of the URL. @@ -441,12 +467,15 @@ $ curl \ Permanently removes the specified version data for the provided key and version numbers from the key-value store. -| Method | Path | -| :----- | :---------------------- | -| `POST` | `/secret/destroy/:path` | +| Method | Path | +|:-------|:------------------------------------| +| `POST` | `/:secret-mount-path/destroy/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to destroy, such as `secret`. This is specified as part of the URL. + - `path` `(string: )` – Specifies the path of the secret to destroy. This is specified as part of the URL. @@ -479,12 +508,15 @@ value. Note that no policy-based filtering is performed on keys; do not encode sensitive information in key names. The values themselves are not accessible via this command. -| Method | Path | -| :----- | :----------------------- | -| `LIST` | `/secret/metadata/:path` | +| Method | Path | +|:-------|:-------------------------------------| +| `LIST` | `/:secret-mount-path/metadata/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing +the secret to list, such as `secret`. This is specified as part of the URL. + - `path` `(string: )` – Specifies the path of the secrets to list. This is specified as part of the URL. @@ -516,12 +548,15 @@ entries. This endpoint retrieves the metadata and versions for the secret at the specified path. Metadata is version-agnostic. -| Method | Path | -| :----- | :----------------------- | -| `GET` | `/secret/metadata/:path` | +| Method | Path | +|:-------|:-------------------------------------| +| `GET` | `/:secret-mount-path/metadata/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to read, such as `secret`. This is specified as part of the URL. + - `path` `(string: )` – Specifies the path of the secret to read. This is specified as part of the URL. @@ -576,12 +611,18 @@ $ curl \ This endpoint creates or updates the metadata of a secret at the specified location. It does not create a new version. -| Method | Path | -| :----- | :----------------------- | -| `POST` | `/secret/metadata/:path` | +| Method | Path | +|:-------|:-------------------------------------| +| `POST` | `/:secret-mount-path/metadata/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to update, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to update. + This is specified as part of the URL. + - `max_versions` `(int: 0)` – The number of versions to keep per key. If not set, the backend’s configured max version is used. Once a key has more than the configured allowed versions, the oldest version will be permanently @@ -634,12 +675,18 @@ capability. Currently, only JSON merge patch is supported and must be specified using a `Content-Type` header value of `application/merge-patch+json`. It does not create a new version. -| Method | Path | -| :------ | :----------------------- | -| `PATCH` | `/secret/metadata/:path` | +| Method | Path | +|:--------|:-------------------------------------| +| `PATCH` | `/:secret-mount-path/metadata/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to patch, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to patch. + This is specified as part of the URL. + - `max_versions` `(int: 0)` – The number of versions to keep per key. If not set, the backend’s configured max version is used. Once a key has more than the configured allowed versions, the oldest version will be permanently @@ -687,11 +734,14 @@ This endpoint permanently deletes the key metadata and all version data for the specified key. All version history will be removed. | Method | Path | -| :------- | :----------------------- | +|:---------|:-------------------------| | `DELETE` | `/secret/metadata/:path` | ### Parameters +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to delete, such as `secret`. This is specified as part of the URL. + - `path` `(string: )` – Specifies the path of the secret to delete. This is specified as part of the URL.