External Secrets

External Secrets Operator

Overview

External Secrets Operator (ESO) synchronizes Kubernetes Secrets from external secret management systems. It watches custom resources and reconciles K8s Secrets from the provider's values.

CRDs: SecretStore, ClusterSecretStore, ExternalSecret, ClusterExternalSecret, PushSecret, ClusterPushSecret.

Latest: chart 2.6.0, app v2.6.0.

Architecture

K8s API (ExternalSecret CR)
  → ESO controller watches for changes
    → Queries external provider (Vault, AWS, GCP, Azure...)
      → Creates/updates K8s Secret
        → Template engine processes data (v2)

Three components:

CRDs

SecretStore / ClusterSecretStore

Defines how ESO authenticates to a provider. SecretStore is namespaced, ClusterSecretStore is cluster-scoped.

apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "http://vault.vault:8200"
      path: "secret"
      version: v2
      auth:
        kubernetes:
          mountPath: "kubernetes"
          role: "eso-reader"
          serviceAccountRef:
            name: "external-secrets"

Key fields:

Provider auth methods (Vault):

ExternalSecret

Defines what secret to fetch and how to store it as a K8s Secret.

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: app-secrets
spec:
  refreshInterval: "1h"
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: my-app-secret          # K8s Secret name
    creationPolicy: Owner
    deletionPolicy: Retain
    template:
      type: Opaque
      metadata:
        labels:
          app: my-app
  data:
    - secretKey: password
      remoteRef:
        key: secret/data/myapp
        property: password
  dataFrom:
    - extract:
        key: secret/data/myapp

Key fields:

PushSecret

Pushes a K8s Secret value to an external provider (reverse sync).

apiVersion: external-secrets.io/v1beta1
kind: PushSecret
metadata:
  name: push-myapp
spec:
  refreshInterval: "1h"
  secretStoreRefs:
    - name: vault-backend
      kind: ClusterSecretStore
  data:
    - match:
        secretKey: password
        remoteRef:
          remoteKey: secret/data/pushed/myapp

ClusterExternalSecret

Cluster-scoped ExternalSecret that projects into multiple namespaces:

apiVersion: external-secrets.io/v1beta1
kind: ClusterExternalSecret
metadata:
  name: cluster-app-secrets
spec:
  externalSecretName: app-secrets
  namespaceSelector:
    matchLabels:
      eso-inject: "true"
  refreshTime: "1h"

Template Engine (v2)

ESO's template engine uses Go text/template. Applied via spec.target.template:

spec:
  target:
    template:
      type: kubernetes.io/tls
      data:
        tls.crt: "{{ .crt | base64decode }}"
        tls.key: |
          {{ .key | base64decode | strings.TrimSuffix "\n" }}

Available functions:

mergePolicy: Controls how template data merges with secret data:

Refresh Policies

Helm Values

Metrics

ESO exposes Prometheus metrics on port 8080 (default):

Common Mistakes

• KV v1 vs v2 path mismatch. Vault KV v2 paths use data/ prefix internally. ESO handles this when version: v2 is set. Set version: v1 for KV v1 engines. Wrong version = 404 errors.
• K8s auth role without policy. The role eso-reader must be created in Vault first with a policy attached. ESO errors with permission denied if the role exists but has no policy.
• ServiceAccount in wrong namespace. serviceAccountRef.name must exist in the ESO controller namespace (not the ExternalSecret namespace). Cross-namespace SA references require serviceAccountRef.namespace.
• refreshInterval: "CreatedOnce" doesn't update. If the provider value changes, ESO won't re-fetch. Use Periodic for dynamic secrets.
• Template errors are silent. A bad template renders the secret with empty values. Use kubectl describe externalsecret to check status conditions.
• creationPolicy: Orphan on existing Secret. ESO won't take ownership but also won't update it. The Secret becomes read-only from ESO's perspective.
• ClusterSecretStore can reference any namespace SA. Make sure the SA referenced has appropriate permissions. ClusterSecretStore is NOT namespace-scoped.
• Metrics port conflicts. If another service uses port 8080, set metrics.service.port or disable metrics.

Deployment (Flux HelmRelease)

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: external-secrets
  namespace: external-secrets
spec:
  chart:
    spec:
      chart: external-secrets
      sourceRef:
        kind: HelmRepository
        name: external-secrets
      version: 2.6.0
  values:
    installCRDs: true
    serviceMonitor:
      enabled: true
    webhook:
      certManager:
        enabled: true
        issuerRef:
          kind: ClusterIssuer
          name: letsencrypt-production
    certController:
      enabled: false
    vault:
      enableTokenCache: false
    concurrent: 1
    leaderElect: true