Module 01

Introduction to Kargo

Progressive Delivery for GitOps Pipelines

You've mastered ArgoCD. Now let's master promotion.

"You deployed to dev. Everything looks great. Tests pass. The team is happy.

Now what?

How do you get that exact same change to staging? And then to production? Safely, reliably, and with a clear audit trail?"

The Promotion Problem

📝

Manual PRs

Someone opens a PR to change a tag in staging, then another for prod. Error-prone, slow.

⚙

Custom Scripts

CI pipelines cobble together sed/yq commands. Fragile, hard to audit.

😱

YOLO Deploys

"Just merge to main and let ArgoCD sync." No gates, no verification, no rollback plan.

What Teams Actually Want

Confidence — "This exact version was verified in staging"
Automation — "Promotion happens without manual toil"
Visibility — "I can see where every version lives right now"
Control — "Production requires approval, but dev is automatic"
Rollback — "If something breaks, I can go back in one click"

Enter Kargo

A Kubernetes-native promotion engine
built for GitOps workflows.

Open Source Akuity Kubernetes Native

What is Kargo?

Kargo is a progressive delivery tool that manages the lifecycle of changes as they move through a series of stages (environments).

It watches for new versions, packages them as Freight, and promotes them through your pipeline — automatically or with approval gates.

Think: "GitOps promotion pipeline as a Kubernetes resource"

What Kargo is NOT

Not a CD tool

ArgoCD (or Flux) still does the actual sync. Kargo orchestrates what gets promoted where.

Not a CI system

Kargo does not build images or run tests. It consumes artifacts that CI already produced.

Not a replacement

It complements your existing GitOps stack. It fills the gap ArgoCD intentionally leaves open.

Quiz 1 — Check Your Understanding

1. What is the primary purpose of Kargo?

a) Build container images from source code b) Manage the promotion of changes across environments in GitOps pipelines c) Replace ArgoCD as the deployment tool

2. What does Kargo do when it detects a new container image version?

a) Immediately deploys it to production b) Packages it as Freight and promotes it through defined stages c) Rebuilds the image with new tags

3. Which tool actually syncs Kubernetes resources to the cluster?

a) Kargo b) ArgoCD (or Flux) c) Helm

Core Concepts — The Cast of Characters

Project → Warehouse → Freight → Stage → Promotion

Each is a Kubernetes Custom Resource. Let's meet them one by one.

1 Project

The Boundary

A Project is a namespace-scoped grouping of all Kargo resources for a particular application or team.

Creates a dedicated Kubernetes namespace
Isolates Warehouses, Stages, and Freight
Controls who can promote and approve

apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: my-app

2 Warehouse

The Watchtower

A Warehouse watches for new versions of your artifacts — container images, Git commits, or Helm charts.

Subscribes to one or more artifact sources
Detects new versions automatically
Assembles discovered versions into Freight

Think: "The warehouse receives new shipments and packages them for delivery."

3 Freight

The Package

Freight is an immutable collection of artifact references that travel together through your pipeline.

Contains specific image tags, Git commits, chart versions
Has a unique ID and is immutable once created
Tracks which stages it has been verified in

Think: "A sealed box of changes. Same box goes dev → staging → prod."

4 Stage

The Checkpoint

A Stage represents an environment or checkpoint in your delivery pipeline.

Defines where Freight comes from (Warehouse or upstream Stage)
Contains a Promotion Template — the recipe for deploying
Can run Verification after promotion
Examples: dev, staging, production

5 Promotion

The Action

A Promotion is a request to move specific Freight to a specific Stage.

Can be created manually (click/CLI) or automatically
Executes the Stage's Promotion Template steps
Tracks status: Pending, Running, Succeeded, Failed
Provides a full audit trail

How It All Fits Together

Warehouse watches registries / repos
↓ discovers new version
Creates Freight (e.g. image:v1.2.3 + commit:abc123)
↓ auto-promotion enabled
Stage: dev → Promotion runs → Git updated → ArgoCD syncs
↓ verification passes
Stage: staging → manual approval → Promotion runs
↓ verification passes
Stage: prod → approved → Promotion runs → Live!

Quiz 2 — Core Concepts

1. What does a Warehouse do in Kargo?

a) Stores application logs and metrics b) Watches for new artifact versions and assembles Freight c) Manages Kubernetes node pools

2. What is Freight?

a) A running container in the cluster b) An immutable collection of artifact references that moves through stages c) A Helm chart dependency

