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
shopholen. · 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 nutzenenvFromoder Volumes wie immer. SecretStore(pro Namespace) bzw.ClusterSecretStore(clusterweit) sagt, wo OpenBao steht und wie ESO sich anmeldet.ExternalSecretsagt, 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 ServiceAccountsshop-apian. 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 deployErwartet (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 ReadWriteheiß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=ExternalSecretErwartet:
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/…mitlistverrät Namen aller Secrets darunter. Gib das nur, wenn dufindwirklich 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
doneErwartet (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-apiErwartet:
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
echoErwartet:
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
ClusterSecretStoreist offen: Jeder Namespace kann ihn referenzieren und bekommt die Rechte vonshop-api. Tag 4 (Drill 4) zeigt den Angriff und sperrt ihn mitconditionsab.
Tipp: ESO 2.x kennt zusätzlich einen eigenen Provider
openBao(spec.provider.openBao, Auth-FeldpathstattmountPath). Er ist derzeit nur lesend (kein PushSecret) und prüft beim Validierensys/mounts/secret, wofür die Rolle zusätzlichreaddarauf braucht. Dieses Buch bleibt beim ausgereiftenvault-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
SecretStorepro Namespace mit eigener Rolle und eigenem ServiceAccount ist das sichere Standardmuster.ClusterSecretStorenur mitconditions(Tag 4). - OpenBao in Produktion per HTTPS:
server: https://…pluscaProviderodercaBundle. Der Dev-Modus mit HTTP ist nur Lab. - Kubernetes-Secrets landen in etcd: Encryption at Rest und RBAC auf
secretssind 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.
v1beta1ist in 2.x abgeschaltet. Manifeste aus älteren Blogposts scheitern sonst beimapply. - Refresh-Intervalle an die Last anpassen und ESO-Metriken
(
/metrics, ServiceMonitor im Chart) ins Monitoring holen, Alarm aufSecretSyncedError.