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
