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
In a nutshell
  • 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; -path overrides 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.

Client requestsecret/credsVault routermatches mount pathSecrets engineisolated viewEncrypted storage

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

CommandEffect
vault secrets enableEnable an engine at a path
vault secrets listList the enabled engines
vault secrets tuneChange settings such as TTLs
vault secrets moveChange the path; this revokes all secrets because leases are tied to the original path
vault secrets disableRevoke 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

CLI kv putVersion storedCLI kv getLatest version returnedAPI GET on the data pathSame data returned

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 of database/." 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; -path overrides 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 kv or kv-v2; the CLI uses -mount, the API path contains data/.
  • cubbyhole is on by default and cannot be disabled.
Watch out

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 the kv-v2 type.

  • 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.