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
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: <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
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: <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
@ -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: <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.
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: <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.
- `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
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: <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.
- `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
(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: <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.
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: <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.
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: <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.
This is specified as part of the URL.
- `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.
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: <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.
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: <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.
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: <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.
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: <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.
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: <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
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: <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
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: <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.
This is specified as part of the URL.