liveBook · Manning

Kubernetes controller

As explained in Kargo in Action

A control loop that observes Kubernetes resources and acts to move their actual state toward the declared desired state.

A Kubernetes controller is a long-running process that watches resources, compares observed state with declared state, and acts when they differ. Unlike a job that runs and exits, it keeps evaluating conditions without a separately scheduled check. section 2.5 section 3.1

Figure 2.4 Two ways to build the same layer. A job (left) is triggered, runs to completion, and exits; between runs nothing is evaluating anything, which is why enforcing a soak requires a job that wakes on a schedule to check. A controller (right) observes continuously, so a condition that becomes true at 2 a.m. is noticed at 2 a.m. without anything having to be woken up first.
A triggered job versus a continuously running controller

Compare what happens between job runs with what a continuously observing controller can detect. section 2.5

Enforcing a pre-production soak

A scheduled-job workflow might wake every five minutes to check whether a version has spent two hours in pre-production. With a promotion controller, the two-hour soak is a property of the environment. Once the condition is met, the version becomes eligible without a separately scheduled checking job. section 2.5

Kargo applies this pattern to promotion between CI and GitOps. Its Kubernetes resources are exposed through Custom Resource Definitions and managed with YAML and kubectl. Controllers watch and reconcile those resources; Kargo governs artifact progression, while Argo CD reconciles GitOps repository state into clusters. section 3.1 section 3.7

When a promotion does not progress, check the responsible resource before changing the workflow:

  • Use kubectl describe on the affected resource; the Warehouse, Stage, or Promotion controller is the first place to look for that resource type. section 3.7
  • Check registry credentials, Git push permissions, Argo CD sync configuration, and stage ordering as likely causes of a first-attempt failure. section 3.7
  • For an installation problem, verify that CRDs are present, controllers are healthy, and RBAC bindings exist. section 3.7

How Kargo in Action covers it

How deep it goes
Defines the watch-and-reconcile loop and works through a soak condition, but does not detail controller implementation.
Examples
Contrasts a scheduled soak-checking job with a controller and traces Warehouse, Stage, and Promotion controllers through a first promotion.
What it assumes
Assumes familiarity with operating Kubernetes while defining the controller pattern through its behavior and a job comparison.
What you can do after
Diagnose/debug with it by describing the affected resource, checking its controller, and verifying controller health during installation.
How it connects
Connects controllers to Custom Resource Definitions, GitOps, CI, Argo CD, and promotion resources.

Also explained in

Compare how 3 books explain Kubernetes controller →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Kargo in Action. The section links point to the parts of the book it draws on.