Configure Kubernetes secrets management with External Secrets Operator and HashiCorp Vault

Install the Vault CLI and verify connectivity

The Vault CLI lets you configure policies and auth methods from your workstation or a bastion host.

wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install -y vault

sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo dnf install -y vault

export VAULT_ADDR="https://vault.example.com:8200"
vault status

Enable the KV v2 secrets engine

KV version 2 supports versioning, which lets you roll back accidental overwrites of application secrets.

vault login
vault secrets enable -path=kv-eso kv-v2
vault kv put kv-eso/production/api-service DB_PASSWORD="Str0ng-P@ss-2024!" API_KEY="ak_live_9f3c7d2a1b"

Enable the Kubernetes auth method in Vault

This lets Vault verify tokens presented by pods against your cluster's API server, without storing static credentials anywhere.

vault auth enable kubernetes

Retrieve the cluster CA and API endpoint, then configure Vault to talk to your cluster.

kubectl config view --raw --minify --flatten -o jsonpath='{.clusters[].cluster.certificate-authority-data}' | base64 -d > /tmp/k8s-ca.crt
KUBE_HOST=$(kubectl config view --raw --minify --flatten -o jsonpath='{.clusters[].cluster.server}')

vault write auth/kubernetes/config \
  kubernetes_host="$KUBE_HOST" \
  kubernetes_ca_cert=@/tmp/k8s-ca.crt

Create a least-privilege Vault policy

Scope the policy to only the paths ESO needs to read. Never grant blanket access to the entire KV mount.

path "kv-eso/data/production/*" {
  capabilities = ["read"]
}

path "kv-eso/metadata/production/*" {
  capabilities = ["list", "read"]
}

vault policy write eso-production-read vault-eso-policy.hcl

Create a Kubernetes auth role bound to a service account

Binding the Vault role to a specific service account and namespace enforces that only ESO pods in that namespace can assume this role, which is the core of namespace isolation.

vault write auth/kubernetes/role/eso-production-role \
  bound_service_account_names=external-secrets-sa \
  bound_service_account_namespaces=external-secrets \
  policies=eso-production-read \
  ttl=15m

Deploy External Secrets Operator with Helm

ESO ships an official Helm chart that installs the controller, webhook, and CRDs. Deploy it into a dedicated namespace to keep it isolated from application workloads.

kubectl create namespace external-secrets
helm repo add external-secrets https://charts.external-secrets.io
helm repo update

helm install external-secrets external-secrets/external-secrets \
  --namespace external-secrets \
  --set installCRDs=true \
  --set replicaCount=2 \
  --set serviceAccount.name=external-secrets-sa

Two replicas give you a controller failover path if a pod is evicted or the node drains during maintenance.

Verify the operator is running

Confirm the controller, webhook, and cert-controller pods reach Running state before creating any secret store resources.

kubectl get pods -n external-secrets
kubectl get crd | grep external-secrets.io

Create a ClusterSecretStore for cluster-wide access

A ClusterSecretStore is not namespaced and can be referenced by ExternalSecret resources across the cluster, useful for shared credentials like registry pull secrets or platform-wide TLS certs.

apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "https://vault.example.com:8200"
      path: "kv-eso"
      version: "v2"
      auth:
        kubernetes:
          mountPath: "kubernetes"
          role: "eso-production-role"
          serviceAccountRef:
            name: "external-secrets-sa"
            namespace: "external-secrets"

kubectl apply -f manifests/cluster-secret-store.yaml
kubectl get clustersecretstore vault-backend -o wide

Create a namespace-scoped SecretStore

Use a SecretStore instead of a ClusterSecretStore when a team should only sync secrets within its own namespace, reinforcing the isolation established by the RBAC and Vault role bindings above.

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend-app
  namespace: production
spec:
  provider:
    vault:
      server: "https://vault.example.com:8200"
      path: "kv-eso"
      version: "v2"
      auth:
        kubernetes:
          mountPath: "kubernetes"
          role: "eso-production-role"
          serviceAccountRef:
            name: "external-secrets-sa"
            namespace: "production"

kubectl create namespace production
kubectl apply -f manifests/app-secret-store.yaml

Define an ExternalSecret to sync into a Kubernetes Secret

The ExternalSecret is the resource that actually maps Vault paths to keys inside a generated Kubernetes Secret. The refreshInterval controls how often ESO re-reads Vault.

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: api-service-secrets
  namespace: production
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend-app
    kind: SecretStore
  target:
    name: api-service-secrets
    creationPolicy: Owner
  data:
    - secretKey: DB_PASSWORD
      remoteRef:
        key: production/api-service
        property: DB_PASSWORD
    - secretKey: API_KEY
      remoteRef:
        key: production/api-service
        property: API_KEY

kubectl apply -f manifests/api-service-external-secret.yaml
kubectl get externalsecret api-service-secrets -n production
kubectl get secret api-service-secrets -n production -o jsonpath='{.data}'

Use templating to reshape synced secrets

Templating lets you build connection strings or config file formats directly from multiple Vault values instead of requiring the application to assemble them at runtime.

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: api-service-connection
  namespace: production
spec:
  refreshInterval: 30m
  secretStoreRef:
    name: vault-backend-app
    kind: SecretStore
  target:
    name: api-service-connection
    creationPolicy: Owner
    template:
      engineVersion: v2
      data:
        DATABASE_URL: "postgres://app_user:{{ .DB_PASSWORD }}@postgres-primary.production.svc.cluster.local:5432/appdb"
  data:
    - secretKey: DB_PASSWORD
      remoteRef:
        key: production/api-service
        property: DB_PASSWORD

Configure RBAC to restrict who can read synced Secrets and ExternalSecrets

ESO synchronizing Vault into a namespace does not automatically restrict which cluster users can read that Secret. Apply RBAC in the target namespace so only the application's service account and approved operators can view it.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: production
  name: secret-reader
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    resourceNames: ["api-service-secrets", "api-service-connection"]
    verbs: ["get"]

kubectl apply -f manifests/secret-reader-role.yaml
kubectl create rolebinding api-service-secret-reader \
  --role=secret-reader \
  --serviceaccount=production:api-service-sa \
  -n production

For a deeper walkthrough of scoping cluster roles and service accounts, see configure Kubernetes RBAC with service accounts and cluster roles.