Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: External Secrets Operator – Grundlagen

Ziel: Den External Secrets Operator (ESO) installieren und Secrets aus OpenBao per Kubernetes-Auth als normale Kubernetes-Secrets in den Namespace shop holen. · Dauer: ca. 90 min · Voraussetzung: Tag 2

Briefing

  • ESO ist ein Controller: Er liest Secrets aus OpenBao und schreibt sie als Kubernetes-Secret. Pods merken davon nichts, sie nutzen envFrom oder Volumes wie immer.
  • SecretStore (pro Namespace) bzw. ClusterSecretStore (clusterweit) sagt, wo OpenBao steht und wie ESO sich anmeldet.
  • ExternalSecret sagt, was geholt wird und in welches Ziel-Secret es geschrieben wird.
  • Für OpenBao nutzt du den Provider vault. ESO meldet sich mit einem kurzlebigen Token des ServiceAccounts shop-api an. Die Audience muss zur Rolle passen (Tag 2).
ExternalSecret ──> SecretStore ──> TokenRequest (SA shop-api, aud=openbao)
      │                 │
      │                 └──> OpenBao: auth/kubernetes/login ──> Token (shop-api-read)
      │                                     │
      └──< Secret shop-api-db <── GET secret/data/shop/api

Drill 1: ESO per Helm installieren

Das Gelände aus Tag 0 steht, der Port-Forward auf 8200 läuft, seed.sh ist gelaufen.

mkdir -p ~/secrets-lab/tag03 && cd ~/secrets-lab/tag03
export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root
helm repo add external-secrets https://charts.external-secrets.io
helm repo update external-secrets
helm search repo external-secrets/external-secrets --versions -o json \
  | jq -r '.[:2][] | "\(.name) \(.version) \(.app_version)"'

Erwartet (gekürzt, kann je nach Version abweichen):

external-secrets/external-secrets 2.12.0 v2.12.0
external-secrets/external-secrets 2.11.0 v2.11.0

Eine Replika je Komponente reicht im Lab. Die CRDs installiert das Chart selbst (installCRDs: true).

cat > eso-values.yaml <<'EOF'
# Lab-Werte (Tag 3): External Secrets Operator, eine Replika je Komponente
installCRDs: true
replicaCount: 1
webhook:
  replicaCount: 1
certController:
  replicaCount: 1
EOF
helm install external-secrets external-secrets/external-secrets \
  -n external-secrets --create-namespace --version 2.12.0 \
  -f eso-values.yaml --wait --timeout 6m
kubectl -n external-secrets get deploy

Erwartet (gekürzt, kann je nach Version abweichen):

NAME: external-secrets
NAMESPACE: external-secrets
STATUS: deployed
REVISION: 1
...
NAME                               READY   UP-TO-DATE   AVAILABLE   AGE
external-secrets                   1/1     1            1           62s
external-secrets-cert-controller   1/1     1            1           62s
external-secrets-webhook           1/1     1            1           62s

Drei Deployments: der Controller (synchronisiert), der Webhook (prüft deine YAMLs beim apply) und der Cert-Controller (versorgt den Webhook mit TLS-Zertifikaten).

Fortschritt speichern? Kostenlos registrieren

Drill 2: CRDs und API-Versionen prüfen

API-Versionen ändern sich bei ESO schneller als bei Kubernetes. Prüf sie im Cluster, nicht im Blog-Artikel.

kubectl api-resources --api-group=external-secrets.io --no-headers \
  | awk '{print $NF, $(NF-2)}'
kubectl api-resources --api-group=generators.external-secrets.io --no-headers \
  | awk '/Vault/{print $NF, $(NF-2)}'

Erwartet:

ClusterExternalSecret external-secrets.io/v1
ClusterPushSecret external-secrets.io/v1alpha1
ClusterSecretStore external-secrets.io/v1
ExternalSecret external-secrets.io/v1
PushSecret external-secrets.io/v1alpha1
SecretStore external-secrets.io/v1
VaultDynamicSecret generators.external-secrets.io/v1alpha1

ExternalSecret und die Stores sind v1. v1beta1 liefert das Chart 2.x nur noch mit crds.unsafeServeV1Beta1=true aus. Alte Manifeste also auf v1 heben. PushSecret und die Generatoren sind noch v1alpha1 (Tag 4).

kubectl explain secretstore.spec.provider.vault.auth.kubernetes.serviceAccountRef \
  | sed -n '/FIELDS/,$p'

Erwartet:

FIELDS:
  audiences <[]string>
    Audience specifies the `aud` claim for the service account token
