What is the difference between an API server and a controller in a declarative control plane?

An API server stores and exposes the resource model, while controllers implement the business logic that acts on that model. The API server receives desired state through the spec and reports current state through status. Controllers watch resources, reconcile drift, and update status when work is completed. This separation keeps the API extensible and makes custom automation easier to build.

Why This Matters for Security Teams

declarative control plane work because they separate two jobs that are easy to confuse: one component defines the contract for state, and another component makes the system move toward that state. The API server is the source of truth for accepted objects, validation, and read/write access to the resource model. Controllers are the workers that turn those objects into real-world changes, which is why reliability, observability, and change control depend on understanding the split.

This distinction matters most when teams extend the platform. If every action were embedded in the API layer, the control plane would become rigid and hard to evolve. If every decision lived only in controllers, the system would lose a clean, auditable model of desired state. Practitioners usually feel the difference only when reconciliation stalls, status becomes stale, or an automation loop starts acting on partial information instead of the declared spec.

How It Works in Practice

The API server is the front door for the declarative model. It accepts object definitions, enforces schema and admission rules, persists the current declaration, and serves reads back to clients and other components. Its role is not to decide how the platform should satisfy the declaration, but to ensure the declaration is valid, durable, and consistently visible.

Controllers work differently. They watch one or more resource types, compare desired state with observed state, and then take action until the gap closes. That action can mean creating, updating, deleting, or coordinating downstream resources, and then reporting status once progress is made. In practice, controllers are event-driven reconcilers, not request handlers.

The API server owns object acceptance, validation, persistence, and read consistency.
Controllers own reconciliation logic, dependency ordering, and status updates.
The spec describes intent; the status reflects progress and outcome.
Custom automation is easier when the API stays stable and controllers can evolve independently.

This split also makes failure handling more practical. If a controller crashes or lags, the desired state is still preserved in the API server, and another controller instance can continue reconciliation. These controls tend to break down when status is treated as authoritative intent, because then operators lose the ability to distinguish declaration from execution.

Common Variations and Edge Cases

Tighter separation of concerns often improves extensibility, but it also adds coordination overhead, especially in systems with many controllers acting on shared resources. Teams sometimes assume that any component that changes state must be “the controller,” when in fact some logic belongs in admission, some in reconciliation, and some in status reporting.

One common edge case is eventual consistency. The API server may show a valid desired state while controllers are still catching up, so the platform is correct but not yet converged. Another is conflicting controllers, where multiple reconcilers touch related resources and need clear ownership boundaries to avoid thrashing. In mature platforms, the question is less “who can write?” and more “who is responsible for convergence?”

The cleanest design is to keep the API expressive enough to represent intent without embedding business logic in the resource schema itself, while keeping controllers narrow enough that their behavior is predictable. When that boundary blurs, debugging becomes harder because the object model no longer clearly explains why the system behaved the way it did.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

NIST CSF 2.0 and CIS Controls v8 set the governance and control requirements practitioners need to meet.

Framework	Control / Reference	Relevance
NIST CSF 2.0	GV.OV-01 — Cybersecurity Governance Oversight	API/controller separation supports clear governance over platform behavior and ownership
Recommendation — Define ownership for intent, reconciliation, and status across the control plane.
CIS Controls v8	16 — Application Software Security	Controllers are application logic that must be designed and tested separately from the API surface
Recommendation — Implement and test controller logic independently from the API contract.

Practitioner Guidance

What to verify: Confirm that the API server validates and stores intent without relying on controller behavior to make the object usable. If status fields are being treated like input, or if controllers depend on undocumented side effects in the API layer, the design is already drifting away from declarative control.

Common mistake: Putting business rules into the API layer just because they feel “closer” to the data. That approach reduces portability and makes custom automation harder to reason about, because the resource model stops being a clean contract and starts acting like hidden logic.

What good looks like: A practitioner should be able to read the spec and understand what is desired, then inspect status and events to see what the controllers have actually achieved. The platform should remain understandable even when a controller is replaced, scaled out, or temporarily unavailable.

Practitioner takeaway: The architectural value of a declarative control plane is not that it removes logic, but that it places logic where it can reconcile state without corrupting the API contract.