scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-03 12:07:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update KV-V2 docs to explicitly call out the secret mount path as a parameter (#19607)

Browse Source 
* 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 f509ef6274
commit fdf4d07fb3
1 changed files with 96 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
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` |
|:-------|:-----------------------------|
| `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
@@ -66,8 +64,13 @@ This path retrieves the current configuration for the secrets backend at the
given 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
@@ -98,11 +101,13 @@ is included in the response whether or not the calling token has `read` access t
the associated [metadata endpoint](/vault/api-docs/secret/kv/kv-v2#read-secret-metadata).
| Method | Path |
| :----- | :------------------------------------------- |
| `GET` | `/secret/data/:path?version=:version-number` |
|:-------|:---------------------------------------------------------|
| `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
@@ -146,11 +151,17 @@ 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` |
|:-------|:---------------------------------|
| `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
@@ -217,11 +228,17 @@ is supported and must be specified using a `Content-Type` header value of
applying a patch with the provided data.
| Method | Path |
| :------ | :------------------- |
| `PATCH` | `/secret/data/: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
@@ -284,11 +301,13 @@ 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` |
|:-------|:------------------------------------|
| `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.
@@ -372,11 +393,13 @@ but the underlying data will not be removed. A delete can be undone using the
`undelete` path.
| Method | Path |
| :----- | :--------------------- |
| `POST` | `/secret/delete/: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
@@ -407,11 +430,14 @@ 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` |
|:-------|:-------------------------------------|
| `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.
@@ -442,11 +468,14 @@ Permanently removes the specified version data for the provided key and version
numbers from the key-value store.
| Method | Path |
| :----- | :---------------------- |
| `POST` | `/secret/destroy/: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.
@@ -480,11 +509,14 @@ sensitive information in key names. The values themselves are not accessible via
this command.
| Method | Path |
| :----- | :----------------------- |
| `LIST` | `/secret/metadata/: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.
@@ -517,11 +549,14 @@ This endpoint retrieves the metadata and versions for the secret at the
specified path. Metadata is version-agnostic.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/secret/metadata/: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.
@@ -577,11 +612,17 @@ This endpoint creates or updates the metadata of a secret at the specified locat
It does not create a new version.
| Method | Path |
| :----- | :----------------------- |
| `POST` | `/secret/metadata/: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
@@ -635,11 +676,17 @@ using a `Content-Type` header value of `application/merge-patch+json`. It does
not create a new version.
| Method | Path |
| :------ | :----------------------- |
| `PATCH` | `/secret/metadata/: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.