Module 02

Warehouses & Freight

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

"Your CI pipeline just built image v1.5.0. It's sitting in your container registry. But nobody told your GitOps pipeline about it.

How does Kargo know there's something new to promote?

That's the job of the Warehouse."

What is a Warehouse?

The Watchtower

A Warehouse is a Kargo resource that continuously monitors artifact sources for new versions. When it finds something new, it creates Freight.

Polls on a configurable interval (default: 5 minutes)
Can subscribe to multiple sources simultaneously
Lives in the Project namespace

Three Types of Subscriptions

📦

Container Images

Watch a registry for new image tags. Supports Docker Hub, ACR, ECR, GCR, and any OCI registry.

📁

Git Repositories

Watch a Git repo for new commits on a branch. Great for config changes or manifests.

☵

Helm Charts

Watch a Helm chart repository for new chart versions. Supports OCI and HTTP repos.

Subscribing to Container Images

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-warehouse
  namespace: my-web-app
spec:
  subscriptions:
  - image:
      repoURL: myacr.azurecr.io/my-web-app
      imageSelectionStrategy: SemVer
      semverConstraint: ">=1.0.0"

This watches your ACR registry for new tags matching SemVer format.

Image Selection Strategies

SemVer

Selects the highest version matching a semantic versioning constraint. Best for versioned releases.

semverConstraint: ">=1.0.0 <2.0.0"

NewestBuild

Selects the most recently pushed image. Useful for dev/staging with build-number tags.

allowTags: "^main-.*"

Digest

Tracks a specific tag (e.g. latest) by digest. Detects when the tag is re-pushed.

imageSelectionStrategy: Digest

SemVer Strategy — Deep Dive

subscriptions:
- image:
    repoURL: myacr.azurecr.io/my-web-app
    imageSelectionStrategy: SemVer
    # Only pick 1.x versions
    semverConstraint: "^1.0.0"
    # Ignore pre-release tags
    ignoreTags:
    - ".*-rc.*"
    - ".*-beta.*"

SemVer constraints use the same syntax as npm/Cargo:
^1.0.0 = >=1.0.0, <2.0.0 | ~1.2.0 = >=1.2.0, <1.3.0

NewestBuild Strategy

subscriptions:
- image:
    repoURL: myacr.azurecr.io/my-web-app
    imageSelectionStrategy: NewestBuild
    # Only consider tags matching this regex
    allowTags: "^main-[0-9a-f]{7}$"
    # Optionally, platform filter
    platform: linux/amd64

When to use: Your CI tags images like main-abc1234 (branch + short SHA). No semantic version, but you always want the newest build.

Quiz 1 — Warehouse Basics

1. What does a Warehouse do when it discovers a new artifact version?

a) Deploys it directly to the cluster b) Creates a new Freight resource c) Sends a Slack notification

2. Which image selection strategy should you use for tags like "v1.2.3"?

a) NewestBuild b) SemVer c) Digest

3. How many artifact sources can a single Warehouse subscribe to?

a) Exactly one b) Multiple sources simultaneously c) One per type (one image, one git, one helm)

Subscribing to Git Repositories

subscriptions:
- git:
    repoURL: https://github.com/my-org/my-app-config.git
    # Watch a specific branch
    branch: main
    # Optional: only care about changes in a path
    includePaths:
    - "charts/my-app/**"
    excludePaths:
    - "charts/my-app/README.md"

Kargo tracks the latest commit on the specified branch. Path filters let you ignore irrelevant changes.

Why Subscribe to Git?

Use Cases for Git Subscriptions

Config-as-code changes — someone updated a ConfigMap or resource limit
Multi-repo setups — app code repo + config/manifests repo
Kustomize overlays — track changes to base manifests
Combined with image — Freight contains both the new image AND the latest config commit

Subscribing to Helm Chart Repos

subscriptions:
- chart:
    # Classic Helm repo
    repoURL: https://charts.example.com
    name: my-app
    semverConstraint: "^2.0.0"

