Skip to content
Hands-on IT IT Drills

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=root

Expected (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 list

Expected (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/config

Expected:

======= 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-42

Expected (abridged):

version            2

Tip: The short form bao kv get secret/webshop/config works too. The CLI help, however, calls it “deprecated” because it hides the real API path secret/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/config

Expected (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/config

Expected (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 get no longer returns a Data block, but still exit code 0. In scripts, therefore, check deletion_time or .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; echo

Expected:

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/config

Expected (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/config

Expected:

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

Expected:

{"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/config shows 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 -dev in 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=@datei or - for stdin.
  • Set max_versions and delete_version_after per mount and manage them as code (Day 13).
  • -cas-required or cas_required prevents parallel writers from overwriting each other.
  • destroy and metadata delete are permanent. Protect them with a policy (Day 2).