Skip to content

Operators and CRDs

CRDs extend the Kubernetes API. Operators add automation logic for those custom resources.

Together, they let teams model and automate complex domain workflows directly in Kubernetes.

CRD basics

A CustomResourceDefinition introduces a new API type.

After a CRD is installed, users can create custom objects with normal Kubernetes workflows (kubectl, GitOps, admission policies, RBAC).

Operator basics

An Operator is a controller that watches custom resources and reconciles desired state into concrete Kubernetes objects and operational actions.

Examples of operator-managed actions:

  • bootstrapping clustered databases
  • performing version-aware upgrades
  • backup and restore orchestration
  • failover and lifecycle management

Why Operators are useful

For complex stateful systems, raw Deployments and StatefulSets are not enough to encode day-2 operations safely.

Operators capture domain runbook logic in code so it is repeatable and observable.

High-level flow

flowchart LR
  A[Custom Resource] --> B[Operator Controller]
  B --> C[StatefulSet, Service, Secret, PVC]
  C --> D[Observed State]
  D --> B

Writing a good reconciler (the rules that matter)

Whether you build operators or just operate them, understanding the reconciliation contract explains their behavior:

  • Reconcile the whole state, not the event. A correct reconciler ignores what changed and asks "given the current desired state, what should exist?" This makes it naturally idempotent -- running it twice does nothing the second time -- and means missed events don't matter.
  • Expect to run again. Reconcilers re-run on every change, on periodic resync, and after controller restarts. Any action that isn't safe to repeat (sending an email, charging a card) doesn't belong in a reconcile loop without external deduplication.
  • Status is the contract. Well-built operators report progress and errors in the custom resource's status and conditions. kubectl describe <cr> should tell you why something is stuck before you resort to operator logs.
  • Finalizers explain stuck deletions. Operators add finalizers to clean up external resources before an object disappears. If the operator is down or broken, deletion hangs -- the most common operator-related incident.

When to choose Helm vs Operator

  • choose Helm for packaging and straightforward lifecycle
  • choose Operator when continuous domain-specific reconciliation is required

Many platforms use both: Helm to install the operator, operator to manage the application lifecycle.

Operational checks

kubectl get crd
kubectl get <custom-resource-plural> -A
kubectl describe <custom-resource-kind> <name> -n <namespace>
kubectl logs deploy/<operator-deployment> -n <operator-namespace>

Governance considerations

  • review CRD schema quality before adoption
  • constrain operator RBAC to least privilege
  • monitor operator upgrades like any control-plane dependency
  • validate backup and restore behavior before production reliance

Summary

CRDs and Operators make Kubernetes extensible and automatable for advanced platforms. Use them when lifecycle logic is too complex for static manifests alone.