# OR for OCI-based Helm repos:
- chart:
    repoURL: oci://myacr.azurecr.io/helm
    name: my-app
    semverConstraint: ">=1.0.0"

Perfect when your team publishes the Helm chart as a versioned artifact.

Multi-Source Warehouse

A single Warehouse can watch multiple sources at once.

spec:
  subscriptions:
  - image:
      repoURL: myacr.azurecr.io/frontend
      imageSelectionStrategy: SemVer
  - image:
      repoURL: myacr.azurecr.io/backend
      imageSelectionStrategy: SemVer
  - git:
      repoURL: https://github.com/my-org/k8s-config.git
      branch: main

When any source has a new version, Kargo creates Freight containing the latest version of all subscribed sources.

Warehouse Polling

How often does the Warehouse check?

Default polling interval: 5 minutes
Configurable via the freightCreationPolicy field
The Warehouse controller reconciles periodically

spec:
  freightCreationPolicy: Automatic   # default
  # Kargo automatically creates Freight
  # when new versions are discovered

Now: Freight

"The Warehouse spotted a new image tag. Now it needs to package that discovery into something that can travel through your pipeline. That package is Freight."

What is Freight?

The Immutable Package

Freight is a Kubernetes resource representing a specific, immutable combination of artifact versions discovered by a Warehouse.

Contains references to exact image digests, Git commits, chart versions
Has a unique ID (short hash)
Tracks which Stages it has been verified in
Tracks which Stages it has been approved for

Anatomy of a Freight Resource

apiVersion: kargo.akuity.io/v1alpha1
kind: Freight
metadata:
  name: abc123def456  # auto-generated unique ID
  namespace: my-web-app
  labels:
    kargo.akuity.io/alias: jolly-penguin  # human-friendly name
spec:
  origin:
    kind: Warehouse
    name: my-warehouse
  images:
  - repoURL: myacr.azurecr.io/my-web-app
    tag: "1.5.0"
    digest: sha256:a1b2c3d4e5f6...
  commits:
  - repoURL: https://github.com/my-org/k8s-config.git
    id: 7f8e9d0c...

Freight Lifecycle

Created by Warehouse when new version discovered
↓
Promoted to dev Stage
↓
Verified in dev (verification passes)
↓
Approved for staging (manual or auto)
↓
Promoted to staging Stage
↓
Verified in staging → Continue to prod...

Freight Status Tracking

status:
  verifiedIn:
    dev:
      verifiedAt: "2024-01-15T10:30:00Z"
    staging:
      verifiedAt: "2024-01-15T11:00:00Z"
  approvedFor:
    staging:
      approvedAt: "2024-01-15T10:45:00Z"
    prod:
      approvedAt: "2024-01-15T11:15:00Z"

Kargo tracks exactly where each Freight has been verified and approved. Full audit trail.

Quiz 2 — Freight Deep Dive

1. What happens to Freight after it is created?

a) It is immediately deployed to all stages b) It is promoted through stages, tracking verification and approval status c) It is deleted after 24 hours

2. In a multi-source Warehouse, when is new Freight created?

a) Only when ALL sources have new versions simultaneously b) When any subscribed source has a new version c) On a fixed schedule regardless of changes

3. Can Freight be modified after creation?

a) Yes, you can update the image tags b) No, Freight is immutable once created c) Only admins can modify Freight

Working with Freight

# List all Freight in a project
kargo get freight --project my-web-app

# Output:
# NAME            ALIAS           ORIGIN        AGE
# abc123def456    jolly-penguin   my-warehouse  5m
# def789ghi012    brave-dolphin   my-warehouse  2h

# Describe a specific Freight
kargo get freight abc123def456 \
  --project my-web-app -o yaml

# Via kubectl
kubectl get freight -n my-web-app

Freight Aliases

Human-Friendly Names

Every Freight gets an auto-generated alias (e.g., jolly-penguin, brave-dolphin) so you don't have to remember hash IDs.

Use aliases in CLI commands: kargo promote --freight jolly-penguin
Displayed in the Kargo UI for easy identification
You can also set custom aliases

