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 an external-secrets-vault ServiceAccount through the TokenRequest API, which the chart's controller ClusterRole allows in every namespace (cluster-secret-store.yaml binds its own external-secrets-vault-token-creator ClusterRole, scoped to that ServiceAccount name, beside it); OpenBao validates it against the TokenReview API and issues a token bound to that store's policy. Platform namespaces use the openbao store and the ServiceAccount in external-secrets; a workload uses openbao-apps and its own, which confines it to kv/<namespace>/ — see Kubernetes auth. No long-lived credential exists anywhere. The stores use ESO's vault provider unchanged against the in-cluster Service.

In application.yaml's valuesObject:

Usage¶

Adding a secret¶

1. Store the value in OpenBao, following the KV layout. A random value is not typed in at all: a Password generator and a PushSecret write it, see Generated secrets.

   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. A workload names openbao-apps and ships the ServiceAccount that store logs in as; a platform component names openbao instead and needs no ServiceAccount:

   ---
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: external-secrets-vault
     namespace: my-app
     annotations:
       argocd.argoproj.io/sync-wave: "-2"
   automountServiceAccountToken: false
   ---
   apiVersion: external-secrets.io/v1
   kind: ExternalSecret
   metadata:
     name: my-app-credentials
     namespace: my-app
     annotations:
       # ESO's CRDs arrive with the external-secrets Application; this
       # covers a sync before they have landed.
       argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true
   spec:
     refreshInterval: 1h
     secretStoreRef:
       name: openbao-apps
       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: my-app/<purpose>   # the namespace is the prefix
           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. openbao-apps and openbao-claude-agents report Valid without logging in, so their auth failures show on the ExternalSecret instead:

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

Then the individual object:

kubectl describe externalsecret -n <namespace> <name>

Pitfalls¶