liveBook · Manning

Promotion control plane

As explained in Kargo in Action

An architectural layer that coordinates artifact advancement between environments independently of build and runtime synchronization.

CI can build and test an artifact, and Argo CD can keep a cluster synchronized with Git, while neither decides which tested artifact should advance to production. That decision is promotion. When scripts, scheduled jobs, and pull requests make it implicitly, teams may struggle to prove what shipped, who approved it, or whether the exact artifact passed pre-production checks. section 1.0 section 1.1

A promotion control plane makes advancement between environments an explicit, governed process. It tracks candidate versions, observes when conditions for advancement are met, carries out permitted transitions, and records each event. It does not replace CI’s build or a GitOps agent’s deployment work: it governs what should enter the desired state that the agent reconciles. section 1.1 section 3.1

A useful test is whether you can answer these questions without reconstructing pipeline runs and commits:

  • Is production running the exact artifact that passed pre-production validation? section 1.1.1
  • Who approved that version, when, and with independent review where required? section 1.1.1
  • Can you trace it from commit to image to each environment, and show that pre-production could not be skipped? section 1.1.1

The distinction from a promotion job matters operationally. A job runs and exits; to enforce a two-hour soak, a workflow must schedule checks. A controller runs continuously, observes versions and environments, and notices when a declared condition becomes true. Centralizing that logic also avoids teams maintaining divergent definitions of “ready.” section 2.5 section 2.6

One image through dev, staging, and production

In Kargo, a Warehouse discovers an image version from a registry and Freight identifies an immutable artifact set by digest. Stages represent positions in the environment graph. A Promotion records an advancement: dev can write the selected version to a GitOps repository, which Argo CD then reconciles into the cluster. After verification in dev, the same Freight can advance to staging and onward to production under the applicable conditions. A Project groups resources for a team or domain. The digest, rather than a mutable tag alone, identifies what moves. section 3.0 section 3.7 section 1.5

Figure 2.5 Devon’s demo-app pilot, drawn like figure 2.1 for comparison. Each numbered label matches the same property there: (1) the system runs continuously rather than on a schedule; (2) one installation serves every team; (3) it records where each version is in the environment graph; (4) verification is recorded against the version it tested; (5) every promotion leaves a record naming the version, the environment, who started it, the outcome, and the pull request.
Devon’s demo-app pilot with Kargo tracking the environment graph and verification and recording each promotion

The pilot diagram contrasts recurring jobs with one continuously running system and shows how version position, verification, and promotion records become visible together. section 2.5

When a first promotion stalls, inspect the affected resource with `kubectl describe` and check the responsible controller. Common causes are registry credentials, Git push permissions, Argo CD sync configuration, and stage ordering. For installation, verify that CRDs are present, controllers are healthy, and RBAC bindings exist. This additional layer is most valuable across multiple environments or teams, or where compliance matters; it is not presented as a fit for non-Kubernetes workloads or genuinely simple delivery. section 3.7 section 1.5

How Kargo in Action covers it

How deep it goes
Explains controller behavior and traces a registry image through Freight and Stages; leaves controller implementation details aside.
Examples
Uses a five-question delivery audit, a two-hour soak, and an image promoted from dev toward production.
What it assumes
Assumes Kubernetes operating familiarity for Kargo, while defining the distinct jobs of CI, promotion, and GitOps deployment.
What you can do after
Operate/configure it with Kargo resources, and diagnose stalled promotions through resource descriptions, controller checks, credentials, sync settings, and stage ordering.
How it connects
Connects artifact digests, environment graphs, verification, GitOps, Kubernetes controllers, and audit trails.

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.