cert-manager — Kubernetes TLS-certificate lifecycle controller
This example compiles a small, real stack — a cert-manager certificate
controller — from one Developer-authored Aggregate to Kubernetes. The
developer declares what cert-manager is; a single Ops Recipe maps that intent
to the official cert-manager Helm chart from the jetstack registry and renders
the Kubernetes objects.
cert-manager is a cluster-scoped Kubernetes add-on that automates the issuance
and renewal of X.509 certificates from issuing sources such as ACME (Let’s
Encrypt), a private CA, or Vault. It extends the cluster with its own
Certificate, Issuer, and ClusterIssuer custom resources. Applications ask
for certificates by declaring those resources — not by wiring an upstream — so
the component takes no uses edge. For the same reason it has no standalone
local-container form, so this family ships a Helm Recipe only; there is no
Compose target. All the component publishes is where a Prometheus server finds
its metrics.
Files
| File | Role |
|---|---|
aggregate.yaml | Developer intent: a single cert-manager component (core/security/cert-manager) with CRD installation on. |
manifest.yaml | Maps the component type to the cert-manager Helm Recipe (cert-manager). |
release.yaml | Operator record for the Kubernetes target: the controller/webhook/CA-injector sizing. |
What it demonstrates
- One authoring surface, realized by an Ops Recipe. The Aggregate is the source of truth for what cert-manager is. The Manifest says how to realize it by mapping the component type to a Recipe by name; the Release supplies the operational sizing. Developer intent and Ops mapping stay separate.
- Three coordinated workloads from one component. The Recipe renders all
three halves of cert-manager: a
Deploymentfor the controller that reconciles certificate requests, aDeploymentfor the webhook that validates and defaults the custom resources, and aDeploymentfor the CA injector that wires the webhook’s CA bundle into the cluster. - Certificate API installation. The developer’s
install_crdsvalue flows into the chart, which installs cert-manager’sCustomResourceDefinitions (theCertificate,Issuer,ClusterIssuer, and ACMEOrder/Challengeresources). Set it false when the CRDs are managed out of band. - Admission wiring. The chart emits the
ValidatingWebhookConfigurationandMutatingWebhookConfigurationthe webhook serves, the webhookService, and the full RBAC set — oneClusterRole/ClusterRoleBindingper controller responsibility plus the leader-electionRoles — so the controller has the permissions it needs. - Reproducible images. The chart ships resolvable release tags; the Recipe re-pins the controller, webhook, CA-injector, and ACME solver images to those tags so the rendered workloads reference pinned versions.
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 cert-manager-tlsIt then prints the commands to run next. The first changes into the new folder:
cd cert-manager-tlsBuild
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 `cert-manager-tls` folder yet, call the `scaffold` tool once with `example` set to `cert-manager-tls` and no `dir`: it writes the example into a new `cert-manager-tls` folder. Then call the `build` tool with `workspace_root` set to `cert-manager-tls`, `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 `cert-manager-tls/dist/`.What renders
The build emits the full cert-manager stack — three Deployments (the
controller, the webhook, and the CA injector), the six cert-manager
CustomResourceDefinitions when install_crds is on, a
ValidatingWebhookConfiguration and a MutatingWebhookConfiguration, the
webhook Service, the controller ServiceAccounts, and the RBAC set of
ClusterRoles, ClusterRoleBindings, and leader-election Roles and
RoleBindings. It also includes a post-install Job (the startup API check
that blocks until the certificate API is serving) and a metrics Service each
for the controller and the CA injector — 50 Kubernetes objects in all. The
controller, webhook, CA-injector, and ACME-solver images are pinned to their
release tags, so every workload references a pinned image tag.