Skip to content
AggregaAggrega
Select language: English

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

FileRole
aggregate.yamlDeveloper intent: a single external-secrets component (core/security/external-secrets) installing the custom resource definitions with the release.
manifest.yamlMaps the component type to the official sourced Recipe (external-secrets).
release.yamlOperator 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_crds value is written into the chart’s installCRDs value, 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 uses edge 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:

Terminal window
aggrega scaffold --example external-secrets-operator

It then prints the commands to run next. The first changes into the new folder:

Terminal window
cd external-secrets-operator

Build

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:

Terminal window
aggrega pull --release release.yaml
aggrega build --release release.yaml

Rendered 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, a Role, and a RoleBinding,
  • three ServiceAccounts, one per workload,
  • a Service for the webhook,
  • two ValidatingWebhookConfigurations,
  • a placeholder Secret the 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.