History

ESO evolved from the earlier Kubernetes External Secrets project, which was limited in flexibility and extensibility. ESO was redesigned using the Kubernetes controller-runtime framework, introducing Custom Resource Definitions (CRDs) such as ExternalSecret, SecretStore, and ClusterSecretStore. This shift enabled better integration, automation, and scalability across different cloud environments and secret backends.

Why It Matters

Managing secrets securely is critical in any production environment. Kubernetes’ native secrets are stored in etcd and, by default, are only base64-encoded—not encrypted. ESO solves this by allowing secrets to live in purpose-built external secret managers, which offer:

  • Encryption at rest and in transit
  • Role-based access control (RBAC)
  • Secret versioning and auditing
  • Centralized security policies

By integrating external secrets with Kubernetes, ESO helps reduce:

  • Secret sprawl and duplication
  • Manual synchronization errors
  • Exposure of sensitive credentials in source code or CI pipelines

Key Concepts and CRDs

  • ExternalSecret: Defines which external secret to fetch and how to project it into a Kubernetes Secret.
  • SecretStore: A namespace-scoped reference to an external provider (e.g., Vault, AWS, GCP).
  • ClusterSecretStore: A cluster-wide version of SecretStore used for multi-namespace secret access.

Each ExternalSecret is linked to a SecretStore or ClusterSecretStore, which contains authentication and configuration information for the external secret backend.

How It Works

  1. A SecretStore or ClusterSecretStore is defined to authenticate with the external secret manager.
  2. An ExternalSecret CR is created, referencing the store and specifying which secret to retrieve.
  3. ESO reads the external secret, applies any defined templates, and creates or updates a native Kubernetes Secret.
  4. The Secret is kept in sync with the external source based on polling intervals or update triggers.

Use Cases

✅ Centralized Secret Management

Use AWS Secrets Manager, Vault, or Azure Key Vault to manage credentials and expose them only at runtime via Kubernetes.

✅ Multi-Cluster Secret Access

Use ClusterSecretStore to allow teams to pull shared secrets across multiple namespaces or clusters.

✅ Dynamic Secret Syncing

Automatically propagate secret updates from Vault into your Kubernetes apps without redeploying them.

✅ Least Privilege Principle

Configure ESO to access only specific secrets via IAM policies or Vault roles, enforcing granular security controls.

Example: Using ESO with AWS Secrets Manager


  apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: my-db-secret
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: aws-secrets
    kind: SecretStore
  target:
    name: my-db-secret
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: prod/db-credentials
        property: username
    - secretKey: password
      remoteRef:
        key: prod/db-credentials
        property: password

This configuration pulls a username and password from AWS Secrets Manager and stores them as a Kubernetes Secret named my-db-secret.

Benefits

  • Eliminates secret duplication across environments
  • Enforces separation of duties between DevOps and security teams
  • Seamlessly integrates with GitOps and CI/CD workflows
  • Supports templating and transformation of secret values

Challenges

  • Requires proper IAM and backend configuration
  • Polling-based sync may delay secret rotation unless carefully tuned
  • Secrets still reside in Kubernetes memory and can be accessed by privileged users if not protected

Supported Providers

  • AWS Secrets Manager
  • HashiCorp Vault
  • Azure Key Vault
  • Google Secret Manager
  • IBM Cloud Secrets Manager
  • Akeyless, 1Password, and more

Related Tools

  • Vault Agent Injector: Sidecar that injects secrets into pods directly from Vault.
  • Sealed Secrets: Encrypt secrets for safe storage in Git.
  • SOPS + Kustomize: Manage secrets in encrypted Git files.

See Also