Skip to content
AggregaAggrega
Select language: English

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

FileRole
aggregate.yamlDeveloper intent: a single cert-manager component (core/security/cert-manager) with CRD installation on.
manifest.yamlMaps the component type to the cert-manager Helm Recipe (cert-manager).
release.yamlOperator 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 Deployment for the controller that reconciles certificate requests, a Deployment for the webhook that validates and defaults the custom resources, and a Deployment for the CA injector that wires the webhook’s CA bundle into the cluster.
  • Certificate API installation. The developer’s install_crds value flows into the chart, which installs cert-manager’s CustomResourceDefinitions (the Certificate, Issuer, ClusterIssuer, and ACME Order/Challenge resources). Set it false when the CRDs are managed out of band.
  • Admission wiring. The chart emits the ValidatingWebhookConfiguration and MutatingWebhookConfiguration the webhook serves, the webhook Service, and the full RBAC set — one ClusterRole/ClusterRoleBinding per controller responsibility plus the leader-election Roles — 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:

Terminal window
aggrega scaffold --example cert-manager-tls

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

Terminal window
cd cert-manager-tls

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 `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.