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.
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