...
  name  <string> -required-
    The name of the ServiceAccount resource being referred to.

  namespace <string>
    Namespace of the resource being referred to.
    Ignored if referent is not cluster-scoped, otherwise defaults to the
    namespace of the referent.

audiences ist der Schlüssel: Ohne den Eintrag bekommt das Token die Standard-Audience des API-Servers, und die Rolle shop-api mit audience=openbao lehnt ab (Tag 4, Drill 7).

Fortschritt speichern? Kostenlos registrieren

Drill 3: SecretStore mit Kubernetes-Auth

cat > secretstore.yaml <<'EOF'
# Tag 3: SecretStore im NS shop – Provider vault gegen OpenBao, Kubernetes-Auth
apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: openbao
  namespace: shop
spec:
  provider:
    vault:
      server: http://openbao.openbao.svc:8200
      path: secret
      version: v2
      auth:
        kubernetes:
          mountPath: kubernetes
          role: shop-api
          serviceAccountRef:
            name: shop-api
            audiences:
              - openbao
EOF
kubectl apply -f secretstore.yaml
kubectl -n shop get secretstore
kubectl -n shop get ss openbao -o yaml | sed -n '/^status/,$p'

Erwartet:

secretstore.external-secrets.io/openbao created
NAME      AGE   STATUS   CAPABILITIES   READY
openbao   3s    Valid    ReadWrite      True
status:
  capabilities: ReadWrite
  conditions:
  - lastTransitionTime: "2026-10-12T07:21:56Z"
    message: store validated
    reason: Valid
    status: "True"
    type: Ready

path: secret ist der Mount, version: v2 die KV-Version. Die Pfade in den ExternalSecrets schreibst du deshalb ohne secret/ und ohne data/. ESO erzeugt für jede Anmeldung per TokenRequest ein neues SA-Token. Ein Secret mit Token im Namespace gibt es nicht.

Tipp: CAPABILITIES ReadWrite heißt nur, dass der Provider Schreiben (PushSecret) kann. Ob die Policy es erlaubt, entscheidet OpenBao.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Das erste ExternalSecret

cat > es-api.yaml <<'EOF'
# Tag 3: einzelne Keys aus secret/shop/api in ein K8s-Secret holen
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: shop-api
  namespace: shop
spec:
  refreshInterval: 1m
  secretStoreRef:
    kind: SecretStore
    name: openbao
  target:
    name: shop-api-db
  data:
    - secretKey: DB_USER
      remoteRef:
        key: shop/api
        property: db_user
    - secretKey: DB_PASSWORD
      remoteRef:
        key: shop/api
        property: db_password
EOF
kubectl apply -f es-api.yaml
kubectl -n shop get externalsecret
kubectl -n shop get secret shop-api-db -o json | jq -r '.data | map_values(@base64d)'

Erwartet:

externalsecret.external-secrets.io/shop-api created
NAME       STORETYPE     STORE     REFRESH INTERVAL   STATUS         READY   LAST SYNC
shop-api   SecretStore   openbao   1m                 SecretSynced   True    3s
{
  "DB_PASSWORD": "lab-db-pw-123",
  "DB_USER": "shop"
}

secretKey ist der Key im Kubernetes-Secret, property der Key in OpenBao. So bekommst du Umgebungsvariablen-taugliche Namen, ohne OpenBao umzubauen.

kubectl -n shop get secret shop-api-db -o yaml \
  | grep -E 'reconcile|ownerReferences|kind: ExternalSecret'

Erwartet:

    reconcile.external-secrets.io/data-hash: b614d5e06fffd6df1a94c94aaa45031c2f6826...
    reconcile.external-secrets.io/created-by: 512babf959de1f10c8b676b8cb3d4958e4412...
    reconcile.external-secrets.io/managed: "true"
  ownerReferences:
    kind: ExternalSecret

Das Secret gehört dem ExternalSecret (creationPolicy: Owner ist Standard). Löschst du das ExternalSecret, räumt der Garbage Collector das Secret mit ab (Tag 4, Drill 3).

Fortschritt speichern? Kostenlos registrieren

Drill 5: Status, Conditions und Events lesen

Wenn etwas hakt, schaust du an drei Stellen: Spalte STATUS, status.conditions und Events.

kubectl -n shop get es shop-api -o yaml | sed -n '/^status/,$p'
kubectl -n shop get events --field-selector involvedObject.kind=ExternalSecret

Erwartet:

