Kubernetes Operator vs Controller vs CRD: What's the Difference?

"Operator", "Controller", and "CRD" are three of the most-confused terms in the entire Kubernetes ecosystem. Tutorials use them interchangeably, job interviews ask trick questions about them, and even seasoned engineers get the distinctions wrong. The truth is simple: they are three different things that often appear together, and once you see the pattern you can never un-see it.

If you have not yet read What is a Kubernetes Operator?, start there — this article assumes you already know what an Operator does and now wants to pin down where the lines are drawn.

A quick kitchen analogy

Before we touch any YAML, picture a restaurant kitchen:

• A menu lists what dishes can be ordered. It is just paper — it does not cook anything.
• A chef reads orders and cooks them. Without a menu, the chef has nothing to make. Without a chef, the menu is just decoration.
• An Italian specialist chef is a chef who only handles Italian dishes and knows the exact subtleties (al dente pasta timing, how to balance an arrabbiata sauce, when fresh basil goes in versus dried).

Map that to Kubernetes:

That's the whole framing. The rest of this article makes it precise.

The 60-second answer

Here are the three terms in one sentence each:

• A CRD (Custom Resource Definition) is a YAML schema that teaches the Kubernetes API server about a new object type. It is data, not code.
• A Controller is a program that runs a control loop — watch, compare, act — to drive the actual state of one or more resources toward their desired state. The official definition lives in the Kubernetes docs.
• An Operator is a controller that uses one or more CRDs to manage a specific application (Postgres, Kafka, cert-manager), and that encodes the operational know-how of running that application as code.

The relationship in one line:

Controller + CRD + Application-domain knowledge = Operator.

Or, in the most-quoted Stack Overflow phrasing:

"All Operators use the controller pattern, but not all controllers are Operators. It's only an Operator if it has: controller pattern + API extension + single-application focus."

CRD — the API contract (data, no behaviour)

A Custom Resource Definition adds a new resource type to the Kubernetes API. Once installed, the API server accepts, validates, and stores instances of that type just like a built-in Deployment or Service.

A trimmed CRD looks like this:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: postgresclusters.acme.io
spec:
  group: acme.io
  scope: Namespaced
  names:
    kind: PostgresCluster
    plural: postgresclusters
    singular: postgrescluster
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas: { type: integer }
                version:  { type: string }

After kubectl apply -f you can run kubectl get postgresclusters and the API responds — the type exists. But nothing in the cluster reacts to a new PostgresCluster. No Pods are created, no Service is exposed, no backup is scheduled. A CRD on its own is just a typed slot in etcd.

Try it yourself: apply the CRD above on a Minikube cluster, create a PostgresCluster resource, then list it. The object will be there, happy as a clam, doing nothing. That is exactly what a CRD-only design feels like.

That fact alone unlocks a real architectural choice: many teams ship CRDs purely as a typed configuration interface consumed by GitOps tools like Argo CD, Flux, or Crossplane. That is a CRD-only design — perfectly legitimate, but not an Operator.

A deeper walk-through of writing CRDs (printer columns, structural schemas, conversion webhooks) lives in Custom Resource Definitions explained.

Controller — the active reconciler

A Kubernetes Controller is the active part. It runs as a Pod inside the cluster (or, briefly, on a developer laptop during development) and executes a never-ending control loop:

1. Watch the API server for changes to specific resource types.
2. Compare the desired state (.spec) against the actual state.
3. Act to close the gap by creating, updating, or deleting other resources.
4. Update status (.status) so users and other controllers can observe.
5. Repeat — the loop never exits.

If that loop sounds familiar, that's because every moving piece in Kubernetes is a controller. The cluster you are running right now contains dozens, all bundled into the kube-controller-manager process:

None of these is an Operator — they reconcile generic primitives, not a particular application. They are controllers, full stop. When you create a Deployment that asks for 3 replicas, the Deployment controller doesn't know or care whether you are running NGINX, a microservice, or a hello-world Pod — it just makes sure 3 Pods exist.

A custom controller is any controller you write, deployed outside kube-controller-manager. It might:

• Watch built-in resources (a controller that auto-injects a logging sidecar into every new Pod — similar in spirit to the sidecar pattern).
• Watch custom resources (in which case it is also an Operator).
• Watch a mix (a policy controller that ensures every Namespace has a ResourceQuota — see resource quotas).

Operator — controller + CRD + domain knowledge

An Operator is the specific case where all three ingredients show up:

1. You define a CRD that represents an entire application (PostgresCluster, KafkaTopic, Certificate).
2. You ship a custom controller that watches that CRD.
3. The controller code contains operational expertise — what the on-call DBA used to do at 3 a.m.: failover, replica re-attach, backup schedule, schema upgrade, version-skew handling.

That third ingredient is the one most "what is an operator?" articles gloss over, and it is the most important one. Two operators can have the same CRD shape and the same reconcile-loop skeleton, but the operator that knows the application is the one that wins.

Real-world Operators you have probably already used:

• Prometheus Operator — ServiceMonitor, PodMonitor, PrometheusRule CRDs. Knows how Prometheus expects to be configured and reloaded.
• cert-manager — Issuer, Certificate, Order CRDs. Knows the ACME protocol, DNS-01 vs HTTP-01 challenges, and when to renew a cert (30 days before expiry, not on expiry day).
• CloudNativePG — Cluster CRD. Knows Postgres streaming replication, base-backup timing, point-in-time recovery, and which replicas are safe to promote.
• Strimzi — Kafka, KafkaTopic, KafkaUser CRDs. Knows the Kafka broker config surface, ZooKeeper-to-KRaft migration, and rolling-update ordering.

