luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

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
This commit is contained in:
Violet Hynes 2023-03-17 12:21:55 -04:00 committed by GitHub
parent da72adcc4c
commit 31f764b82b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 96 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
website/content/api-docs/secret/kv/kv-v2.mdx
View File

@ -11,22 +11,20 @@ versioned mode. For general information about the usage and operation of the kv
secrets engine, please see the [Vault kv secrets engine, please see the [Vault kv
documentation](/vault/docs/secrets/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 ## Configure the KV Engine
This path configures backend level settings that are applied to every key in the This path configures backend level settings that are applied to every key in the
key-value store. key-value store.
| Method | Path | | Method | Path |
| :----- | :--------------- | |:-------|:-----------------------------|
| `POST` | `/secret/config` | | `POST` | `/:secret-mount-path/config` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - 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 - `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. 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 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 This path retrieves the current configuration for the secrets backend at the
given path. given path.
| Method | Path | | Method | Path |
| :----- | :--------------- | |:-------|:-----------------------------|
| `GET` | `/secret/config` | | `GET` | `/:secret-mount-path/config` |
### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount to read the config,
of, such as `secret`. This is specified as part of the URL.
### Sample Request ### 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 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). the associated [metadata endpoint](/vault/api-docs/secret/kv/kv-v2#read-secret-metadata).
| Method | Path | | Method | Path |
| :----- | :------------------------------------------- | |:-------|:---------------------------------------------------------|
| `GET` | `/secret/data/:path?version=:version-number` | | `GET` | `/:secret-mount-path/data/:path?version=:version-number` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to read, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to read. - `path` `(string: <required>)` – Specifies the path of the secret to read.
This is specified as part of the URL. This is specified as part of the URL.
- `version` `(int: 0)` - Specifies the version to return. If not set the latest - `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 the `create` capability. If the value already exists, the calling token must
have an ACL policy granting the `update` capability. have an ACL policy granting the `update` capability.
| Method | Path | | Method | Path |
| :----- | :------------------- | |:-------|:---------------------------------|
| `POST` | `/secret/data/:path` | | `POST` | `/:secret-mount-path/data/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to update, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to update.
This is specified as part of the URL.
- `options` `(Map: <optional>)` – An object that holds option settings. - `options` `(Map: <optional>)` – An object that holds option settings.
- `cas` `(int: <optional>)` - This flag is required if `cas_required` is set - `cas` `(int: <optional>)` - 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 `application/merge-patch+json`. A new version will be created upon successfully
applying a patch with the provided data. applying a patch with the provided data.
| Method | Path | | Method | Path |
| :------ | :------------------- | |:--------|:---------------------------------|
| `PATCH` | `/secret/data/:path` | | `PATCH` | `/:secret-mount-path/data/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to patch, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to patch.
This is specified as part of the URL.
- `options` `(Map: <optional>)` – An object that holds option settings. - `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 - `cas` `(int: <optional>)` - 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 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`. (i.e. non-map keys or map keys with no underlying subkeys) with `null`.
| Method | Path | | Method | Path |
| :----- | :---------------------- | |:-------|:------------------------------------|
| `GET` | `/secret/subkeys/:path` | | `GET` | `/:secret-mount-path/subkeys/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to read, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to read. - `path` `(string: <required>)` – Specifies the path of the secret to read.
This is specified as part of the URL. This is specified as part of the URL.
- `version` `(int: 0)` - Specifies the version to return. If not set the latest - `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 | | Method | Path |
| :------- | :------------------- | | :------- | :------------------- |
| `DELETE` | `/secret/data/:path` | | `DELETE` | `/:secret-mount-path/data/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to delete, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to delete. - `path` `(string: <required>)` – Specifies the path of the secret to delete.
This is specified as part of the URL. 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 but the underlying data will not be removed. A delete can be undone using the
`undelete` path. `undelete` path.
| Method | Path | | Method | Path |
| :----- | :--------------------- | |:-------|:-----------------------------------|
| `POST` | `/secret/delete/:path` | | `POST` | `/:secret-mount-path/delete/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to delete, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to delete. - `path` `(string: <required>)` – Specifies the path of the secret to delete.
This is specified as part of the URL. This is specified as part of the URL.
- `versions` `([]int: <required>)` - The versions to be deleted. The versioned - `versions` `([]int: <required>)` - 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. 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. This restores the data, allowing it to be returned on get requests.
| Method | Path | | Method | Path |
| :----- | :----------------------- | |:-------|:-------------------------------------|
| `POST` | `/secret/undelete/:path` | | `POST` | `/:secret-mount-path/undelete/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to undelete, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to undelete. - `path` `(string: <required>)` – Specifies the path of the secret to undelete.
This is specified as part of the URL. 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 Permanently removes the specified version data for the provided key and version
numbers from the key-value store. numbers from the key-value store.
| Method | Path | | Method | Path |
| :----- | :---------------------- | |:-------|:------------------------------------|
| `POST` | `/secret/destroy/:path` | | `POST` | `/:secret-mount-path/destroy/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to destroy, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to destroy. - `path` `(string: <required>)` – Specifies the path of the secret to destroy.
This is specified as part of the URL. 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 sensitive information in key names. The values themselves are not accessible via
this command. this command.
| Method | Path | | Method | Path |
| :----- | :----------------------- | |:-------|:-------------------------------------|
| `LIST` | `/secret/metadata/:path` | | `LIST` | `/:secret-mount-path/metadata/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to list, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secrets to list. - `path` `(string: <required>)` – Specifies the path of the secrets to list.
This is specified as part of the URL. 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 This endpoint retrieves the metadata and versions for the secret at the
specified path. Metadata is version-agnostic. specified path. Metadata is version-agnostic.
| Method | Path | | Method | Path |
| :----- | :----------------------- | |:-------|:-------------------------------------|
| `GET` | `/secret/metadata/:path` | | `GET` | `/:secret-mount-path/metadata/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to read, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to read. - `path` `(string: <required>)` – Specifies the path of the secret to read.
This is specified as part of the URL. 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. This endpoint creates or updates the metadata of a secret at the specified location.
It does not create a new version. It does not create a new version.
| Method | Path | | Method | Path |
| :----- | :----------------------- | |:-------|:-------------------------------------|
| `POST` | `/secret/metadata/:path` | | `POST` | `/:secret-mount-path/metadata/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to update, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – 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 - `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 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 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 using a `Content-Type` header value of `application/merge-patch+json`. It does
not create a new version. not create a new version.
| Method | Path | | Method | Path |
| :------ | :----------------------- | |:--------|:-------------------------------------|
| `PATCH` | `/secret/metadata/:path` | | `PATCH` | `/:secret-mount-path/metadata/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to patch, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – 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 - `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 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 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. specified key. All version history will be removed.
| Method | Path | | Method | Path |
| :------- | :----------------------- | |:---------|:-------------------------|
| `DELETE` | `/secret/metadata/:path` | | `DELETE` | `/secret/metadata/:path` |
### Parameters ### Parameters
- `secret-mount-path` `(string: <required>)` - The path to the KV mount containing
the secret to delete, such as `secret`. This is specified as part of the URL.
- `path` `(string: <required>)` – Specifies the path of the secret to delete. - `path` `(string: <required>)` – Specifies the path of the secret to delete.
This is specified as part of the URL. This is specified as part of the URL.