status:
  binding:
    name: shop-api-db
  conditions:
  - lastTransitionTime: "2026-10-12T07:22:03Z"
    message: secret synced
    reason: SecretSynced
    status: "True"
    type: Ready
  refreshTime: "2026-10-12T07:22:03Z"
  syncedResourceVersion: 1-3100fad8f0639bf81f08734993f6e748c1b37068ccb122b6aa214368
LAST SEEN   TYPE     REASON    OBJECT                    MESSAGE
7s          Normal   Created   externalsecret/shop-api   secret created

refreshTime ist der letzte erfolgreiche Abgleich. Die eigentliche Fehlermeldung steht fast immer im Event (UpdateFailed), nicht in der Condition. Die sagt meist nur could not get secret data from provider.

Reason Bedeutung
SecretSynced alles gut
SecretSyncedError Lesen oder Schreiben fehlgeschlagen, Event lesen
SecretMissing creationPolicy: Merge, aber Ziel-Secret fehlt (Tag 4)
SecretDeleted Quelle weg, deletionPolicy: Delete hat gelöscht (Tag 4)

Fortschritt speichern? Kostenlos registrieren

Drill 6: dataFrom – extract und find

extract holt alle Keys eines Pfads. find sucht über mehrere Pfade.

cat > es-extract.yaml <<'EOF'
# Tag 3: alle Keys eines Pfads auf einmal (dataFrom.extract)
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: shop-api-all
  namespace: shop
spec:
  refreshInterval: 1m
  secretStoreRef:
    kind: SecretStore
    name: openbao
  target:
    name: shop-api-all
  dataFrom:
    - extract:
        key: shop/api
EOF
cat > es-find.yaml <<'EOF'
# Tag 3: alle Secrets unter shop/ suchen (dataFrom.find) – braucht list-Rechte
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: shop-find
  namespace: shop
spec:
  refreshInterval: 1m
  secretStoreRef:
    kind: SecretStore
    name: openbao
  target:
    name: shop-find
  dataFrom:
    - find:
        path: shop
        name:
          regexp: "^shop/.*"
EOF
kubectl apply -f es-extract.yaml -f es-find.yaml
kubectl -n shop get es shop-api-all shop-find
kubectl -n shop get secret shop-api-all -o json | jq -c '.data | keys'
kubectl -n shop get events --field-selector involvedObject.name=shop-find \
  -o jsonpath='{.items[0].message}'

Erwartet:

externalsecret.external-secrets.io/shop-api-all created
externalsecret.external-secrets.io/shop-find created
NAME           STORETYPE     STORE     REFRESH INTERVAL   STATUS              READY ...
shop-api-all   SecretStore   openbao   1m                 SecretSynced        True  ...
shop-find      SecretStore   openbao   1m                 SecretSyncedError   False ...
["api_key","db_password","db_user"]
error processing spec.dataFrom[0].find, err: error getting all secrets: cannot read
secret data from Vault: Error making API request.

URL: GET http://openbao.openbao.svc:8200/v1/secret/metadata/shop?list=true
Code: 403. Errors:

* 1 error occurred:
    * permission denied

