Dev server
An in-memory teaching server; it is never a production topology.
Chapter contract
Prerequisites:
Docker with Compose, Vault CLI, jq, curl, OpenSSL, and Python 3.
User-visible outcome:
Priya can use a constrained local identity and reset the lab without exposing bootstrap material.
Learning objectives
- Start and stop the shared lab repeatably.
- Use a constrained learner token instead of handling the root token manually.
- Verify identity and capabilities without displaying secret data.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | Defines consumption, validation, reload, and stop-using behavior. |
| Platform team owns | Provides trusted runtime identity, protected delivery, network, and telemetry. |
| Vault owns | Operates auth mounts, policies, engines, audit, and recovery. |
Core concepts
OIDC login
In a shared environment, Priya proves identity in the browser and Vault maps approved claims to policies. The platform owns OIDC configuration.
Constrained lab token
A finite teaching identity with only the learner policy; it stands in for OIDC without adding an identity provider.
Idempotence
Repeated setup converges instead of multiplying resources.
Commands and configuration
cd learn-vault/labs/bootstrap
./setup.sh
source ../../.runtime/learner.env
vault token lookup -format=json | jq '{policies:.data.policies,ttl:.data.ttl}'
vault token capabilities lockbox-kv/data/orders-apiPlatform-team supplied context: approved OIDC environment
export VAULT_ADDR=https://vault.example.internal:8200
export VAULT_CACERT=/approved/path/vault-ca.crt
vault login -method=oidc -path=oidc -no-print role=developer
vault token lookup -format=json | jq '{policies:.data.policies,ttl:.data.ttl}'-no-print stores the token through the configured token helper without displaying it. Do not use -no-store here because that option must print the token to make it usable.
Secret-safety stop
Stop: This lab uses local HTTP and Vault dev mode only on 127.0.0.1 with disposable data. Neither choice belongs in production.
Failure drill
| Symptom | vault status cannot connect. |
|---|---|
| Likely causes | Docker stopped, port 8200 occupied, or VAULT_ADDR points elsewhere. |
| Inspect safely | Run docker compose ps, inspect port ownership, and print only VAULT_ADDR. |
| Do not print | bootstrap.env, learner.env, token files, or container environment. |
Break it / fix it
Break it: Point VAULT_ADDR at an unused local port.
Show diagnosis and fix
Fix it: Restore the loopback lab address, confirm Compose health, then repeat metadata-only login checks.
Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.
Try it
Bootstrap boundary
labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.
Cost:
$0; local containers only
Starting state:
Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.
User actions:
Run setup twice to prove idempotence, then use the separate human-user lab to inspect identity and prove an expected authorization denial.
cd learn-vault/labs/bootstrap
./setup.sh
./setup.sh
cd ../human-user
./inspect-identity.sh
./expected-denial.shSuccess criteria:
Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.
Troubleshooting:
Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.
Verify
- The second setup run succeeds without duplicate-mount errors.
- Token lookup contains lockbox-learner and a finite TTL.
- The privileged action is denied.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Run ./cleanup.sh when finishing a session. Re-running setup reconstructs all disposable state.
Project Lockbox increment
Tracked examples are separated from generated credentials and renders under ignored learn-vault/.runtime.
Quick check
Why not export the root token manually?
History, process inspection, copy-paste, and screenshots make it easy to leak.
Why run setup twice?
It verifies repeatable recovery for another learning session.
Why is local HTTP bounded here?
It is loopback-only and carries disposable lab data.
What is the clean reset?
Run cleanup, then setup again.
Gotchas
- A new shell must source learner.env again.
- Dev-server logs can expose bootstrap details, so service logging is disabled.
- Deleting containers alone can leave volumes; use cleanup.
Recap and next
A safe tutorial treats its bootstrap credentials as secrets and makes reset cheaper than manual repair.