External Secrets Operator
The External Secrets Operator (ESO) is a Kubernetes controller that reads secrets from an external store and writes them into ordinary Kubernetes Secrets, keeping them refreshed. In the Web App Blueprint it is the last hop between Parameter Store and the application's environment variables.
What it does
You declare a SecretStore or ClusterSecretStore that says which backend to read and how to authenticate, and an ExternalSecret that lists which remote keys to fetch and which Kubernetes Secret to write. ESO fetches the values, creates the Secret, and re-reads the backend on an interval. Pods consume the Secret the normal way; nothing in the chart or in Git holds a secret value.
How BuiltForProd uses it
The external-secrets unit in acme-aws-blueprint-webapp-infra installs the external-secrets chart (version 2.6.0) into the external-secrets namespace with its CRDs. Its ServiceAccount external-secrets-sa gets an EKS Pod Identity role, acme-usw2-dev-eso-pod-id, whose policy allows ssm:GetParameter, ssm:GetParameters and ssm:GetParametersByPath on /acme/usw2/dev/* and read access to Secrets Manager secrets under the same prefix. It cannot read any other stage's parameters.
The ClusterSecretStore named aws-ssm, pointing at Parameter Store in the stage's region, is created by the argocd unit rather than here, so that it lands in a separate state after the operator's custom resource definitions are established.
The consumer is the chart in acme-aws-blueprint-webapp-gitops. When externalSecrets.enabled is true in values-<stage>.yaml (it is for dev, staging and prod, with ssmPrefix set to acme/usw2/dev, acme/usw2/stg and acme/usw2/prd), the template external-secret.yaml renders an ExternalSecret named blueprint-app-secrets:
| Secret key | Remote parameter |
|---|---|
DOCDB_HOST | /acme/usw2/prd/documentdb/endpoint |
DOCDB_PASSWORD | /acme/usw2/prd/documentdb/master_password |
REDIS_HOST | /acme/usw2/prd/elasticache/endpoint |
It refreshes every hour. The Deployment then reads those three values from the Secret instead of from plain values. When the DocumentDB password is rotated by a version bump, the application picks it up on the next refresh or pod restart.
The infrastructure modules publish the endpoints and password; the SOPS workflow publishes third-party credentials to the same prefix, so any application secret can be delivered the same way by adding a data entry to the ExternalSecret.
Terms you will see
| Term | Meaning |
|---|---|
| ClusterSecretStore | The cluster-wide definition of a backend, here aws-ssm. |
| ExternalSecret | The declaration of which remote keys become which Secret keys. |
| Refresh interval | How often ESO re-reads the backend, here one hour. |
| Remote ref | The path of one value in the backend. |
| Creation policy | Who owns the resulting Secret; Owner means ESO manages it fully. |
Where to read more
- Web App Blueprint overview
- Systems Manager Parameter Store for the source
- SOPS for how human-managed secrets get there
- DocumentDB for the password rotation it follows