Agent Injector
Admission adds Agent containers and shared volumes.
Chapter contract
Prerequisites:
Chapter 13 complete and familiarity with pod volumes and application reload behavior.
User-visible outcome:
The team selects one Kubernetes delivery model with explicit auth, renewal, delivery, and reload owners.
Learning objectives
- Compare Agent Injector, CSI, Vault Secrets Operator, and direct API.
- Name who authenticates, renews, renders, syncs, and reloads.
- Select the minimum mechanism satisfying Lockbox requirements.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | States the consumer contract and proves reload and degraded behavior. |
| Platform team owns | Owns runtime identity, integration components, rollout, and operational health. |
| Vault owns | Owns server-side trust, policy, engines, audit, and Vault service health. |
Core concepts
CSI provider
Mounts data through the Secrets Store CSI Driver lifecycle.
Vault Secrets Operator
Reconciles Vault data into Kubernetes resources.
Direct API
Application owns login, renewal, retries, cache, and telemetry.
Commands and configuration
cd learn-vault/labs/kubernetes-delivery
python3 decision_matrix.py --requirements requirements.json
python3 validate_examples.pyOptional approved context: client-side kubectl dry-run can supplement the offline checks, but it may still contact the current API server for discovery or schema validation.
Secret-safety stop
Stop: Syncing to a Kubernetes Secret creates another durable copy with separate RBAC, etcd encryption, backup, watch, and deletion lifecycle.
Failure drill
| Symptom | Integration is healthy but the pod uses stale material. |
|---|---|
| Likely causes | Volume updated without reload, template stopped, synced Secret not remounted, or cache too old. |
| Inspect safely | Check component status, inode, mtime, resource version, generation, and reload result. |
| Do not print | Volume contents, Secret data, sink token, node log payloads, or API responses. |
Break it / fix it
Break it: Assume an updated CSI volume automatically reloads the process.
Show diagnosis and fix
Fix it: Add and verify an application watcher or choose an integration with the required template contract.
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
Platform-supplied external configuration is represented by reserved example inputs; this lab applies nothing.
Cost:
$0; offline validation with no external resource changes
Starting state:
Use the tracked example and offline validator; real GitLab, AWS, and Kubernetes configuration remains platform-owned.
User actions:
Run the Lockbox decision matrix and statically validate minimal Injector and CSI examples.
cd learn-vault/labs/kubernetes-delivery
python3 decision_matrix.py --requirements requirements.json | tee ../../.runtime/delivery-decision.txt
grep -q '^selected: agent-injector$' ../../.runtime/delivery-decision.txt
python3 validate_examples.py
rm -f ../../.runtime/delivery-decision.txtSuccess 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
- One owner is named for auth, renewal, delivery, and reload.
- Selected delivery supports file templates and active reload without a Kubernetes Secret.
- Example manifests pass offline validation.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Remove the runtime decision output. Offline checks create no cluster resources.
Project Lockbox increment
Lockbox selects Agent Injector for file templates plus app reload; CSI remains valid for volume-native consumers.
Quick check
Which has most app coupling?
Direct API.
Does CSI guarantee reload?
No. The application must detect and accept updates.
What appears when syncing a Secret?
Kubernetes API, etcd, RBAC, controllers, backups, and watchers.
Why does Injector fit here?
Agent owns auth and templates while the app owns a small reload contract.
Gotchas
- Admission failure can block pod creation.
- SubPath mounts do not receive normal projected updates.
- Secret environment variables do not update in running processes.
Recap and next
Choose integration by who owns every lifecycle step and how component failure reaches the application.