Tag 5: Agent Injector
Ziel: Secrets per Annotation als Datei in den Pod bringen, das Audience-Problem sauber lösen und einen hängenden Init-Container in zwei Minuten diagnostizieren. · Dauer: ca. 90 min · Voraussetzung: Tag 2
Briefing
- Der Injector ist ein Mutating Webhook. Er hängt an annotierte Pods
einen Init-Container (
vault-agent-init) und einen Sidecar (vault-agent) an. - Beide laufen mit dem OpenBao-Image als Agent, melden sich per
Kubernetes-Auth an und rendern Templates in ein gemeinsames
emptyDirunter/vault/secrets. - Das Chart nutzt den Injector
hashicorp/vault-k8s. Darum heißen alle Annotationenvault.hashicorp.com/…, auch gegen OpenBao. - Die App sieht nur Dateien. Kein SDK, kein Token im App-Container.
kubectl apply ──> API-Server ──> Webhook openbao-agent-injector
│ patcht Pod
Pod shop-api: [vault-agent-init] ──> [app] + [vault-agent]
│ ▲ │ Re-Render
└── /vault/secrets (emptyDir) ┘
└── login auth/kubernetes (Rolle shop-api) ──> OpenBao
Drill 1: Den Injector kennenlernen
mkdir -p ~/secrets-lab/tag05 && cd ~/secrets-lab/tag05
kubectl -n openbao get deploy openbao-agent-injector \
-o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
kubectl -n openbao get deploy openbao-agent-injector -o json \
| jq -r '.spec.template.spec.containers[0].env[]
| select(.name | test("VAULT_(ADDR|IMAGE|AUTH_PATH)")) | "\(.name)=\(.value)"'
kubectl get mutatingwebhookconfiguration openbao-agent-injector-cfg \
-o jsonpath='{.webhooks[0].name} {.webhooks[0].failurePolicy}{"\n"}'Erwartet:
docker.io/hashicorp/vault-k8s:1.7.6
AGENT_INJECT_VAULT_ADDR=http://openbao.openbao.svc:8200
AGENT_INJECT_VAULT_AUTH_PATH=auth/kubernetes
AGENT_INJECT_VAULT_IMAGE=quay.io/openbao/openbao:2.7.1
vault.hashicorp.com Ignore
Der Webhook kommt von HashiCorp, der Agent ist OpenBao. Ein
openbao-spezifisches Annotations-Präfix gibt es in diesem Injector
nicht. Merke dir failurePolicy: Ignore, das wird in Drill 8
wichtig.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Erster Versuch – und er hängt
Die Pflicht-Annotationen: agent-inject,
role und pro Datei
agent-inject-secret-<name>. Der Dateiname ist
<name>, der Wert der API-Pfad (bei KV v2 mit
data/).
cp ~/secrets-lab/code/tag05/*.yaml .
grep vault.hashicorp 10-shop-api-naiv.yaml
kubectl apply -f 10-shop-api-naiv.yaml
sleep 20
kubectl -n shop get pod -l app=shop-apiErwartet:
vault.hashicorp.com/agent-inject: "true"
vault.hashicorp.com/role: "shop-api"
vault.hashicorp.com/agent-inject-secret-api: "secret/data/shop/api"
deployment.apps/shop-api created
NAME READY STATUS RESTARTS AGE
shop-api-8557c9d4cc-lsz2w 0/2 Init:0/1 0 25s
0/2 zeigt: Der Sidecar ist da, also hat der Webhook
gegriffen. Aber der Init-Container wird nicht fertig. Seine Logs sagen,
warum:
kubectl -n shop logs deploy/shop-api -c vault-agent-init | grep -A7 ERROR | head -8Erwartet:
2026-10-12T07:26:57.052Z [ERROR] agent.auth.handler: error authenticating:
error=
| Error making API request.
|
| URL: PUT http://openbao.openbao.svc:8200/v1/auth/kubernetes/login
| Code: 403. Errors:
|
| * invalid audience (aud) claim: audience claim does not match any expected audience
Fortschritt speichern? Kostenlos registrieren
Drill 3: Das Audience-Problem lösen
Ohne weitere Angabe nimmt der Agent das normale ServiceAccount-Token
des Pods (kube-api-access-…). Dessen Audience ist der
API-Server, die Rolle shop-api verlangt aber
openbao (Tag 2):
kubectl -n shop create token shop-api \
| jq -R 'split(".")[1] | @base64d | fromjson | .aud'
bao read -field=audience auth/kubernetes/role/shop-apiErwartet:
[
"https://kubernetes.default.svc.cluster.local"
]
openbao
Die saubere Lösung: ein eigenes projiziertes Token mit Audience
openbao und kurzer Laufzeit, nur für den Agent. Die
Annotation agent-service-account-token-volume-name zeigt
auf dieses Volume. Der App-Container muss es nicht mounten.
diff 10-shop-api-naiv.yaml 20-shop-api-token.yaml
kubectl apply -f 20-shop-api-token.yaml
kubectl -n shop rollout status deploy/shop-api --timeout=90s
kubectl -n shop exec deploy/shop-api -c app -- cat /vault/secrets/apiErwartet:
1c1
< # Tag 5, Drill 2: erster Versuch – nur die drei Pflicht-Annotationen
---
> # Tag 5, Drill 3: eigenes projiziertes Token mit Audience "openbao" für den Agent
17a18
> vault.hashicorp.com/agent-service-account-token-volume-name: "bao-token"
24a26,33
> volumes:
> - name: bao-token
> projected:
> sources:
> - serviceAccountToken:
> path: token
> audience: openbao
> expirationSeconds: 600
deployment "shop-api" successfully rolled out
data: map[api_key:lab-api-key-456 db_password:lab-db-pw-123 db_user:shop]
metadata: map[created_time:2026-10-12T07:26:49.585635772Z custom_metadata:<nil> ...]
Der Injector mountet das Volume in beide Agent-Container unter
/var/run/secrets/vault.hashicorp.com/serviceaccount.
Kubelet erneuert das Token selbstständig. Der Init-Container bekommt
übrigens auch kube-api-access-…, nutzt es aber nicht mehr
für den Login.
Sicherheit: Die Abkürzung „Audience aus der Rolle entfernen” funktioniert auch, akzeptiert dann aber jedes Token des ServiceAccounts, auch eines, das für einen ganz anderen Empfänger ausgestellt wurde. Lass die Audience in der Rolle.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Template als Env-Datei
Das Standard-Format (map) taugt nur zum Anschauen. Mit
agent-inject-template-<name> bestimmst du den Inhalt
per Go-Template. with secret liest den Pfad, bei KV v2
liegen die Werte unter .Data.data.
grep -A8 'inject-secret-env' 30-shop-api-template.yaml
kubectl apply -f 30-shop-api-template.yaml
kubectl -n shop rollout status deploy/shop-api --timeout=90s
kubectl -n shop exec deploy/shop-api -c app -- cat /vault/secrets/env
kubectl -n shop logs deploy/shop-api -c app
kubectl -n shop exec deploy/shop-api -c app -- ls -l /vault/secrets/Erwartet:
vault.hashicorp.com/agent-inject-secret-env: "secret/data/shop/api"
vault.hashicorp.com/agent-inject-template-env: |
{{- with secret "secret/data/shop/api" -}}
export DB_USER="{{ .Data.data.db_user }}"
export DB_PASSWORD="{{ .Data.data.db_password }}"
export API_KEY="{{ .Data.data.api_key }}"
{{- end }}
vault.hashicorp.com/agent-inject-perms-env: "0400"
vault.hashicorp.com/template-static-secret-render-interval: "20s"deployment "shop-api" successfully rolled out
export DB_USER="shop"
export DB_PASSWORD="lab-db-pw-123"
export API_KEY="lab-api-key-456"
start als shop
total 4
-r-------- 1 100 1000 90 Oct 12 07:27 env
Die App startet mit
. /vault/secrets/env && exec …. Das klappt, weil
der Init-Container die Datei schreibt, bevor app startet.
Die Datei gehört dem Agent-User (UID 100), mit 0400 kann
sie hier nur root lesen. Läuft deine App als anderer User, setz
agent-run-as-same-user oder passende Rechte. Die Variablen
leben nur im App-Prozess, nicht in der Pod-Spec, also auch nicht in
kubectl describe.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Sidecar rendert neu
KV-Secrets haben keine Lease. Der Sidecar liest sie im Intervall
template-static-secret-render-interval neu (Standard 5 min,
hier 20 s).
bao kv patch secret/shop/api api_key=lab-api-key-457 | tail -1
sleep 30
kubectl -n shop exec deploy/shop-api -c app -- grep API_KEY /vault/secrets/env
kubectl -n shop logs deploy/shop-api -c vault-agent | grep rendered | tail -1 \
| cut -c26-
kubectl -n shop exec deploy/shop-api -c app -- sh -c 'echo $API_KEY'Erwartet:
version 2
export API_KEY="lab-api-key-457"
[INFO] agent: (runner) rendered "(dynamic)" => "/vault/secrets/env"
Die Datei ist neu, die letzte Zeile bleibt leer:
kubectl exec startet eine neue Shell ohne die Variablen,
und der laufende App-Prozess hätte ohnehin den alten Wert. Wer
Env-Variablen nutzt, braucht einen Neustart (Tag 9) oder liest die Datei
bei Bedarf neu.
bao kv patch secret/shop/api api_key=lab-api-key-456 >/dev/nullFortschritt speichern? Kostenlos registrieren
Drill 6: Nur Init, kein Sidecar
Für Jobs oder Apps, die ohnehin nur beim Start lesen:
agent-pre-populate-only.
kubectl -n shop patch deploy shop-api --type merge -p '{"spec":{"template":{"metadata":
{"annotations":{"vault.hashicorp.com/agent-pre-populate-only":"true"}}}}}'
kubectl -n shop rollout status deploy/shop-api --timeout=90s
sleep 5
kubectl -n shop get pod -l app=shop-api -o json | jq -c '.items[]
| {init: [.spec.initContainers[].name], main: [.spec.containers[].name]}'Erwartet:
deployment.apps/shop-api patched
deployment "shop-api" successfully rolled out
{"init":["vault-agent-init"],"main":["app"]}
Kein Sidecar, also auch kein Re-Render und keine Lease-Erneuerung. Das spart pro Pod einen Container und dessen Requests. Für dynamische Secrets (Tag 7) ist das die falsche Wahl.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Ressourcen der Agents
Jeder Agent-Container fordert per Chart-Default 250m CPU
und 64Mi RAM an. Bei 200 Pods ist das ein Node voller
Sidecars, die meist schlafen.
kubectl -n shop patch deploy shop-api --type merge -p '{"spec":{"template":{"metadata":
{"annotations":{"vault.hashicorp.com/agent-pre-populate-only":"false",
"vault.hashicorp.com/agent-requests-cpu":"25m",
"vault.hashicorp.com/agent-requests-mem":"32Mi",
"vault.hashicorp.com/agent-limits-cpu":"100m",
"vault.hashicorp.com/agent-limits-mem":"64Mi"}}}}}'
kubectl -n shop rollout status deploy/shop-api --timeout=90s
sleep 5
kubectl -n shop get pod -l app=shop-api -o json | jq -c '.items[].spec
| (.initContainers + .containers)[] | {name, r: .resources}'Erwartet:
{"name":"vault-agent-init","r":{"limits":{"cpu":"100m","memory":"64Mi"},
"requests":{"cpu":"25m","memory":"32Mi"}}}
{"name":"app","r":{}}
{"name":"vault-agent","r":{"limits":{"cpu":"100m","memory":"64Mi"},
"requests":{"cpu":"25m","memory":"32Mi"}}}
Clusterweit setzt du das über injector.agentDefaults in
der Values-Datei, pro Workload über die Annotationen.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Fehlersuche
Zwei Klassiker. Erstens eine falsche Rolle:
kubectl -n shop patch deploy shop-api --type merge -p '{"spec":{"template":{"metadata":
{"annotations":{"vault.hashicorp.com/role":"shop-apx"}}}}}'
sleep 25
kubectl -n shop get pod -l app=shop-api
kubectl -n shop logs -l app=shop-api -c vault-agent-init --tail=20 \
| grep '^ | \*' | tail -1Erwartet:
deployment.apps/shop-api patched
NAME READY STATUS RESTARTS AGE
shop-api-778976cfd-6vwjv 2/2 Running 0 32s
shop-api-ff8f5f9ff-9gtdf 0/2 Init:0/1 0 25s
| * invalid role name "shop-apx"
Das Rollout bleibt stehen, der alte Pod läuft weiter. Die
Fehlermeldung steht immer im Container vault-agent-init,
nicht in app. Zurück auf den Stand aus Git:
kubectl apply -f 30-shop-api-template.yaml
kubectl -n shop rollout status deploy/shop-api --timeout=90sZweitens: Der Injector ist weg. failurePolicy: Ignore
lässt den Pod dann ohne Agents durch, allerdings erst nach dem
Webhook-Timeout von 30 s.
kubectl -n openbao scale deploy openbao-agent-injector --replicas=0
kubectl -n openbao wait --for=delete pod \
-l app.kubernetes.io/name=openbao-agent-injector --timeout=60s
kubectl -n shop delete pod -l app=shop-api --wait=false
sleep 45
kubectl -n shop get pod -l app=shop-api
kubectl -n shop logs -l app=shop-api -c app --tail=1Erwartet:
deployment.apps/openbao-agent-injector scaled
pod/openbao-agent-injector-8cf8bbc95-ww6nk condition met
pod "shop-api-778976cfd-75lp2" deleted from shop namespace
NAME READY STATUS RESTARTS AGE
shop-api-778976cfd-mq6wj 0/1 Error 2 (20s ago) 21s
sh: .: line 0: can't open '/vault/secrets/env': No such file or directory
0/1 statt 0/2: kein Sidecar, keine
Annotation agent-inject-status. Hier crasht die App
wenigstens laut. Eine App, die fehlende Konfiguration mit Defaults
überspielt, läuft dagegen still mit falschen Werten. Injector
zurückholen:
kubectl -n openbao scale deploy openbao-agent-injector --replicas=1
kubectl -n openbao rollout status deploy openbao-agent-injector --timeout=90s
kubectl -n shop delete pod -l app=shop-api
kubectl -n shop rollout status deploy/shop-api --timeout=90sTipp: Merkliste bei „Pod hängt in
Init:0/1“: Logs vonvault-agent-init, dann Rolle und Audience perbao read auth/kubernetes/role/<rolle>, dann die Policy (permission deniedbeim Lesen statt beim Login).
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
P=$(kubectl -n shop get pod -l app=shop-api -o jsonpath='{.items[0].metadata.name}')
S=$(kubectl -n shop get pod "$P" \
-o jsonpath='{.metadata.annotations.vault\.hashicorp\.com/agent-inject-status}')
[ "$S" = injected ] && ok "Pod injiziert" || nok "nicht injiziert: $S"
kubectl -n shop get pod "$P" -o jsonpath='{.spec.containers[*].name}' \
| grep -q vault-agent && ok "Sidecar läuft" || nok "kein Sidecar"
kubectl -n shop exec "$P" -c app -- grep -q lab-db-pw-123 /vault/secrets/env \
&& ok "Env-Datei gerendert" || nok "Env-Datei fehlt"
kubectl -n shop exec "$P" -c app -- env | grep -q lab-db-pw-123 \
&& nok "Secret in Container-Env" || ok "kein Secret in der Container-Env"Challenge
Lege zusätzlich secret/shop/stripe als
/vault/secrets/stripe.json mit Dateirechten
0440 in den Pod, ohne eine zweite YAML-Datei zu
schreiben.
Hinweis: consul-template kennt die Funktion
toJSON, und Annotationen kannst du per
kubectl patch ergänzen.
Lösung
cat > stripe-patch.yaml <<'EOF'
spec:
template:
metadata:
annotations:
vault.hashicorp.com/agent-inject-secret-stripe.json: "secret/data/shop/stripe"
vault.hashicorp.com/agent-inject-template-stripe.json: |
{{ with secret "secret/data/shop/stripe" }}{{ .Data.data | toJSON }}{{ end }}
vault.hashicorp.com/agent-inject-perms-stripe.json: "0440"
EOF
kubectl -n shop patch deploy shop-api --type merge --patch-file stripe-patch.yaml
kubectl -n shop rollout status deploy/shop-api --timeout=90s
kubectl -n shop exec deploy/shop-api -c app -- cat /vault/secrets/stripe.jsonErwartet:
deployment.apps/shop-api patched
deployment "shop-api" successfully rolled out
{"token":"lab-stripe-789"}
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
failurePolicy: Ignoreist bequem und gefährlich: Fällt der Injector aus, starten Pods ohne Secrets. Zwei Replikas, PodDisruptionBudget und Alarm auf CrashLoops nach Injector-Ausfällen gehören dazu.- Audience pro Rolle setzen und per projiziertem Token liefern. Eine
Kyverno-Regel kann erzwingen, dass injizierte Pods
agent-service-account-token-volume-nametragen. - Agent-Requests realistisch setzen
(
injector.agentDefaults). Bei hunderten Pods sind die Chart-Defaults Kapazitätsplanung, nicht Kleinkram. - Gegen echtes OpenBao mit TLS:
vault.hashicorp.com/tls-secretundca-certstatttls-skip-verify. Die CA gehört in ein Secret im App-Namespace. - Templates sind Code: in Git, im Review, mit Tests. Ein Tippfehler in
einem Key fällt erst im laufenden Pod auf
(
vault.hashicorp.com/error-on-missing-key-<name>hilft).