Secrets Engines · Topic 1 of 4
Purpose, Enabling and Accessing Secrets Engines
Vault Associate (003): what secrets engines are for, how to enable them with the CLI, API and UI, and how to read and write secrets with each interface.
- 5 min
- A secrets engine stores, generates or encrypts data; it is enabled at a path and Vault routes requests by that path.
- The default path is the engine type name;
-pathoverrides it, and paths are case-sensitive. - Enable, list, tune, move and disable are the lifecycle commands; disabling deletes the engine's stored data.
What it is
A secrets engine is a Vault component that stores, generates or encrypts data. It receives a request, acts on it and returns a result. Some engines store and read data, some generate credentials for other systems on demand, and some provide encryption as a service.
Each engine is enabled (mounted) at a path. Vault routes every request that starts with that path to the engine, so you work with an engine like a virtual filesystem using read, write and delete operations.
How it works
Paths and isolation
By default an engine is enabled at a path named after its type, so vault secrets enable aws mounts it at aws/. You can choose another path, and some engines can be enabled at several paths. Each instance is isolated from the others.
Paths are case-sensitive, so kv/ and KV/ are different mounts. Mount points cannot overlap: you cannot mount under an existing mount or create a mount that is a prefix of an existing one. For example foo/bar and foo/baz can coexist, but foo and foo/baz cannot.
Each engine gets its own isolated view of storage, so one engine cannot reach another engine's data.
Lifecycle commands
| Command | Effect |
|---|---|
vault secrets enable | Enable an engine at a path |
vault secrets list | List the enabled engines |
vault secrets tune | Change settings such as TTLs |
vault secrets move | Change the path; this revokes all secrets because leases are tied to the original path |
vault secrets disable | Revoke the engine's secrets, where supported, and delete all of its stored data |
The cubbyhole engine is enabled by default and cannot be disabled, moved or enabled multiple times.
Enabling an engine
vault secrets enable aws
vault secrets enable -path=ssh-prod ssh
vault secrets enable -max-lease-ttl=30m database
vault secrets enable -path=secret -version=2 kv
-path sets the mount path and must be unique among secrets engines. -description, -default-lease-ttl and -max-lease-ttl are also available. For KV version 2 you can use -version=2 kv or the shortcut type kv-v2.
With the API, send a POST to /sys/mounts/:path with the engine type in the body. Set options.version to "2" to mount KV v2; the default is "1".
curl --header "X-Vault-Token: $VAULT_TOKEN" \
--request POST \
--data '{"type": "kv", "options": {"version": "2"}}' \
$VAULT_ADDR/v1/sys/mounts/secret
Use GET /sys/mounts to list engines and DELETE /sys/mounts/:path to disable one. The UI can also enable and manage secrets engines.
Accessing secrets
With KV v2, the vault kv commands can take the mount with -mount, and they add data/ for you:
vault kv put -mount=secret creds passcode=my-long-passcode
vault kv get -mount=secret creds
vault kv get -mount=secret -version=1 creds
The API path for KV v2 includes data/. Read with GET /:mount/data/:path (add ?version=N for a specific version) and write with POST /:mount/data/:path using a body shaped like {"data": {...}}. Metadata lives under /:mount/metadata/:path.
For other engines use vault read and vault write. For example vault read aws/creds/my-role asks the AWS engine to generate credentials. Each engine defines its own paths, and vault path-help shows the paths an enabled engine responds to.
In the UI, select an enabled engine from the secrets engines list, then open a path to view a secret or create a new one.
How the exam asks about this
- "You need to see every mount that is active on a server." Run
vault secrets list. - "An engine must live at
prod-db/instead ofdatabase/." Enable it with-path=prod-db. - "Which API call enables an engine?" POST to
/sys/mounts/:path.
What to remember for the exam
- A secrets engine stores, generates or encrypts data; it is enabled at a path and Vault routes requests by that path.
- The default path is the engine type name;
-pathoverrides it, and paths are case-sensitive. - Enable, list, tune, move and disable are the lifecycle commands; disabling deletes the engine's stored data.
- Enable over the API with POST to
/sys/mounts/:path; list with GET/sys/mounts. - KV v2 is enabled with
-version=2 kvorkv-v2; the CLI uses-mount, the API path containsdata/. cubbyholeis on by default and cannot be disabled.
vault secrets disable is not a pause button. It revokes the engine's secrets where supported and deletes all of the data stored for that mount.
Common mistakes
Putting data/ in a KV v2 CLI command. The vault kv commands add it for you. The data/ prefix belongs to the API path and to policies, where it must appear explicitly.
Treating move as harmless. Moving an engine changes its path, and leases are tied to the original path, so all secrets are revoked. The configuration persists.
Mounting overlapping paths. foo and foo/baz conflict, so the second enable fails. Pick sibling paths such as foo/bar and foo/baz.
Check yourself
What does an engine's mount path do?
Vault routes every request with that path prefix to the engine, and the engine defines the paths beneath it.
How do you enable KV version 2 at
secret/from the CLI?Run
vault secrets enable -path=secret -version=2 kv, or use thekv-v2type.What happens to the stored data when you run
vault secrets disable?Vault revokes the engine's secrets where supported and deletes all of the engine's data from storage.
Topic 1 of 4 in Secrets Engines
Test yourself on Secrets Engines
The full HashiCorp Vault Associate 003 question bank has 600 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.