Zum Inhalt springen
Trainingslager IT-Trainingslager

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.