Anhang A: Spickzettel
Stand des Buchs: OpenBao 2.7.1 (bao-CLI), Helm-Chart
openbao 0.30.3, kind 0.33 (Kubernetes 1.37), External
Secrets Operator 2.12.0, Secrets Store CSI Driver 1.6.1, Reloader-Chart
2.2.18. Namen entsprechen der Demo-App shop-api im
Namespace shop.
Lab-Umgebung
kubectl -n openbao port-forward svc/openbao 8200:8200 # eigenes Terminal
export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root # root nur im Dev-Modus!
~/secrets-lab/setup/check.sh # Gelände prüfen (✔/✘)
~/secrets-lab/setup/seed.sh # nach jedem Neustart von openbao-0
bao status # Storage Type inmem = Dev-Modus
| Was |
Wert im Lab |
| OpenBao vom Laptop / aus dem Cluster |
http://127.0.0.1:8200 /
http://openbao.openbao.svc:8200 |
| KV v2 |
Mount secret/, secret/shop/api,
secret/shop/stripe, secret/ci/deploy |
| Kubernetes-Auth |
Mount kubernetes/, Rolle shop-api,
Audience openbao |
| JWT-Auth für CI |
jwt-ci/ (Lab-Issuer), jwt-github/,
jwt-gitlab/ |
| Dynamisch |
database/ mit Rollen shop-ro (Tag 4),
shop-ro-short (Tag 7), PKI pki/ mit Rolle
shop-svc |
KV v2 mit der CLI
bao kv get secret/shop/api # alles inkl. Metadaten
bao kv get -field=db_password secret/shop/api # ein Wert, ohne Zeilenumbruch
bao kv get -format=json secret/shop/api | jq -r '.data.data.api_key'
bao kv get -version=2 secret/shop/api # ältere Version
bao kv list secret/shop # braucht list auf metadata/
bao kv put secret/shop/api db_user=shop ... # ERSETZT das ganze Secret
bao kv patch secret/shop/api db_password=neu # ändert nur diesen Key
bao kv put -cas=4 secret/shop/api ... # nur wenn Version 4 aktuell ist
bao kv rollback -version=2 secret/shop/api # alte Version als neue Version
bao kv metadata get secret/shop/api # Versionen, current_version
bao kv metadata put -max-versions=5 -custom-metadata=owner=team-shop secret/shop/api
bao kv metadata delete secret/shop/feature # alle Versionen weg
bao kv get -output-curl-string secret/shop/api # passender curl-Aufruf
bao kv get -output-policy secret/shop/api # passende Policy-Regel
Dieselben Aufrufe per curl
| CLI |
HTTP |
Pfad |
kv get |
GET |
/v1/secret/data/shop/api |
kv metadata get |
GET |
/v1/secret/metadata/shop/api |
kv list |
LIST (oder GET ?list=true) |
/v1/secret/metadata/shop |
| Login Kubernetes |
POST |
/v1/auth/kubernetes/login |
| Login JWT / AppRole |
POST |
/v1/auth/jwt-ci/login,
/v1/auth/approle/login |
| Token erneuern |
POST |
/v1/auth/token/renew-self |
| Auspacken |
POST |
/v1/sys/wrapping/unwrap |
curl -s -H "X-Vault-Token: $BAO_TOKEN" "$BAO_ADDR/v1/secret/data/shop/api" \
| jq '.data.data'
curl -s -H "Authorization: Bearer $BAO_TOKEN" "$BAO_ADDR/v1/secret/data/shop/api"
curl -s -X LIST -H "X-Vault-Token: $BAO_TOKEN" "$BAO_ADDR/v1/secret/metadata/shop"
curl -s -X POST "$BAO_ADDR/v1/auth/kubernetes/login" \
-d "{\"role\":\"shop-api\",\"jwt\":\"$(cat /var/run/secrets/openbao/token)\"}" \
| jq -r '.auth.client_token'
curl -s -H "X-Vault-Token: $BAO_TOKEN" -H "X-Vault-Wrap-TTL: 120s" \
"$BAO_ADDR/v1/secret/data/shop/stripe" | jq -r '.wrap_info.token'
Ohne oder mit ungültigem Token antwortet OpenBao mit 403
und {"errors":["permission denied"]}, nicht mit
401.
Policies
# KV v2: immer API-Pfade mit data/ bzw. metadata/
path "secret/data/shop/api" {
capabilities = ["read"]
}
# Auflisten (dataFrom.find bei ESO, kv list)
path "secret/metadata/shop/*" {
capabilities = ["list", "read"]
}
# Unterpfad sperren: deny schlägt jede andere Regel
path "secret/data/shop/admin/*" {
capabilities = ["deny"]
}
Policy-Template: Namespace aus dem Entity-Alias der Kubernetes-Auth.
Der Accessor ist in jedem Lab anders, die Shell setzt ihn ein (Tag 2,
Drill 7, Tag 14, Drill 3):
A=$(bao auth list -format=json | jq -r '."kubernetes/".accessor')
M="identity.entity.aliases.$A.metadata"
bao policy write ns-read - <<EOF
path "secret/data/{{$M.service_account_namespace}}/*" {
capabilities = ["read"]
}
EOF
bao policy write shop-api-read shop-api-read.hcl
bao policy read shop-api-read
bao policy list
bao token capabilities "$T" secret/data/shop/api # read / deny, ohne Zugriff
bao token capabilities secret/data/shop/api # eigener Token
bao auth list -format=json | jq -r '."kubernetes/".accessor'
| Capability |
Wofür |
read |
Secret lesen (data/), Metadaten lesen
(metadata/) |
list |
Schlüssel auflisten (metadata/) |
create, update |
schreiben (PushSecret: auch auf metadata/) |
deny |
sperrt, schlägt alle anderen Regeln |
Tokens, Wrapping, Leases
bao token create -policy=shop-api-read -ttl=15m -field=token
bao token create -policy=shop-api-read -ttl=60s -use-limit=2 -field=token
bao token lookup # eigener Token
bao token lookup -format=json "$T" | jq -c '.data | {policies, ttl, meta}'
bao token renew # eigener Token, bis max_ttl
bao token revoke -self # am Ende jedes CI-Jobs
bao auth tune -default-lease-ttl=15m -max-lease-ttl=1h kubernetes/
bao read sys/auth/kubernetes/tune
bao kv get -wrap-ttl=5m secret/shop/stripe # Antwort einpacken
bao token create -policy=shop-api-read -wrap-ttl=2m # Token einpacken
bao write sys/wrapping/lookup token="$WRAP" # creation_path prüfen
BAO_TOKEN=$WRAP bao unwrap -field=token # genau einmal
bao list sys/leases/lookup/database/creds/shop-ro-short # aktive Leases
bao lease lookup database/creds/shop-ro-short/<id>
bao lease renew database/creds/shop-ro-short/<id>
bao lease revoke database/creds/shop-ro-short/<id>
bao lease revoke -prefix database/creds/shop-ro-short # Notbremse (Tag 15)
| Begriff |
Bedeutung |
token_ttl |
Laufzeit nach Login und nach jedem Renewal |
token_max_ttl |
harte Grenze, danach nur neuer Login |
token_explicit_max_ttl |
harte Grenze, gilt auch für periodische Tokens |
period |
periodischer Token ohne Maximum (Legacy, vermeiden) |
-use-limit |
Token nach n Anfragen verbraucht (CLI-Vorabfragen zählen mit) |
Auth-Logins
# Kubernetes-Auth: SA-Token mit passender Audience
bao write auth/kubernetes/login role=shop-api \
jwt="$(kubectl -n shop create token shop-api --audience openbao)"
# JWT-Auth (Lab-Issuer aus Tag 10, CI-Token)
BAO_TOKEN= bao write -field=token auth/jwt-ci/login role=deploy-main \
jwt="$(./mint-jwt.sh)"
# AppRole mit gewrappter Secret-ID (Tag 10, Drill 8)
WRAP=$(BAO_TOKEN=$ISSUER bao write -wrap-ttl=120s -field=wrapping_token \
-f auth/approle/role/jenkins-deploy/secret-id)
SECRET_ID=$(BAO_TOKEN=$WRAP bao unwrap -field=secret_id)
BAO_TOKEN= bao write -field=token auth/approle/login \
role_id="$ROLE_ID" secret_id="$SECRET_ID"
# JWT dekodieren (Base64url)
jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'
Kubernetes-Auth-Rolle
bao write auth/kubernetes/role/shop-api \
bound_service_account_names=shop-api \
bound_service_account_namespaces=shop \
audience=openbao \
token_policies=shop-api-read token_ttl=15m token_max_ttl=1h
bao read auth/kubernetes/role/shop-api
bao list auth/kubernetes/role
| Feld |
Zweck |
Lab-Wert |
bound_service_account_names |
erlaubte ServiceAccounts |
shop-api |
bound_service_account_namespaces |
erlaubte Namespaces |
shop |
audience |
genau eine erwartete aud |
openbao |
token_policies |
Policies des OpenBao-Tokens |
shop-api-read |
alias_name_source |
Name des Entity-Alias |
serviceaccount_uid |
bao write auf eine bestehende Kubernetes-Rolle ändert
nur die übergebenen Felder.
JWT-Rolle für Pipelines
bao auth enable -path=jwt-ci jwt
bao write auth/jwt-ci/config [email protected] \
bound_issuer=https://ci.lab.example
# echte Anbieter: oidc_discovery_url=https://token.actions.githubusercontent.com
bao write auth/jwt-ci/role/deploy-main - <<'EOF'
{
"role_type": "jwt",
"user_claim": "sub",
"bound_audiences": ["openbao"],
"bound_claims_type": "string",
"bound_claims": {"repository_id": "100001", "ref": "refs/heads/main"},
"claim_mappings": {"repository": "repository", "run_id": "run_id"},
"token_policies": ["ci-deploy"],
"token_ttl": "5m",
"token_max_ttl": "10m"
}
EOF
| Feld |
Bedeutung |
bound_audiences |
erwartete aud (GitHub: im Workflow setzen, GitLab:
id_tokens.aud) |
bound_subject |
exakter sub, z. B.
repo:acme/shop:environment:production |
bound_claims |
Claims als UND, Liste pro Claim als ODER |
bound_claims_type |
string (exakt) oder glob
(refs/tags/v*) |
claim_mappings |
Claim → Token-Metadatum (Audit-Log, Policy-Templates) |
user_claim |
Name des Entity-Alias, meist sub |
| Anbieter |
Claims zum Binden |
| GitHub Actions |
repository_id, ref,
environment, workflow_ref,
job_workflow_ref |
| GitLab CI |
project_id, ref_protected,
environment, environment_protected |
Kubernetes (jwt-k8s/) |
sub, /kubernetes.io/namespace
(JSON-Pointer) |
External Secrets Operator
apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
name: openbao
namespace: shop
spec:
provider:
vault: # Provider vault, spricht auch mit OpenBao
server: http://openbao.openbao.svc:8200
path: secret # KV-Mount
version: v2 # v1 auf KV v2 = 403, URL ohne data/
auth:
kubernetes:
mountPath: kubernetes
role: shop-api
serviceAccountRef:
name: shop-api
audiences: [openbao] # fehlt sie: invalid audience
---
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} # creationPolicy: Owner (Standard)
data:
- secretKey: DB_PASSWORD # Key im K8s-Secret
remoteRef: {key: shop/api, property: db_password} # ohne secret/, ohne data/
dataFrom:
- extract: {key: shop/stripe} # alle Keys eines Pfads
kubectl -n shop get ss,es # STATUS, READY
kubectl -n shop get events --field-selector involvedObject.name=shop-api
kubectl -n shop annotate es shop-api force-sync="$(date +%s)" --overwrite
kubectl api-resources --api-group=external-secrets.io # v1 bzw. v1alpha1
| Objekt |
API-Version (ESO 2.12.0) |
SecretStore, ClusterSecretStore,
ExternalSecret |
external-secrets.io/v1 |
PushSecret |
external-secrets.io/v1alpha1 |
VaultDynamicSecret (Generator) |
generators.external-secrets.io/v1alpha1 |
Agent Injector
Annotation (vault.hashicorp.com/…) |
Zweck |
agent-inject: "true" |
Pod injizieren |
role: "shop-api" |
Kubernetes-Auth-Rolle |
agent-inject-secret-<datei>: "secret/data/shop/api" |
Pfad, Datei /vault/secrets/<datei> |
agent-inject-template-<datei> |
Go-Template, KV v2: .Data.data.<key> |
agent-inject-perms-<datei>: "0400" |
Dateirechte |
agent-service-account-token-volume-name: "bao-token" |
projiziertes Token mit aud=openbao |
agent-pre-populate-only: "true" |
nur Init, kein Sidecar |
template-static-secret-render-interval: "20s" |
KV-Neurendern (Standard 5 min) |
agent-requests-cpu, agent-limits-mem
… |
Ressourcen der Agents |
error-on-missing-key-<datei>: "true" |
Abbruch statt <no value> (Doku) |
agent-inject-status |
vom Injector gesetzt: injected |
vault.hashicorp.com/agent-inject-template-env: |
{{- with secret "secret/data/shop/api" -}}
export DB_PASSWORD="{{ .Data.data.db_password }}"
{{- end }}
kubectl -n shop logs deploy/shop-api -c vault-agent-init | grep -A7 ERROR
kubectl -n shop logs deploy/shop-api -c vault-agent --tail=5
kubectl -n openbao logs deploy/openbao-agent-injector --tail=5
Secrets Store CSI Driver
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
name: shop-api-bao
namespace: shop # immer der Namespace des Pods
spec:
provider: openbao
secretObjects: # optional: Spiegel in ein K8s-Secret
- secretName: shop-api-csi
type: Opaque
data:
- {objectName: db_password, key: DB_PASSWORD}
parameters:
baoAddress: "http://openbao.openbao.svc:8200"
roleName: "shop-api"
audience: "openbao"
objects: |
- objectName: "db_password"
secretPath: "secret/data/shop/api"
secretKey: "db_password"
Im Pod: Volume csi mit
driver: secrets-store.csi.k8s.io,
readOnly: true und
volumeAttributes.secretProviderClass: shop-api-bao. Fehler
stehen in den Events mit reason=FailedMount, der Pod hängt
in ContainerCreating.
Dynamische Secrets und cert-manager
# Agent-Template für DB-Credentials: Werte unter .Data, nicht .Data.data
vault.hashicorp.com/agent-inject-secret-db: "database/creds/shop-ro-short"
vault.hashicorp.com/agent-inject-template-db: |
{{- with secret "database/creds/shop-ro-short" -}}
export PGUSER="{{ .Data.username }}"
export PGPASSWORD="{{ .Data.password }}"
{{- end }}
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata: {name: openbao, namespace: shop}
spec:
vault:
server: http://openbao.openbao.svc:8200
path: pki/sign/shop-svc
auth:
kubernetes:
role: cert-manager-shop
mountPath: /v1/auth/kubernetes # mit /v1/-Präfix
serviceAccountRef:
name: shop-issuer # cert-manager braucht RBAC für dessen Token
audiences: ["openbao"]
Neuladen
metadata:
annotations:
reloader.stakater.com/auto: "true" # alle referenzierten Secrets
secret.reloader.stakater.com/reload: shop-db # nur diese Secrets
# Helm: Rollout bei jeder Änderung des gerenderten Secrets
annotations:
checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") .
| sha256sum }}
Env-Variablen ändern sich nur mit Neustart. Secret-Volumes
aktualisiert der kubelet (bis ca. 2 min), subPath-Mounts
nie.
GitHub Actions
permissions:
contents: read
id-token: write # ohne das kein OIDC-Token
jobs:
deploy:
environment: production # sub = repo:acme/shop:environment:production
steps:
- uses: hashicorp/vault-action@v4 # produktiv per Commit-SHA pinnen
with:
url: https://openbao.example.com
method: jwt
path: jwt-github
role: shop-prod
jwtGithubAudience: openbao
secrets: |
secret/data/ci/deploy registry_password | REGISTRY_PASSWORD
Ohne Action: JWT per
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=openbao" mit
Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN
holen, mit bao write auth/jwt-github/login einlösen, jeden
Wert per ::add-mask:: maskieren (Tag 11).
GitLab CI
deploy:
image:
name: quay.io/openbao/openbao:2.7.1
entrypoint: [""]
environment: production
id_tokens:
OPENBAO_ID_TOKEN:
aud: https://openbao.lab.example # = bound_audiences der Rolle (Tag 12)
variables:
BAO_ADDR: https://openbao.example.com
script:
- ./ci/bao-secrets.sh # Login mit $OPENBAO_ID_TOKEN, Secret als Datei, revoke
ci/bao-secrets.sh aus Tag 12, Drill 5 (Kern):
BAO_TOKEN=$(bao write -field=token auth/jwt-gitlab/login \
role=shop-deploy jwt="$OPENBAO_ID_TOKEN")
export BAO_TOKEN
umask 077
bao kv get -field=registry_password secret/ci/deploy > "${TMPDIR:-/tmp}/registry-pw"
bao token revoke -self >/dev/null
Premium-Variante secrets: mit vault: plus
VAULT_SERVER_URL, VAULT_AUTH_PATH,
VAULT_AUTH_ROLE siehe Tag 12, Drill 4.
Audit-Log
kubectl -n openbao logs openbao-0 | grep '^{' > audit.jsonl
jq -c 'select(.type=="response" and (.request.path|startswith("secret/data/")))
| {t: .time[11:19], who: .auth.display_name, path: .request.path,
ok: (.error == null)}' audit.jsonl | tail
H=$(bao write -field=hash sys/audit-hash/stdout input=lab-api-key-456)
grep "$H" audit.jsonl | jq -r '[.time, .type, .auth.display_name] | @tsv'
Werte und Tokens stehen nur als hmac-sha256:… im Log.
display_name für Kubernetes-Logins ist
kubernetes-<namespace>-<serviceaccount>.
Fehlermeldung → Ursache
| Meldung |
Ursache |
Erster Befehl |
invalid audience (aud) claim |
Token-aud ≠
audience/bound_audiences |
Token dekodieren, Rolle lesen |
namespace not authorized |
Namespace nicht in der Rolle |
bao read auth/kubernetes/role/<r> |
service account name not authorized |
anderer ServiceAccount |
serviceAccountName vs. Rolle |
invalid role name "x" |
Rolle existiert nicht (Tippfehler) |
bao list auth/kubernetes/role |
permission denied (Login) |
TokenReview sagt nein: Pod/SA weg, Token kaputt |
Token neu holen |
permission denied (Lesen, 403) |
Policy deckt API-Pfad nicht, Token abgelaufen |
URL lesen, bao token capabilities |
claim "x" does not match any associated bound claim values |
CI-Claim passt nicht (Branch, Repo, Environment) |
JWT dekodieren, bound_claims |
claim "x" is missing |
Claim fehlt im JWT (z. B. kein environment:) |
Job-Definition prüfen |
invalid subject (sub) claim |
bound_subject passt nicht |
sub-Format (Tag 11) |
invalid issuer (iss) claim |
falscher Issuer |
bound_issuer |
token is expired |
JWT nach exp benutzt |
Laufzeit beim CI-Anbieter |
no known key successfully validated the token signature |
falscher Schlüssel / falscher Mount |
jwt_validation_pubkeys, Discovery |
wrapping token is not valid or does not exist |
schon ausgepackt oder abgelaufen |
Alarm: wer hat ausgepackt? |
invalid role or secret ID |
Secret-ID verbraucht oder abgelaufen |
neue gewrappte Secret-ID |
check-and-set parameter did not match the current version |
-cas veraltet |
kv metadata get |
TTL … exceeded the effective max_ttl … |
Renewal an token_max_ttl gekappt |
Re-Login einbauen |
lease not found / invalid lease |
Lease widerrufen oder abgelaufen |
neue Credentials holen |
<no value> in gerenderter Datei |
Key im Template fehlt (Injector) |
Key-Namen, error-on-missing-key |
| Kubernetes-Symptom |
Wo nachsehen |
Pod Init:0/1, Injector |
kubectl logs <pod> -c vault-agent-init |
Pod 0/1 statt 0/2, Injector |
Webhook weg (failurePolicy: Ignore), Annotation
agent-inject |
Pod ContainerCreating, CSI |
Events reason=FailedMount |
ExternalSecret SecretSyncedError |
Events reason=UpdateFailed (URL lesen) |
SecretStore InvalidProviderConfig |
Login scheitert: Rolle, Audience, SA |
Store Valid, ExternalSecret rot |
Policy oder Pfad, nicht Login |
Methoden im Vergleich
| Methode |
Secret in etcd? |
Rotation beim Pod |
Gut für |
| ESO (Tag 3/4) |
ja |
refreshInterval + Reloader |
Standard-Apps, GitOps |
| Agent Injector (Tag 5) |
nein |
Sidecar rendert Datei neu |
Apps mit Konfigdateien |
| CSI Driver (Tag 6) |
nein (optional Sync) |
Datei bei aktiver Rotation |
Dateien ohne Sidecar |
App-SDK / bao agent (Tag 8) |
nein |
App liest selbst / exec-Neustart |
dynamische Secrets |
Faustregel aus Tag 9: Kann die App Dateien neu lesen, gewinnt ein
dateibasierter Weg. Braucht sie Env-Variablen, gehört Reloader von
Anfang an dazu. Die ausführliche Matrix steht in Tag 9, Drill 7.