External Secrets Operator¶

External Secrets Operator (ESO) bridges OpenBao to native Kubernetes Secret objects. Workloads consume secrets the standard way — envFrom, volumeMounts, imagePullSecrets — with no sidecar, no init container and no code that knows what a Vault token is.

At a glance¶

Configuration¶

sequenceDiagram
    participant App as Workload
    participant ES as ExternalSecret
    participant ESO as ESO Controller
    participant Bao as OpenBao
    participant K as K8s Secret

    ESO->>Bao: login (k8s SA JWT)
    Bao-->>ESO: vault token
    ESO->>Bao: read kv/path
    Bao-->>ESO: secret data
    ESO->>K: create/update Secret
    App->>K: mount / envFrom

ESO mints a short-lived token for its external-secrets-vault ServiceAccount through the TokenRequest API (the external-secrets-vault-token-creator ClusterRole); OpenBao validates it against the TokenReview API and issues a token bound to the external-secrets policy. No long-lived credential exists anywhere, and when it breaks it breaks in the ClusterSecretStore status. The store uses ESO's vault provider unchanged against the in-cluster Service.

Usage¶

Adding a secret¶

1. Store the value in OpenBao, following the KV layout:

   bao kv put kv/<workload>/<purpose> key1="value1" key2="value2"
   

2. Declare an ExternalSecret alongside the workload's other manifests; the parent Application picks it up:

   ---
   apiVersion: external-secrets.io/v1
   kind: ExternalSecret
   metadata:
     name: my-app-credentials
     namespace: my-app
     annotations:
       # ESO and its CRDs install in 03-controllers; this covers a sync
       # before they have landed.
       argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true
   spec:
     refreshInterval: 1h
     secretStoreRef:
       name: openbao
       kind: ClusterSecretStore
     target:
       name: my-app-credentials   # name of the resulting K8s Secret
       creationPolicy: Owner
     data:
       - secretKey: key1           # key in the K8s Secret
         remoteRef:
           key: <workload>/<purpose>
           property: key1          # key inside the KV entry
   

   To pull every key without listing them, use dataFrom instead of data:

   spec:
     dataFrom:
       - extract:
           key: <workload>/<purpose>
   

3. Consume the Secret:

   spec:
     containers:
       - name: my-app
         envFrom:
           - secretRef:
               name: my-app-credentials
   

refreshInterval polls OpenBao; 0 disables polling and re-syncs only on resource changes. To sync now rather than wait:

kubectl annotate externalsecret -n <namespace> <name> \
  force-sync=$(date +%s) --overwrite

Health check¶

Start with the store; if it is not Ready, nothing downstream is either:

kubectl get clustersecretstore openbao -o jsonpath='{.status}' | jq

Then the individual object:

kubectl describe externalsecret -n <namespace> <name>

Pitfalls¶