Day 1: Dev Server and KV v2
Goal: Write, version, delete and recover secrets in KV v2, via CLI and via API. · Duration: approx. 60 min · Prerequisite: Day 0
Briefing
- The dev server runs in RAM, is already unsealed and has
secret/as KV v2. After a restart all data is gone. - KV v2 stores every change as a new version. The API separates the
contents (
secret/data/…) from the metadata (secret/metadata/…). - You will need this separation for policies from Day 2 on.
secret/data/webshop/config -> contents (version n)
secret/metadata/webshop/config -> versions, max_versions, custom_metadata
secret/delete|undelete|destroy/ -> delete, recover, destroy versions
Drill 1: Start the Dev Server
Terminal 1:
bao server -dev -dev-root-token-id=rootExpected (abridged):
==> OpenBao server configuration:
Api Address: http://127.0.0.1:8200
Storage: inmem
Version: OpenBao v2.7.1, committed 2026-10-01T15:32:54Z
WARNING! dev mode is enabled! In this mode, OpenBao runs entirely in-memory
Unseal Key: vz52pbAft3HVEPB+8o4BV1GHJB5PXsmbw2/I2Ckol84=
Root Token: root
Terminal 2:
cd ~/bao-lab/tag01
export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root
bao status
bao secrets listExpected (abridged):
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
Total Shares 1
Threshold 1
Version 2.7.1
Commit Date 2026-10-01T15:32:54Z
Storage Type inmem
HA Enabled false
Path Type Accessor Description
---- ---- -------- -----------
cubbyhole/ cubbyhole cubbyhole_46e09526 per-token private secret storage
identity/ identity identity_5764417f identity store
secret/ kv kv_68a32e3c key/value secret storage
sys/ system system_0406b0f9 system endpoints used for control, ...
Save your progress? Sign up for free
Drill 2: Write, Read, Patch
bao kv put -mount=secret webshop/config db_user=webshop db_pass=lab-pw-1
bao kv get -mount=secret webshop/configExpected:
======= Secret Path =======
secret/data/webshop/config
======= Metadata =======
Key Value
--- -----
created_time 2026-10-08T06:58:26.847918Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
===== Data =====
Key Value
--- -----
db_pass lab-pw-1
db_user webshop
The values are lab secrets. put always replaces the
entire secret. patch changes only individual fields:
bao kv patch -mount=secret webshop/config api_key=lab-key-42Expected (abridged):
version 2
Tip: The short form
bao kv get secret/webshop/configworks too. The CLI help, however, calls it “deprecated” because it hides the real API pathsecret/data/…. Use-mount=.
Save your progress? Sign up for free
Drill 3: Output for Scripts
bao kv get -mount=secret -field=db_pass webshop/config; echo
bao kv get -mount=secret -format=json webshop/config | jq '.data.data'
bao kv get -mount=secret -format=json webshop/config | jq '.data.metadata.version'Expected:
lab-pw-1
{
"api_key": "lab-key-42",
"db_pass": "lab-pw-1",
"db_user": "webshop"
}
2
Why the echo? -field prints the value
without a trailing newline. That is ideal for $(…), but
ugly in the terminal.
Save your progress? Sign up for free
Drill 4: Versions
bao kv put -mount=secret webshop/config \
db_user=webshop db_pass=lab-pw-3 api_key=lab-key-42
bao kv get -mount=secret -version=1 -field=db_pass webshop/config; echo
bao kv metadata get -mount=secret webshop/configExpected (abridged):
lab-pw-1
======== Metadata Path ========
secret/metadata/webshop/config
============ Metadata ============
Key Value
--- -----
cas_required false
current_version 3
custom_metadata <nil>
delete_version_after 0s
max_versions 0
oldest_version 0
====== Version 1 ======
...
====== Version 3 ======
created_time 2026-10-08T06:58:27.32184Z
deletion_time n/a
destroyed false
max_versions 0 means: the mount default of 10 versions
applies.
Save your progress? Sign up for free
Drill 5: delete, undelete, destroy
bao kv delete -mount=secret webshop/config
bao kv get -mount=secret webshop/configExpected (abridged):
Success! Data deleted (if it existed) at: secret/data/webshop/config
======= Metadata =======
deletion_time 2026-10-08T06:58:33.145983Z
destroyed false
version 3
Warning: After a
delete,kv getno longer returns aDatablock, but still exit code 0. In scripts, therefore, checkdeletion_timeor.data.data == null.
delete is a soft delete. You can bring the version
back:
bao kv undelete -mount=secret -versions=3 webshop/config
bao kv get -mount=secret -field=db_pass webshop/config; echoExpected:
Success! Data written to: secret/undelete/webshop/config
lab-pw-3
destroy deletes permanently:
bao kv destroy -mount=secret -versions=1 webshop/config
bao kv get -mount=secret -version=1 webshop/configExpected (abridged):
Success! Data written to: secret/destroy/webshop/config
destroyed true
version 1
Save your progress? Sign up for free
Drill 6: Metadata and Rollback
bao kv metadata put -mount=secret -max-versions=5 -delete-version-after=720h \
-custom-metadata=owner=team-shop -custom-metadata=env=lab webshop/config
bao kv metadata get -mount=secret -format=json webshop/config \
| jq '.data | {max_versions, delete_version_after, custom_metadata}'Expected:
Success! Data written to: secret/metadata/webshop/config
{
"max_versions": 5,
"delete_version_after": "720h0m0s",
"custom_metadata": {
"env": "lab",
"owner": "team-shop"
}
}
A rollback writes the contents of an old version as a new version:
bao kv rollback -mount=secret -version=2 webshop/config
bao kv get -mount=secret -format=json webshop/config \
| jq -c '.data.data, .data.metadata.version'Expected (abridged):
custom_metadata map[env:lab owner:team-shop]
deletion_time 2026-11-07T06:58:33.667548Z
version 4
{"api_key":"lab-key-42","db_pass":"lab-pw-1","db_user":"webshop"}
4
Why does version 4 have a deletion_time? Because of
delete_version_after=720h, it will be deleted automatically
in 30 days.
Save your progress? Sign up for free
Drill 7: KV v1 and a Custom Mount
bao secrets enable -path=kv1 -version=1 kv
bao kv put -mount=kv1 webshop/config db_pass=lab-pw-1
bao kv get -mount=kv1 webshop/configExpected:
Success! Enabled the kv secrets engine at: kv1/
Success! Data written to: kv1/webshop/config
===== Data =====
Key Value
--- -----
db_pass lab-pw-1
| Feature | KV v1 | KV v2 |
|---|---|---|
| Versions, undelete, rollback | no | yes |
| API path for data | kv1/<pfad> |
<mount>/data/<pfad> |
| Metadata, check-and-set | no | yes |
A custom KV v2 mount for a team:
bao secrets enable -path=team-shop -version=2 -description="Webshop-Team" kv
bao kv put -mount=team-shop app/flags beta=true
bao secrets list -detailed | grep -E '^(Path|kv1|secret|team-shop)'Expected (abridged):
Path Plugin Accessor Default TTL Max TTL ...
kv1/ kv kv_6a873da7 system system ...
secret/ kv kv_68a32e3c system system ...
team-shop/ kv kv_87cf6012 system system ...
Save your progress? Sign up for free
Drill 8: The API with curl
curl -s -H "X-Vault-Token: $BAO_TOKEN" \
$BAO_ADDR/v1/secret/data/webshop/config | jq -c '.data.data'
curl -s -H "Authorization: Bearer $BAO_TOKEN" \
$BAO_ADDR/v1/secret/data/webshop/config | jq -c '.data.data'
curl -s -X POST -H "X-Vault-Token: $BAO_TOKEN" \
-d '{"data":{"db_user":"webshop","db_pass":"lab-pw-5"}}' \
$BAO_ADDR/v1/secret/data/webshop/config | jq -c '.data.version'
curl -s -H "X-Vault-Token: $BAO_TOKEN" \
"$BAO_ADDR/v1/secret/metadata/webshop?list=true" | jq -c .dataExpected:
{"api_key":"lab-key-42","db_pass":"lab-pw-1","db_user":"webshop"}
{"api_key":"lab-key-42","db_pass":"lab-pw-1","db_user":"webshop"}
5
{"keys":["config"]}
Even with OpenBao, the header is called X-Vault-Token.
There is no X-Bao-Token header:
curl -s -H "X-Bao-Token: $BAO_TOKEN" $BAO_ADDR/v1/secret/data/webshop/config
curl -s $BAO_ADDR/v1/sys/health | jq -c '{initialized, sealed, version}'Expected:
{"errors":["permission denied"]}
{"initialized":true,"sealed":false,"version":"2.7.1"}
Tip:
bao kv get -mount=secret -output-curl-string webshop/configshows you the matching curl command without running it.
Save your progress? Sign up for free
Checkpoint
ok() { "$@" >/dev/null 2>&1 && echo "✔ $*" || echo "✘ $*"; }
ok bao status
ok bao kv get -mount=secret webshop/config
ok bao kv get -mount=team-shop app/flags
[ "$(bao kv metadata get -mount=secret -format=json webshop/config \
| jq .data.max_versions)" = 5 ] && echo "✔ max_versions=5" || echo "✘ max_versions"
bao secrets list | grep -q '^kv1/' && echo "✔ kv1/" || echo "✘ kv1/"Challenge
Limit the entire team-shop/ mount to 3 versions. Then
write five versions of app/flags and prove that only
versions 3 to 5 still exist.
Hint: Settings for the entire mount live under
<mount>/config.
Solution
bao write team-shop/config max_versions=3
for i in 2 3 4 5; do bao kv put -mount=team-shop app/flags beta=$i >/dev/null; done
bao kv metadata get -mount=team-shop -format=json app/flags \
| jq -c '.data.versions | keys'Expected:
Success! Data written to: team-shop/config
["3","4","5"]
Save your progress? Sign up for free
Enterprise Note
- Never use
-devin production: storage in RAM, no TLS, a known root token. - Never pass secrets as arguments on the command line, otherwise they
end up in the shell history. Better:
bao kv put -mount=secret app/x db_pass=@dateior-for stdin. - Set
max_versionsanddelete_version_afterper mount and manage them as code (Day 13). -cas-requiredorcas_requiredprevents parallel writers from overwriting each other.destroyandmetadata deleteare permanent. Protect them with a policy (Day 2).