Credentials for Private Repos

Kargo uses Kubernetes Secrets to authenticate with private registries and repos.

# For container registries
kubectl create secret generic my-registry-creds \
  --namespace my-web-app \
  --from-literal=username=myuser \
  --from-literal=password=mytoken

# Label it so Kargo discovers it
kubectl label secret my-registry-creds \
  --namespace my-web-app \
  kargo.akuity.io/cred-type=image

# Annotate with the repo URL pattern
kubectl annotate secret my-registry-creds \
  --namespace my-web-app \
  kargo.akuity.io/repo-url="myacr.azurecr.io"

Git Repository Credentials

# For Git repos (HTTPS with token)
kubectl create secret generic my-git-creds \
  --namespace my-web-app \
  --from-literal=username=git \
  --from-literal=password=ghp_xxxxxxxxxxxx

kubectl label secret my-git-creds \
  --namespace my-web-app \
  kargo.akuity.io/cred-type=git

kubectl annotate secret my-git-creds \
  --namespace my-web-app \
  kargo.akuity.io/repo-url="https://github.com/my-org"

# For SSH-based Git access
kubectl create secret generic my-git-ssh \
  --namespace my-web-app \
  --from-file=sshPrivateKey=/path/to/key

kubectl label secret my-git-ssh \
  kargo.akuity.io/cred-type=git

Azure Container Registry (ACR) Credentials

# Option 1: Service Principal
kubectl create secret generic acr-creds \
  --namespace my-web-app \
  --from-literal=username=$SP_APP_ID \
  --from-literal=password=$SP_PASSWORD

kubectl label secret acr-creds \
  --namespace my-web-app \
  kargo.akuity.io/cred-type=image

kubectl annotate secret acr-creds \
  --namespace my-web-app \
  kargo.akuity.io/repo-url="myacr.azurecr.io"

# Option 2: Workload Identity (recommended for AKS)
# Configure the Kargo controller SA with
# federated credentials to access ACR

Complete Warehouse Example

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-warehouse
  namespace: my-web-app
spec:
  subscriptions:
  - image:
      repoURL: myacr.azurecr.io/my-web-app
      imageSelectionStrategy: SemVer
      semverConstraint: ">=1.0.0"
  - git:
      repoURL: https://github.com/my-org/k8s-config.git
      branch: main
      includePaths:
      - "apps/my-web-app/**"

This Warehouse creates Freight whenever a new image tag or a new Git commit appears.

Quiz 3 — Credentials & Configuration

1. How does Kargo authenticate with private container registries?

a) Via labeled and annotated Kubernetes Secrets in the project namespace b) By reading Docker config from the node c) Through environment variables on the controller pod

2. Which label must be applied to a Secret for Kargo to use it for image registry credentials?

a) kargo.akuity.io/cred-type=image b) app.kubernetes.io/type=registry c) kargo/registry-secret=true

3. What filtering can you apply to a Git subscription in a Warehouse?

a) includePaths and excludePaths to watch specific directories b) Only branch name, no path filtering is supported c) File extension filtering only

Troubleshooting Warehouses

Freight not appearing? — Check Warehouse status: kubectl describe warehouse my-warehouse -n my-web-app
Auth errors? — Verify Secret labels and annotations match repo URLs
Wrong versions? — Check semverConstraint, allowTags, and ignoreTags regex
No new Freight? — Ensure the actual tag exists in the registry and matches your filter
Controller logs: kubectl logs -n kargo deploy/kargo-controller

Key Takeaways

Warehouses watch artifact sources: images, Git repos, Helm charts
Three image strategies: SemVer, NewestBuild, Digest
Freight is an immutable bundle of artifact versions
Freight tracks verification and approval status as it moves through stages
Credentials use labeled Kubernetes Secrets in the project namespace
Multiple subscriptions per Warehouse — Freight bundles all sources together

Up Next

Module 03: Stages & Promotions

Checkpoints in your delivery pipeline and the recipes for deploying changes.

Promotion Templates Git Workflows Multi-Stage Pipelines