Zum Inhalt springen
Trainingslager IT-Trainingslager

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 emptyDir unter /vault/secrets.
  • Das Chart nutzt den Injector hashicorp/vault-k8s. Darum heißen alle Annotationen vault.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-api

Erwartet:

        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 -8

Erwartet:

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-api

Erwartet:

[
  "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/api

Erwartet:

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

Fortschritt 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 -1

Erwartet:

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=90s

Zweitens: 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=1

Erwartet:

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=90s

Tipp: Merkliste bei „Pod hängt in Init:0/1“: Logs von vault-agent-init, dann Rolle und Audience per bao read auth/kubernetes/role/<rolle>, dann die Policy (permission denied beim 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.json

Erwartet:

deployment.apps/shop-api patched
deployment "shop-api" successfully rolled out
{"token":"lab-stripe-789"}

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • failurePolicy: Ignore ist 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-name tragen.
  • 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-secret und ca-cert statt tls-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).