Auto-auth
Agent obtains and renews a token through a configured auth method.
Chapter contract
Prerequisites:
Chapter 7 complete, AppRole inputs present, and the Compose Agent profile available.
User-visible outcome:
orders-api receives an Agent-rendered file and proves freshness, permissions, and reload signaling.
Learning objectives
- Run Agent auto-auth with the lab AppRole.
- Render a minimal file with protected permissions.
- Detect freshness and trigger reload without logging content.
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
Template
A controlled rendering of selected Vault data.
Token sink
Protected token output; omit it unless another process needs it.
Reload command
A bounded hook run only after successful render.
Commands and configuration
cd learn-vault/labs/bootstrap
docker compose --profile agent up -d vault-agent
cd ../vault-agent
./wait-for-render.sh
./inspect-render.shSecret-safety stop
Stop: Agent reduces custom token code; it does not make rendered files non-secret. Protect destinations, backups, process access, and cleanup.
Failure drill
| Symptom | The app keeps old configuration while Agent is running. |
|---|---|
| Likely causes | Template error, policy denial, renewal failure, rename mismatch, or reload hook failure. |
| Inspect safely | Check Agent state, render mtime, error class, reload marker, and KV version. |
| Do not print | Rendered content, token sink, SecretID, or Agent environment. |
Break it / fix it
Break it: Stop Agent after the first render and let the file become stale.
Show diagnosis and fix
Fix it: Restore auto-auth, require a successful new render, then verify the application reload marker.
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:
Start the Agent profile, wait for a protected render and reload marker, then inspect mode, mtime, and schema keys only.
cd learn-vault/labs/bootstrap
docker compose --profile agent up -d vault-agent
cd ../vault-agent
./wait-for-render.sh
./inspect-render.sh
test -f ../../.runtime/reload.request
./cleanup.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 render exists with mode 0600.
- Inspection reports expected keys without values.
- The reload marker follows a successful render.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Stop the Agent profile and remove renders and markers; keep core services if continuing.
Project Lockbox increment
orders-api receives KV configuration through an Agent file-and-reload contract and exposes render age only.
Quick check
What does Agent remove from app code?
Token acquisition, renewal, and template retrieval mechanics.
Who owns reload correctness?
The application contract.
Is a token sink mandatory?
No. Omit it when no separate process needs the token.
What should health inspect?
Agent state, freshness, schema validity, and app acceptance.
Gotchas
- A reload command does not prove the application accepted data.
- Destination ownership and atomic rename semantics matter.
- Agent API proxy is deprecated in favor of Vault Proxy; auto-auth and templates remain Agent use cases.
Recap and next
Agent is a lifecycle sidecar, not an ownership shortcut: the app still defines valid, fresh, and reloadable.