find listet über secret/metadata/…. Die Policy shop-api-read erlaubt nur read auf secret/data/shop/*. Least Privilege funktioniert, du brauchst eine Zusatz-Policy.

cat > shop-api-list.hcl <<'EOF'
# Tag 3: Zusatz-Policy für dataFrom.find – Metadaten unter shop/ auflisten
path "secret/metadata/shop/*" {
  capabilities = ["list", "read"]
}
path "secret/metadata/shop" {
  capabilities = ["list"]
}
EOF
bao policy write shop-api-list shop-api-list.hcl
bao write auth/kubernetes/role/shop-api token_policies=shop-api-read,shop-api-list
bao read -format=json auth/kubernetes/role/shop-api \
  | jq -c '.data | {audience, token_policies}'
kubectl -n shop annotate es shop-find force-sync="$(date +%s)" --overwrite
sleep 3
kubectl -n shop get secret shop-find -o json | jq -r '.data | map_values(@base64d)'

Erwartet:

Success! Uploaded policy: shop-api-list
Success! Data written to: auth/kubernetes/role/shop-api
{"audience":"openbao","token_policies":["shop-api-read","shop-api-list"]}
externalsecret.external-secrets.io/shop-find annotated
{
  "shop_api": "{\"api_key\":\"lab-api-key-456\",\"db_password\":\"lab-db-pw-123\",...}",
  "shop_stripe": "{\"token\":\"lab-stripe-789\"}"
}

bao write auf eine bestehende Rolle ändert nur die übergebenen Felder, Bindung und Audience bleiben. find liefert pro Pfad einen Key mit dem ganzen Secret als JSON. Der Pfad wird zum Key-Namen (/ wird zu _). Für Env-Variablen ist extract meist die bessere Wahl.

Achtung: metadata/… mit list verrät Namen aller Secrets darunter. Gib das nur, wenn du find wirklich brauchst.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Refresh beobachten und erzwingen

refreshInterval: 1m heißt: ESO liest spätestens nach einer Minute neu. Ändere das Passwort in OpenBao und beobachte.

bao kv patch secret/shop/api db_password=lab-db-pw-124 >/dev/null; date +%T
for i in $(seq 1 15); do
  v=$(kubectl -n shop get secret shop-api-db -o jsonpath='{.data.DB_PASSWORD}' \
    | base64 -d)
  echo "$(date +%T) $v"; [ "$v" = lab-db-pw-124 ] && break; sleep 5
done

Erwartet (Zeiten variieren):

09:22:46
09:22:46 lab-db-pw-123
09:22:51 lab-db-pw-123
09:22:56 lab-db-pw-123
09:23:01 lab-db-pw-123
09:23:06 lab-db-pw-124

Nicht warten wollen? Jede Änderung an Annotationen löst sofort einen Abgleich aus. Die Konvention aus der ESO-Doku ist force-sync mit Zeitstempel.

bao kv patch secret/shop/api db_password=lab-db-pw-123 >/dev/null
kubectl -n shop annotate es shop-api force-sync="$(date +%s)" --overwrite
sleep 2
kubectl -n shop get secret shop-api-db -o jsonpath='{.data.DB_PASSWORD}' | base64 -d
echo
kubectl -n shop get events --field-selector involvedObject.name=shop-api

Erwartet:

externalsecret.external-secrets.io/shop-api annotated
lab-db-pw-123
LAST SEEN   TYPE     REASON    OBJECT                    MESSAGE
73s         Normal   Created   externalsecret/shop-api   secret created
5s          Normal   Updated   externalsecret/shop-api   secret updated

Achtung: Das Kubernetes-Secret ist aktuell, der Pod noch nicht. Env-Variablen liest ein Container nur beim Start. Wie du neu ausrollst, zeigt Tag 9.

Kurze Intervalle kosten Last: Jeder Abgleich ist ein Login plus ein Read pro ExternalSecret. Bei 500 ExternalSecrets mit 10s merkt OpenBao das. refreshInterval: 0s holt einmal und nie wieder.

Fortschritt speichern? Kostenlos registrieren

Drill 8: ClusterSecretStore als Variante

Ein ClusterSecretStore gilt clusterweit. Weil er keinen Namespace hat, braucht serviceAccountRef einen.

cat > clustersecretstore.yaml <<'EOF'
# Tag 3: ClusterSecretStore – clusterweit, ServiceAccount mit Namespace
apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: openbao-shop
spec:
  provider:
    vault:
      server: http://openbao.openbao.svc:8200
      path: secret
      version: v2
      auth:
        kubernetes:
          mountPath: kubernetes
          role: shop-api
          serviceAccountRef:
            name: shop-api
            namespace: shop
            audiences:
              - openbao
EOF
cat > es-stripe-css.yaml <<'EOF'
# Tag 3: ExternalSecret über den ClusterSecretStore
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: shop-stripe
  namespace: shop
spec:
  refreshInterval: 1m
  secretStoreRef:
    kind: ClusterSecretStore
    name: openbao-shop
  target:
    name: shop-stripe
  data:
    - secretKey: STRIPE_TOKEN
      remoteRef:
        key: shop/stripe
        property: token
EOF
kubectl apply -f clustersecretstore.yaml -f es-stripe-css.yaml
kubectl get clustersecretstore
kubectl -n shop get es shop-stripe
kubectl -n shop get secret shop-stripe -o jsonpath='{.data.STRIPE_TOKEN}' | base64 -d
echo

Erwartet:

clustersecretstore.external-secrets.io/openbao-shop created
externalsecret.external-secrets.io/shop-stripe created
NAME           AGE   STATUS   CAPABILITIES   READY
openbao-shop   3s    Valid    ReadWrite      True
NAME          STORETYPE            STORE          REFRESH INTERVAL   STATUS         ...
shop-stripe   ClusterSecretStore   openbao-shop   1m                 SecretSynced   ...
lab-stripe-789

Sicherheit: Dieser ClusterSecretStore ist offen: Jeder Namespace kann ihn referenzieren und bekommt die Rechte von shop-api. Tag 4 (Drill 4) zeigt den Angriff und sperrt ihn mit conditions ab.

Tipp: ESO 2.x kennt zusätzlich einen eigenen Provider openBao (spec.provider.openBao, Auth-Feld path statt mountPath). Er ist derzeit nur lesend (kein PushSecret) und prüft beim Validieren sys/mounts/secret, wofür die Rolle zusätzlich read darauf braucht. Dieses Buch bleibt beim ausgereiften vault-Provider.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
[ "$(kubectl -n external-secrets get deploy --no-headers 2>/dev/null \
  | awk '$2=="1/1"' | wc -l)" -eq 3 ] && ok "3 ESO-Deployments bereit" \
  || nok "ESO nicht bereit"
[ "$(kubectl -n shop get ss openbao -o jsonpath='{.status.conditions[0].reason}')" \
  = Valid ] && ok "SecretStore openbao Valid" || nok "SecretStore nicht Valid"
for es in shop-api shop-api-all shop-find shop-stripe; do
  [ "$(kubectl -n shop get es $es -o jsonpath='{.status.conditions[0].reason}')" \
    = SecretSynced ] && ok "ExternalSecret $es synchron" || nok "$es nicht synchron"
done
PW=$(kubectl -n shop get secret shop-api-db -o jsonpath='{.data.DB_PASSWORD}' \
  | base64 -d)
[ "$PW" = lab-db-pw-123 ] && ok "DB_PASSWORD korrekt" || nok "DB_PASSWORD falsch"
bao policy read shop-api-list >/dev/null 2>&1 \
  && ok "Policy shop-api-list vorhanden" || nok "Policy shop-api-list fehlt"

Challenge

Bau ein ExternalSecret shop-env, das alle Keys aus shop/api und shop/stripe in ein Secret schreibt. Die Keys sollen als SHOP_<KEY> bzw. SHOP_STRIPE_<KEY> in Großbuchstaben ankommen und alle 30 Sekunden aktualisiert werden.

Hinweis: Jeder dataFrom-Eintrag kann eine Liste rewrite haben: erst regexp (Präfix), dann transform mit einem Template auf .value (den Key-Namen).

Lösung

cat > challenge-shop-env.yaml <<'EOF'
# Tag 3 Challenge: alle Keys aus shop/api und shop/stripe als SHOP_*-Keys (groß)
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: shop-env
  namespace: shop
spec:
  refreshInterval: 30s
  secretStoreRef:
    kind: SecretStore
    name: openbao
  target:
    name: shop-env
  dataFrom:
    - extract:
        key: shop/api
      rewrite:
        - regexp:
            source: "(.*)"
            target: "SHOP_$1"
        - transform:
            template: "{{ .value | upper }}"
    - extract:
        key: shop/stripe
      rewrite:
        - regexp:
            source: "(.*)"
            target: "SHOP_STRIPE_$1"
        - transform:
            template: "{{ .value | upper }}"
EOF
kubectl apply -f challenge-shop-env.yaml
sleep 3
kubectl -n shop get secret shop-env -o json | jq -r '.data | map_values(@base64d)'

Erwartet:

externalsecret.external-secrets.io/shop-env created
{
  "SHOP_API_KEY": "lab-api-key-456",
  "SHOP_DB_PASSWORD": "lab-db-pw-123",
  "SHOP_DB_USER": "shop",
  "SHOP_STRIPE_TOKEN": "lab-stripe-789"
}

Im Pod reicht dann envFrom: [{secretRef: {name: shop-env}}].

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Ein SecretStore pro Namespace mit eigener Rolle und eigenem ServiceAccount ist das sichere Standardmuster. ClusterSecretStore nur mit conditions (Tag 4).
  • OpenBao in Produktion per HTTPS: server: https://… plus caProvider oder caBundle. Der Dev-Modus mit HTTP ist nur Lab.
  • Kubernetes-Secrets landen in etcd: Encryption at Rest und RBAC auf secrets sind Pflicht. ESO verschiebt das Problem, löst es aber nicht ganz (Tag 6 zeigt CSI ohne etcd).
  • Chart-Version pinnen und vor Upgrades die API-Versionen prüfen. v1beta1 ist in 2.x abgeschaltet. Manifeste aus älteren Blogposts scheitern sonst beim apply.
  • Refresh-Intervalle an die Last anpassen und ESO-Metriken (/metrics, ServiceMonitor im Chart) ins Monitoring holen, Alarm auf SecretSyncedError.