3. What is a Kargo Project?

a) A namespace-scoped grouping that isolates Kargo resources for an application b) A GitHub repository c) A Docker Compose file

Kargo + ArgoCD

ArgoCD

Syncs desired state from Git to cluster. Detects drift. Handles rollout. Deploys.

Kargo

Updates Git with new versions. Orchestrates which version goes where. Promotes.

Kargo updates Git repo → ArgoCD detects change → ArgoCD syncs cluster

The Complete GitOps Loop

CI builds image v1.2.3
↓
Warehouse detects new image
↓
Freight created with image:v1.2.3
↓
Promotion updates values.yaml in Git (image.tag: v1.2.3)
↓
ArgoCD sees Git change, syncs to cluster
↓
Verification confirms health

Kargo Architecture

API Server

Serves the Kargo API and UI. Handles RBAC and authentication.

Controller

Reconciles Kargo resources. Watches Warehouses, manages Freight, executes Promotions.

CRDs

Project, Warehouse, Freight, Stage, Promotion — all stored in the Kubernetes API.

Webhooks

Validates and mutates Kargo resources on creation/update.

Installing Kargo on AKS

Kargo is installed via Helm into your Kubernetes cluster.

# Add the Kargo Helm repo
helm repo add kargo https://charts.kargo.io
helm repo update

# Install Kargo
helm install kargo kargo/kargo \
  --namespace kargo \
  --create-namespace \
  --set api.adminAccount.enabled=true \
  --set api.adminAccount.password=admin \
  --set api.adminAccount.tokenSigningKey=shared-signing-key

Verify the Installation

# Check pods are running
kubectl get pods -n kargo

# Expected output:
# kargo-api-...         Running
# kargo-controller-...  Running
# kargo-webhooks-...    Running

# Check CRDs installed
kubectl get crds | grep kargo
# freights.kargo.akuity.io
# projects.kargo.akuity.io
# promotions.kargo.akuity.io
# stages.kargo.akuity.io
# warehouses.kargo.akuity.io

The Kargo UI

Visual Pipeline View

Project Dashboard — see all stages and their current Freight
Freight Timeline — every version ever discovered
Promotion History — full audit trail with status
One-click Promote — drag Freight to a Stage to promote
Verification Status — green/red indicators per Stage

# Access the UI via port-forward
kubectl port-forward svc/kargo-api -n kargo 8443:443

The Kargo CLI

# Install the CLI
brew install akuity/tap/kargo   # macOS

# Login
kargo login https://localhost:8443 \
  --admin --password admin --insecure-skip-tls-verify

# Common commands
kargo get projects
kargo get stages --project my-app
kargo get freight --project my-app
kargo promote --project my-app \
  --stage staging \
  --freight abc123def

Quiz 3 — Architecture & Tooling

1. How is Kargo typically installed on a Kubernetes cluster?

a) Via a Helm chart b) As a Docker Compose stack c) Through the Azure Marketplace only

2. In the Kargo + ArgoCD workflow, who updates the Git repository with new image tags?

a) ArgoCD b) Kargo (via Promotion steps) c) The developer manually

3. Which Kargo component reconciles resources and executes Promotions?

a) The API Server b) The Controller c) The Webhooks

Your First Kargo Project

Let's create a simple project that promotes a web app through dev → staging → prod.

apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: my-web-app
spec:
  promotionPolicies:
  - stage: dev
    autoPromotionEnabled: true
  - stage: staging
    autoPromotionEnabled: false
  - stage: prod
    autoPromotionEnabled: false

Apply and Verify

# Apply the project
kubectl apply -f project.yaml

# Verify - a namespace is created
kubectl get ns my-web-app

# Check the project
kargo get projects
# NAME          AGE
# my-web-app    5s

# The namespace is where all your
# Warehouses, Stages, and Freight will live

Next module: We'll create a Warehouse and see Freight appear automatically!

Key Takeaways

Kargo is a Kubernetes-native promotion engine for GitOps
It complements ArgoCD — Kargo promotes, ArgoCD deploys
Core resources: Project, Warehouse, Freight, Stage, Promotion
Freight is an immutable package of artifact versions
Stages are checkpoints with promotion templates and verification
Everything is a Kubernetes CRD — declarative and auditable

Up Next

Module 02: Warehouses & Freight

The watchtower that spots new versions and the packages that carry them.

Subscriptions Image Selection Freight Discovery