Kubernetes Operators and Custom Resources: Your Complete Guide

Kubernetes is a powerful orchestration platform, but out of the box, it doesn't know how to run your specific application. It knows how to run containers—but it doesn't know how to run a database, a message queue, or a monitoring stack the right way. That's where Operators and Custom Resources come in.

If you've ever found yourself wondering how to make Kubernetes smarter about managing your stateful applications, you're about to uncover its most powerful secret.

What Are Custom Resources (CRs)?

Kubernetes has a core set of built-in resource types: Pods, Services, Deployments, ConfigMaps, and so on. But what if you need something Kubernetes doesn't natively understand? For example, a "PostgreSQLDatabase" or a "KafkaTopic" or a "RedisCluster"?

You can teach Kubernetes about these new types by creating Custom Resource Definitions (CRDs).

A CRD is simply a YAML file that tells the Kubernetes API: "I want to define a new object type called X." Once applied, you can use kubectl create and kubectl get to manage your custom objects, just like built-in resources.

Example: A Simple Custom Resource

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: webapps.example.com
spec:
  group: example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas:
                  type: integer
                image:
                  type: string
  scope: Namespaced
  names:
    plural: webapps
    singular: webapp
    kind: WebApp

After applying this CRD, you can create a WebApp object:

apiVersion: example.com/v1
kind: WebApp
metadata:
  name: my-app
spec:
  replicas: 3
  image: nginx:1.21

But there's a catch: just defining a WebApp doesn't actually deploy anything. Kubernetes doesn't know what to do with it yet. That's where Operators come in.

What Are Operators?

An Operator is software that watches your Custom Resources and takes action to make the current state of your cluster match the desired state defined in those resources. Think of it as a custom controller for your custom resource.

The term was popularized by CoreOS (now part of Red Hat) in 2016. The concept builds on the Kubernetes "controller" pattern—operators just extend it to domain-specific applications.

The Key Insight

An Operator encodes operational knowledge into software. If you have a human operator who knows "how to properly upgrade a PostgreSQL cluster from version 13 to 14, including backup, rollback, and health checks," an Operator captures that logic in code. It automates the manual work your team used to do.

How Operators and CRDs Work Together

1. You define a CRD (like PostgreSQLCluster or RedisFailover).
2. You deploy an Operator—a set of Pods that watches the Kubernetes API for changes to that CRD.
3. When you create a PostgreSQLCluster object, the Operator sees it, reads its spec, and creates the necessary Deployments, Services, PVCs, and ConfigMaps to make it real.
4. If you update the CR (e.g., increase the replica count), the Operator reacts and adjusts the deployment.
5. If a Pod crashes, the Operator goes beyond basic Kubernetes recovery—it might rebuild data replicas, re-run initial setup scripts, or trigger a failover.

You get a self-healing, self-updating application that your DevOps team doesn't need to babysit.

Real-World Examples

Some of the most valuable Operators manage databases, message queues, and CI/CD tools. Here are a few you might already use:

• Prometheus Operator — Manages monitoring stacks (Prometheus, Alertmanager, Grafana) via CRDs. You define a Prometheus resource and it handles the rest.
• Strimzi (Kafka Operator) — Manages Kafka clusters on Kubernetes. Handles upgrades, broker rebalancing, and topic management.
• Cert-Manager — Manages TLS certificates. You define a Certificate resource, and Cert-Manager talks to Let's Encrypt (or another issuer) to get and renew certs automatically.
• Elasticsearch Operator (ECK) — Manages Elasticsearch clusters, Kibana, and APM servers, with automatic upgrades, scaling, and snapshots.

Building Your Own Operator

You don't need to be a Kubernetes core contributor to build an operator. The community provides several frameworks to make it much easier:

• Kubebuilder (most popular) — Go-based. Generates boilerplate code for controllers and CRDs.
• Operator SDK (Ansible-based or Helm-based) — Great for teams that prefer configuration over code. You can build an operator using Ansible playbooks or Helm charts.
• Java Operator SDK — If your team lives in the Java ecosystem.

A Minimal Operator in Concept

At its heart, an operator loop looks like this (pseudo-code):

while True:
    for each CustomResource CR:
        current_state = inspect_cluster(CR)
        desired_state = read_spec(CR)
        if current_state != desired_state:
            apply_changes(CR, desired_state)
    time.sleep(10)

The real code is more complex (handling deletions, events, reconciliation, error states), but that's the essence.

When Should You Use an Operator?

Operators are not for everything. Use them when:

• Your application is stateful (databases, caches, queues).
• Your application requires multi-step lifecycle management (backups, upgrades, scaling with data rebalancing).
• You want to expose domain-specific features (e.g., "create a read replica", "run a backup") as Kubernetes-native API objects.
• You have a repetitive operational task that a human currently performs manually.

Don't use an Operator to wrap a simple stateless web app that can already be managed with a Deployment and Service. That's overkill.

Caveats and Complexity

• Operators have bugs. If an operator has a flaw in its reconciliation logic, it could accidentally delete your production database PVCs. Always test thoroughly.
• Version lock-in. Your Operator's CRD version must be compatible with both the operator's logic and your application's configuration. Upgrading an operator sometimes requires careful migration of CRD schemas.
• Learning curve. Building an operator requires understanding Kubernetes internals (controllers, informers, API server, client-go, RBAC, webhooks). Kubebuilder helps, but you still need to understand the patterns.

The Bottom Line

Custom Resources give you a way to define new types of objects. Operators give you a way to automate them. Together, they let you turn Kubernetes from a generic container scheduler into a platform that understands your application's unique needs.

If you're running databases or message queues on Kubernetes and you're not using an operator, you're probably doing too much manual work. The operator is your robot sidekick—it never sleeps, never forgets a step, and it certainly doesn't complain about on-call rotations.