liveBook · Manning

Kargo Promotion controller

As explained in Kargo in Action

A Kargo Kubernetes controller that executes steps for Promotion resources and records their status.

The Kargo Promotion controller executes the promotion-template steps for a Promotion resource and updates its status as they run. The Promotion persists as a queryable Kubernetes resource, recording the advancement and its results for audit and downstream use. section 3.2.4

Use the resource status and controller logs to locate problems:

  • For a failed promotion, inspect `kubectl describe promotion <name>` to find the failed step, its output, and any errors. section 3.2.4
  • If a promotion starts but fails during execution, investigate the Promotion controller; its logs are a first check when the system misbehaves. section 3.2.5
Listing 3.4 Creating a Promotion with kubectl
kubectl apply -f - <<EOF
apiVersion: kargo.akuity.io/v1alpha1
kind: Promotion
metadata:
  generateName: dev-                                  # #1
  namespace: demo                                     # #2
spec:
  stage: dev                                          # #3
  freight: 7b2f9a8e3c1d5f4a6b8e9c0d2f1a5b7c           # #4
EOF

A minimal Promotion manifest identifies the Stage and Freight to advance. The controller picks up the created resource and runs the Stage's promotion-template steps. section 3.2.4

Listing 3.5 The same Promotion after it has run to completion
apiVersion: kargo.akuity.io/v1alpha1
kind: Promotion
metadata:
  name: dev-x7g2k                                     # #1
  namespace: demo
spec:
  stage: dev
  freight: 7b2f9a8e3c1d5f4a6b8e9c0d2f1a5b7c
status:
  phase: Succeeded                                    # #2
  startTime: "2026-05-25T14:22:01Z"                   # #3
  finishTime: "2026-05-25T14:22:28Z"
  freightCollection:                                  # #4
    freight:
      demo-app:
        name: 7b2f9a8e3c1d5f4a6b8e9c0d2f1a5b7c

After execution, the resource status shows the phase, timestamps, and Freight collection, providing a record of what was promoted and when. section 3.2.4

How Kargo in Action covers it

How deep it goes
Traces resource execution, status fields, audit data, and failure checks without detailing step internals.
Examples
Uses a kubectl-created Promotion and its completed status, including phase, timestamps, and Freight collection.
What it assumes
Assumes familiarity with Promotion resources, Stages, Freight, and promotion-template steps.
What you can do after
Diagnose failed promotions by inspecting resource status and checking the responsible controller's logs.
How it connects
Connects Promotion resources and promotion templates with Stages, Freight, Kubernetes, and Argo CD.

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.