Kubernetes Custom Resources and When to Use a Controller

A Kubernetes custom resource adds an API object type to a cluster through a CustomResourceDefinition (CRD); creating the CRD makes that type available, but does not by itself run a controller. Use a controller when you need software to watch those objects and continually make real cluster state match the desired state they describe.

What a custom resource and CRD do

Kubernetes includes built-in resource types such as Pods, Services, and Deployments. A custom resource is an instance of an additional type that an administrator or application developer defines for a particular cluster. For example, a team might define a Website resource with fields for a hostname and the name of a container image.

The CRD tells the Kubernetes API server about that type. It specifies details such as the resource’s name, scope, and schema. Once the CRD is established, clients can use the Kubernetes API to create, read, update, and delete objects of that type, just as they do with built-in resources. A CRD is a definition; a custom resource is an object created from that definition.

Neither one automatically implements application-specific behavior. A CRD can validate and store structured data, but it does not create a Deployment, contact an external service, or respond to changes by itself.

How the API and a controller work together

A controller is a program that observes resources and repeatedly reconciles actual state toward a desired state. In Kubernetes, it commonly watches objects through the API, compares what exists with what the objects request, and takes actions such as creating or updating other resources. It runs continuously rather than performing a one-time action when an object is submitted.

For a Website resource, a controller might read the requested image and hostname, then create or update a Deployment and a Service. If someone changes the image in the custom resource, the controller notices the change and updates the Deployment. If a managed object is deleted unexpectedly, the controller may recreate it, depending on its design.

The typical flow is:

Install a CRD so the API server recognizes a new kind.
Create a custom resource expressing desired configuration.
Run a controller that watches the resource and reconciles that configuration.
Inspect status or events to understand whether the requested state was achieved.

A controller may update a resource’s status subresource to report progress, conditions, or observed details. The spec usually holds desired configuration; status is reported state. This separation helps clients distinguish what was requested from what has happened.

When a CRD alone is enough

A CRD without a dedicated controller is useful when the custom object is primarily a structured record stored in the Kubernetes API. For example, a platform team could define a resource that records a policy or a team’s configuration for other software to read. A client can also create and inspect custom resources without an always-running controller if a person or separate process handles the next steps.

Before choosing this approach, consider whether the API server’s schema validation and any configured admission rules are enough. A CRD schema can describe field types, required fields, defaults, and constraints. Admission webhooks can add validation or mutation when appropriate, but they are not substitutes for a reconciliation loop that continually manages resources.

Keeping a CRD-only design simple can be a benefit: there is no controller deployment to operate, secure, monitor, or upgrade. The trade-off is that the objects do not cause ongoing action on their own, and users may mistake stored intent for completed work.

When you need a controller

Build or install a controller when a custom resource represents a desired outcome that Kubernetes or another system must maintain. Common reasons include creating related resources, responding to updates, repairing drift, tracking asynchronous work, or coordinating with an external API.

Manage dependent resources: A Database object could cause a controller to create a Service and persistent storage resources.
Keep configuration applied: A controller can update managed resources when the custom resource changes and restore them if they drift.
Report progress: A controller can record whether provisioning is pending, complete, or failing.
Coordinate outside the cluster: A controller may call an external system when a resource is created or changed, provided it has suitable credentials and handles failures.

Controllers are also useful for cleanup. A deletion request may require removing dependent resources or releasing an external allocation. Kubernetes finalizers can delay deletion while a controller performs cleanup; poorly designed cleanup can leave an object stuck, so the controller must handle retries and failures carefully.

How to decide and what it costs to operate

Start with the behavior, not the fact that a custom object is possible. Ask whether anyone needs the cluster to take action after a resource is created, or to keep taking action as the system changes. If the object is only data for a human or another system, a CRD alone may suffice. If it should cause or maintain an outcome, a controller is generally the appropriate mechanism.

A useful design checklist is:

What desired state does the resource express, and which fields are part of its stable API?
Which resources or external systems should be created, updated, or cleaned up?
How should the controller behave when an operation fails or is retried?
How will users see readiness, errors, and the difference between requested and observed state?
Who will deploy, upgrade, monitor, and grant permissions to the controller?

A controller adds operational work: it must be deployed, configured with appropriate permissions, observed for failures, and kept compatible with the CRD’s schema and versions. Reconciliation should be safe to repeat because controllers can receive the same event more than once and may restart mid-operation. Design the controller to converge on the desired result rather than relying on a single event being delivered exactly once.

Common misconceptions and pitfalls

“Creating a CRD creates the application” is a common misunderstanding. The CRD makes a kind available; the custom resource stores an instance; a controller supplies ongoing behavior. Installing a CRD without its intended controller can leave valid-looking objects that no software acts on.

Another pitfall is treating a successful API response as proof that work is complete. It confirms that the API server accepted the object, not that a Deployment became ready or an external service was provisioned. Use status, events, and the state of managed resources to check progress.

Schema changes also need care. CRDs support versioning and conversion strategies, but changing field meaning or removing fields can affect existing objects and clients. Plan how stored data will be served across versions, and test upgrades. Finally, keep controller permissions limited to the resources and operations it needs; a controller’s service account should not receive broad privileges merely for convenience.

Frequently Asked Questions

Does a Kubernetes CRD need a controller?
No. A CRD can define and store custom objects without a dedicated controller. You need a controller when the objects should trigger ongoing reconciliation or other automated behavior.

What is the difference between a CRD and a custom resource?
A CRD defines a resource type in the Kubernetes API. A custom resource is one object, or instance, of that type.

Can a CRD create Pods by itself?
No. The CRD makes the custom type available and validates its data. A controller or another process must create Pods or other resources in response.

Can I use a custom resource without writing an operator?
Yes. You can use it as structured API data, or have another client or process consume it. An operator is one common way to package a controller and related application-management logic.

Is every controller an operator?
No. A controller is a component that reconciles resources. “Operator” commonly describes a broader application-management approach that uses Kubernetes APIs and controllers, often with domain-specific operational knowledge.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →