Extending the API
Operators
1.What is an operator ?
An operator is CRDs + a custom controller. It turns a human operator's runbook (install, upgrade, backup, failover) into a reconcile loop that runs forever.
- k8s.io : "software extensions to Kubernetes that make use of custom resources to manage applications and their components." The idea came from a CoreOS blog post.
- Every operator is a controller, not every controller is an operator. The Deployment controller is generic. CloudNativePG knows Postgres : promotion, WAL archiving, backups.
2.What it automates
- Deploy an app on demand
- Take and restore backups
- Upgrades with schema or config changes
- Publish a Service for apps that cannot use the Kubernetes API
- Simulate failure to test resilience
- Leader election for apps that have none
3.Anatomy (k8s.io SampleDB)
Deploy it like any app : CRDs plus a controller Deployment, outside the control plane.
- Users touch only the CR :
kubectl edit SampleDB/.example-database - You write .spec (a change bumps metadata.generation). The operator writes .status.conditions with observedGeneration.
- Children carry an ownerReference, so a StatefulSet change re-runs reconcile.
- Delete the SampleDB : a finalizer takes a snapshot, then the StatefulSet and volumes go.
Every write goes through kube-apiserver. Arrows to the children are shorthand.
4.Capability levels
| In these notes | Level* |
|---|---|
| CloudNativePG | 5 Auto Pilot |
| External Secrets | 4 Deep Insights |
| OTel Operator | 4 Deep Insights |
| cert-manager | 3 Full Lifecycle |
| Knative Operator | 2 Seamless Upgrades |
| Flux CD | 2 Seamless Upgrades |
* OperatorHub level, self-declared by the publisher in the CSV (metadata.). Read the docs before you trust it.
5.Write one, or not ?
| You need | Reach for | Why |
|---|---|---|
| Install / upgrade a stateless app | Helm chart + Flux HelmRelease | Levels 1-2, no Go code to maintain |
| App reads a config file | ConfigMap | k8s.io : a file a Pod reads is not a CR |
| Logic on built-in kinds | Plain controller, --resource=false | No new API needed |
| Validate or default fields | CRD schema + CEL, or admission policy | No webhook (CRDs, Admission) |
| Parent-to-children mapping | Metacontroller | One JSON webhook, it does the watching |
| Non-declarative API | A stand-alone API | k8s.io : CRDs and aggregation fit declarative only |
| It already exists | Install it | Someone else carries the pager |
| Backup, failover, ordered upgrades | Write an operator | Level 3+ is why operators exist |
1.One reconcile pass
Red dashed : a step failed, Result ignored, retry with backoff. Each pass reads the current state, never "what changed". Finalizer and ownerReference rules : Owners, Finalizers and GC.
2.The calls (controller-runtime v0.25)
func (r *SampleDBReconciler) Reconcile(ctx context.Context,
req ctrl.Request) (res ctrl.Result, err error) {
var db dbv1.SampleDB
if err = r.Get(ctx, req.NamespacedName, &db); err != nil {
return res, client.IgnoreNotFound(err) } // gone : nil
if db.DeletionTimestamp != nil { // final backup first
controllerutil.RemoveFinalizer(&db, fin)
return res, r.Update(ctx, &db) }
if controllerutil.AddFinalizer(&db, fin) {
return res, r.Update(ctx, &db) }
sts := child(&db) // *appsv1.StatefulSet, name + namespace
_, err = controllerutil.CreateOrUpdate(ctx, r.Client, sts,
func() error { // set sts.Spec, then own it
return ctrl.SetControllerReference(&db, sts, r.Scheme) })
if err != nil { return res, err }
meta.SetStatusCondition(&db.Status.Conditions, ready(&db))
res.RequeueAfter = time.Hour // periodic work
return res, r.Status().Update(ctx, &db)
}
Builder : For(&dbv1., a child change requeues. Requeue: true is deprecated, reconcile. stops retries.
3.Pick a toolkit
| Tool (language) | Latest | You write | Used here / notes |
|---|---|---|---|
| controller-runtime (Go) | v0.25.2 | Reconcile(ctx, req) (Result, error) | Flux CD, CNPG, ESO |
| Kubebuilder (Go) | v4.16.0 | Types, markers, Reconcile | CNPG, ESO, OTel |
| Operator SDK (Go, Ansible, Helm) | v1.42.3 | Go via Kubebuilder, a playbook or a chart | OTel plugins. Helm type : level 2 max |
| Java Operator SDK (Java) | v5.6.2 | A Reconciler class (fabric8 client) | Quarkus extension |
| Kopf (Python 3.11+) | 1.44.6 | @kopf.on.create, timer, daemon | Feature-complete, stable |
| kube-rs (Rust) | 4.2.0 | async fn reconcile(obj, ctx) | In kube::runtime |
| Metacontroller (any) | v4.17.2 | A JSON sync webhook | API still v1alpha1 |
| OLM v1 operator-controller | v1.12.0 | A ClusterExtension : package + channel | OperatorHub.io catalog, cluster-admin |
4.Build, test, ship (Kubebuilder)
| Command | Does |
|---|---|
| kubebuilder init --domain <domain> --repo <go-module> | Scaffold the project and a Kind e2e suite |
| kubebuilder create api --group db --version v1alpha1 --kind SampleDB | CRD Go type, controller, envtest suite |
| make manifests generate | CRD YAML + ClusterRole from markers, DeepCopy |
| make install run | CRDs in, controller runs on your laptop |
| make test | envtest : etcd + kube-apiserver from setup-envtest (KUBEBUILDER_ASSETS) |
| make test-e2e | Kind cluster + Ginkgo, deleted on pass |
| make docker-build docker-push IMG=<image> && make deploy IMG=<image> | Push image, deploy CRDs, RBAC, Deployment |
5.Gotchas & good to know
- Finalizer deadlock : remove the operator before its CRs and they hang in Terminating.
- ownerReferences cannot cross namespaces (OwnerRefInvalidNamespace events).
- envtest has no controller-manager : no GC, no Pods. Assert ownerReferences, .status.
- Keep
--leader-electon before replicas > 1. - Upgrade the operator first. It only knows operands up to its own version.
- Operator down : the app keeps serving, only automation pauses.
- OLM v1 installs, then upgrades along the channel.