external-secrets — Kubernetes secrets-synchronization operator
This example compiles a small, real stack — the external-secrets operator —
from one Developer-authored Aggregate to Kubernetes, backed by the official
external-secrets Helm chart.
external-secrets synchronizes secret material from external secret-management
systems — HashiCorp Vault, AWS Secrets Manager, Google Secret Manager, Azure Key
Vault, and others — into native Kubernetes Secrets, keeping them in sync as the
source changes. It is a cluster-scoped controller that extends the cluster API
with its own custom resources rather than a server applications route to, so it
takes no uses edge, and all it publishes is where a Prometheus server finds
its metrics: applications obtain their secrets by declaring ExternalSecret and
SecretStore resources, and the operator materializes the corresponding
Kubernetes Secrets.
Files
| File | Role |
|---|---|
aggregate.yaml | Developer intent: a single external-secrets component (core/security/external-secrets) installing the custom resource definitions with the release. |
manifest.yaml | Maps the component type to the official sourced Recipe (external-secrets). |
release.yaml | Operator record for the Kubernetes target: the operator’s compute sizing. |
What it demonstrates
- One authoring surface. A single Aggregate is the source of truth for what the operator is; the Manifest says how to realize it.
- A developer value flows to the render. The developer’s
install_crdsvalue is written into the chart’sinstallCRDsvalue, bringing the external-secrets custom resource definitions into the cluster with the release. - A cluster-extending controller, no topology edge. external-secrets adds
its own custom resources to the cluster API; consumers request secrets by
declaring those resources, so the component wires no
usesedge and exports nothing but where its metrics are. - A single coherent operator. The chart renders the controller, the webhook, and the certificate controller as one operator; the bundled provider subchart is off, so no foreign datastore, cache, or broker is pulled in. The rendered output is byte-identical across runs of the same input.
- A reproducible image. The Recipe pins all three container images to a
resolvable release tag (
ghcr.io/external-secrets/external-secrets:v2.7.0), so the rendered workloads reference a pinned version.
Scaffold the example
You can build this example with the commands below, or have your AI assistant build it for you.
Write the example into a new folder named after it:
aggrega scaffold --example external-secrets-operatorIt then prints the commands to run next. The first changes into the new folder:
cd external-secrets-operatorBuild
This workspace carries no .aggrega-config.yaml, so the standard-library
entities resolve from the hub registry, hub.aggrega.ai, and no catalog flag is
needed:
aggrega pull --release release.yamlaggrega build --release release.yamlRendered artifacts land under dist/. The build resolves the upstream chart by
OCI reference on aggrega pull and pins it in a lockfile.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `external-secrets-operator` folder yet, call the `scaffold` tool once with `example` set to `external-secrets-operator` and no `dir`: it writes the example into a new `external-secrets-operator` folder. Then call the `build` tool with `workspace_root` set to `external-secrets-operator`, `release` set to `release.yaml`, `auto_pull` set to true and `write` set to true. Tell me which files the build wrote; they are under `external-secrets-operator/dist/`.What renders
The build emits the external-secrets operator as a set of Kubernetes objects:
- 24
CustomResourceDefinitions for the external-secrets API (ExternalSecret,SecretStore,ClusterSecretStore, and the related push and generator resources), - three
Deployments — the controller, the webhook, and the certificate controller, - the RBAC that binds them:
ClusterRoles,ClusterRoleBindings, aRole, and aRoleBinding, - three
ServiceAccounts, one per workload, - a
Servicefor the webhook, - two
ValidatingWebhookConfigurations, - a placeholder
Secretthe certificate controller populates with the webhook’s serving certificate at runtime.
All three container images are pinned to their release tag, so the workloads reference pinned images.