The first Operator was the etcd-operator from CoreOS in 2016, which is also how the pattern got its name (see What is a Kubernetes Operator? for the full history).

All three pieces, in one Go skeleton

If you don't write Go yet, skim this section — the shape of the code is what matters. We will come back to Go in detail in the scaffold your first operator project guide, and you can also write operators in Python (KOPF) or Helm if Go is not your language.

Here is the smallest possible end-to-end picture using controller-runtime — the same library Operator SDK and Kubebuilder generate against.

1. The CRD type (Go struct → CRD YAML via controller-gen):

// api/v1/postgrescluster_types.go
type PostgresClusterSpec struct {
    Replicas int32  `json:"replicas"`
    Version  string `json:"version"`
}

type PostgresClusterStatus struct {
    ReadyReplicas int32  `json:"readyReplicas"`
    Phase         string `json:"phase"` // Pending / Ready / Degraded
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
type PostgresCluster struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec              PostgresClusterSpec   `json:"spec,omitempty"`
    Status            PostgresClusterStatus `json:"status,omitempty"`
}

2. The Controller (the reconcile loop):

// controllers/postgrescluster_controller.go
type PostgresClusterReconciler struct {
    client.Client
    Scheme *runtime.Scheme
}

func (r *PostgresClusterReconciler) Reconcile(
    ctx context.Context, req ctrl.Request,
) (ctrl.Result, error) {

    var cluster acmev1.PostgresCluster
    if err := r.Get(ctx, req.NamespacedName, &cluster); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // ----- DOMAIN KNOWLEDGE LIVES HERE -----
    // Build the desired StatefulSet from .spec.
    // Compare to the existing one. CreateOrUpdate.
    // Check primary health; promote a replica if needed.
    // Schedule a base backup if the schedule says so.
    // Update .status with observed state.
    // -----------------------------------------

    return ctrl.Result{RequeueAfter: 30 * time.Second}, nil
}

func (r *PostgresClusterReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&acmev1.PostgresCluster{}).      // owns the CR
        Owns(&appsv1.StatefulSet{}).         // owns its children
        Complete(r)
}

3. Wire it together (main.go):

mgr, _ := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{Scheme: scheme})
(&PostgresClusterReconciler{
    Client: mgr.GetClient(), Scheme: mgr.GetScheme(),
}).SetupWithManager(mgr)
mgr.Start(ctrl.SetupSignalHandler())

That entire bundle — the PostgresCluster CRD + the PostgresClusterReconciler controller + the application-specific logic inside Reconcile() — is the Operator. Pull out any one piece and the name no longer fits:

• Remove the CRD → you have a controller (likely one that mutates built-in resources).
• Remove the controller → you have a CRD (a typed config surface).
• Remove the Postgres-specific backup/failover/replica logic → you have a generic custom controller, not a Postgres Operator.

Common confusions, cleared up

Five mistakes that come up in interviews and PR reviews:

1. "A StatefulSet is an Operator for stateful workloads." No — a StatefulSet is a built-in primitive (ordered Pods, stable identities, ordered rollout). It does not understand application-level concepts like primary, replica, or backup. Most database Operators use a StatefulSet internally and add the application logic on top.

2. "kubectl plugins are controllers." No — kubectl plugins run on your laptop, client-side. Controllers run continuously inside the cluster, watching the API server.

3. "Admission webhooks are controllers." No — admission webhooks intercept API requests at write time, before the object is even stored. They do not run a continuous reconcile loop. Operators can expose webhooks (see mutating & validating webhooks for operators, covered later in this course), but a webhook on its own is not a controller.

4. "A Helm chart is an Operator." No — Helm renders YAML and pushes it once. An Operator runs forever and corrects drift. The two are complementary; operator-sdk init --plugins=helm even wraps a chart as an Operator (see Helm-based operator tutorial).

5. "CRD without a controller is broken." No — it is a valid design. Many teams ship CRDs purely as a typed configuration surface consumed by Argo CD, Flux, Crossplane, or kubectl. A CRD without a controller is just data, and that can be exactly what you want.

Which one do you actually need?

The decision tree is short: if you have application-specific day-2 operations to encode, you are writing an Operator. If you have cluster-wide policy to apply to existing resources, you are writing a custom controller. If you just need a typed slot in the API, you are writing a CRD.

The 80/20 rule: before writing any of the above, check OperatorHub.io — for 80 % of common workloads (Postgres, Kafka, Redis, Prometheus, Vault, Elastic) someone has already shipped a production-grade Operator and you can install it in one command.

What's next?

You now have the clean mental model. The natural follow-ups:

• Go deeper on the loop itself — the reconcile loop explained with timing diagrams and edge cases.
• Understand level-triggered design — desired state vs actual state explains why operators are not event-driven the way most people assume.
• Master the API contract — Custom Resource Definitions (CRDs) explained covers structural schemas, printer columns, and conversion webhooks.
• Build your first Operator — Install Operator-SDK on Linux and you will be running the code skeleton above against a real cluster in under an hour.
• Going back to basics? Start at What is a Kubernetes Operator? — the 60-second definition and the history of the pattern.