mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 23:21:08 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
106 lines
4.2 KiB
Plaintext
106 lines
4.2 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: KV - Secrets Engines
|
|
description: The KV secrets engine can store arbitrary secrets.
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
|
|
|
# KV secrets engine
|
|
|
|
The `kv` secrets engine is a generic key-value store used to store arbitrary
|
|
secrets within the configured physical storage for Vault. This secrets engine
|
|
can run in one of two modes; store a single value for a key, or store a number
|
|
of versions for each key and maintain the record of them.
|
|
|
|
## KV version 1
|
|
|
|
When running the `kv` secrets engine non-versioned, it stores the most recently
|
|
written value for a key. Any update will overwrite the original value and not
|
|
recoverable. The benefits of non-versioned `kv` is a reduced storage size for
|
|
each key since no additional metadata or history is stored. Additionally, it
|
|
gives better runtime performance because the requests require fewer storage
|
|
calls and no locking.
|
|
|
|
Refer to the [KV version 1 Docs](/vault/docs/secrets/kv/kv-v1) for more
|
|
information.
|
|
|
|
## KV version 2
|
|
|
|
When running v2 of the `kv` secrets engine, a key can retain a configurable
|
|
number of versions. The default is 10 versions. The older versions' metadata and
|
|
data can be retrieved. Additionally, it provides check-and-set operations to
|
|
prevent overwriting data unintentionally.
|
|
|
|
When a version is deleted, the underlying data is not removed, rather it is
|
|
marked as deleted. Deleted versions can be undeleted. To permanently remove a
|
|
version's data, use the `vault kv destroy` command or the API endpoint. You can
|
|
delete all versions and metadata for a key by deleting the metadata using the
|
|
`vault kv metadata delete` command or the API endpoint with DELETE verb. You can
|
|
restrict who has permissions to soft delete, undelete, or fully remove data with
|
|
[Vault policies](/vault/docs/concepts/policies).
|
|
|
|
Refer to the [KV version 2 Docs](/vault/docs/secrets/kv/kv-v2) for more
|
|
information.
|
|
|
|
|
|
## Version comparison
|
|
|
|
Regardless of its version, you use the [`vault kv`](/vault/docs/commands/kv)
|
|
command to interact with KV secrets engine. However, the API endpoint are
|
|
different. You must be aware of those differences to write policies as intended.
|
|
|
|
The following table lists the `vault kv` sub-commands and their respective API
|
|
endpoints assuming the KV secrets engine is enabled at `secret/`.
|
|
|
|
|
|
| Command | KV v1 endpoint | KV v2 endpoint |
|
|
| ----------------- | ----------------- | ------------------------------ |
|
|
| `vault kv get` | secret/<key_path> | secret/**data**/<key_path> |
|
|
| `vault kv put` | secret/<key_path> | secret/**data**/<key_path> |
|
|
| `vault kv list` | secret/<key_path> | secret/**metadata**/<key_path> |
|
|
| `vault kv delete` | secret/<key_path> | secret/**data**/<key_path> |
|
|
|
|
In addition, KV v2 has sub-commands to handle versioning of secrets.
|
|
|
|
| Command | KV v2 endpoint |
|
|
| ------------------- | ------------------------------ |
|
|
| `vault kv patch` | secret/**data**/<key_path> |
|
|
| `vault kv rollback` | secret/**data**/<key_path> |
|
|
| `vault kv undelete` | secret/**undelete**/<key_path> |
|
|
| `vault kv destroy` | secret/**destroy**/<key_path> |
|
|
| `vault kv metadata` | secret/**metadata**/<key_path> |
|
|
|
|
|
|
To reduce confusion, the CLI command outputs the secret path when you are
|
|
working with KV v2.
|
|
|
|
**Example:**
|
|
|
|
<CodeBlockConfig hideClipboard highlight="4">
|
|
|
|
```shell-session
|
|
$ vault kv put secret/web-app api-token="WEOIRJ13895130WENJWEFN"
|
|
|
|
=== Secret Path ===
|
|
secret/data/web-app
|
|
|
|
======= Metadata =======
|
|
Key Value
|
|
--- -----
|
|
created_time 2024-07-02T00:34:58.074825Z
|
|
custom_metadata <nil>
|
|
deletion_time n/a
|
|
destroyed false
|
|
version 1
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
You can use `-mount` flag if omitting `/data/` in the CLI command is confusing.
|
|
|
|
```shell-session
|
|
$ vault kv put -mount=secret web-app api-token="WEOIRJ13895130WENJWEFN"
|
|
```
|