liveBook · Manning

Chapter 3: Getting started with Kargo

What you will learn in chapter 3 of Kargo in Action

This chapter introduces the plan to install Kargo and Argo CD, model a delivery workflow, run a first promotion, and troubleshoot common failures.

After this chapter you will be able to

What it builds on

Section by section

Introduction

This chapter introduces the plan to install Kargo and Argo CD, model a delivery workflow, run a first promotion, and troubleshoot common failures.

3.1 What Kargo is and where it fits

This section explains the promotion gap Kargo fills, its boundaries with CI and Argo CD, and what it means for Kargo to be Kubernetes-native.

Key terms: GitOps, Argo CD, state declared in Git, promotion control plane, CI, cluster reconciliation, Kubernetes-native, Custom Resource Definitions, CRDs, kubectl

3.2 The core resource model

Introduces Kargo’s five resource types by tracing an artifact from discovery to promotion within a Project.

Key terms: Project, Kubernetes namespace, RBAC, Warehouse, Freight, Stage, Promotion, artifact bundle, promotion graph

3.2.1 Warehouse: where artifacts come from

This section explains how a Warehouse discovers eligible artifact versions and registers them as Freight without deploying them.

Key terms: Warehouse, Freight, artifact discovery, subscription, repoURL, semverConstraint, Secret, Project, requestedFreight.origin

3.2.2 Freight: an immutable artifact identity

This section explains how Kargo creates Freight to identify immutable artifact versions and promote coherent bundles through Stages.

Key terms: Freight, digest, SHA, tag, lineage, Warehouse controller, name, origin, Warehouse, Stage

3.2.3 Stage: a node in the promotion graph

This section explains how a Stage selects eligible Freight and defines the steps that run when that Freight is promoted.

Key terms: Stage, Freight, Warehouse, direct: true, sources.stages, Stage controller, Promotion object, kustomize-set-image, imageFrom, argocd-update

3.2.4 Promotion: a durable advancement event

This section explains how a Promotion advances Freight to a Stage, persists as an audit record, and reports its progress and results.

Key terms: Promotion, Freight, Stage, audit trail, auto-promotion policy, Promote button, kargo CLI, kubectl, generateName, Promotion controller

3.2.5 Project: the team or service scope

This section explains how Projects scope Kargo resources, how controllers divide promotion work, and how a promotion reaches Argo CD through a Git update.

Key terms: Project, namespace, RBAC, isolation boundary, Warehouse controller, Stage controller, Promotion controller, controller logs, Freight, Stage

3.3 What you need before you start

This section identifies the cluster prerequisites, cert-manager dependency, and workstation tools needed before installing Kargo and following the first promotion walkthrough.

Key terms: Kubernetes cluster, CRDs, cluster-scoped RBAC resources, controllers, cert-manager, TLS certificate, API server, Kargo pods, kubectl, kubeconfig context

3.4 Installing Kargo

This section explains how to install Kargo with Helm and verify that the installation is ready for use.

Key terms: Helm chart, CRDs, controllers, RBAC, $pass, $hashed_pass, $signing_key, passwordHash, tokenSigningKey, --wait

3.5 Building your first promotion

This section traces a demo-app image from registry discovery through GitOps promotion and Argo CD deployment, then shows how the same flow advances through ordered environments.

Key terms: Warehouse, semver constraint, Freight, digest, lineage record, Promotion, dev Stage, GitOps repository, envs/dev overlay, Argo CD Application

3.5 Installing Argo CD

This section explains Argo CD’s role alongside Kargo, what to verify after installation, and why the book’s promotion examples use Argo CD.

Key terms: Kargo, Argo CD, promotions, reconciles, Argo CD server, application controller, repository server, Running, applications, Git-based promotion steps

3.5.1 Preparing the GitOps repository

This section prepares a forked GitOps repository as the shared state store for Kargo promotions and Argo CD reconciliation.

Key terms: GitOps repository, promotions, reconciliation, environment directory, kustomization.yaml, application image, initial tag, demo-gitops, fork, GitOps repository URL

3.5.2 Creating the Kargo Project

This section creates a Kargo Project as the namespace for an application’s resources and shows how to verify that Kargo processed it.

Key terms: Project, namespace, RBAC, Warehouse, Stage, Freight, NotFound, Kargo controller, controller logs

3.5.3 Creating the Argo CD Applications

This section shows how to create one Argo CD Application per environment and explains the settings that let Kargo promotions trigger reconciliation.

Key terms: Argo CD Application, Stage, argocd-update, source.path, destination.namespace, kargo.akuity.io/authorized-stage, kargo.akuity.io/project, kustomization.yaml, kustomize-set-image, syncPolicy

3.5.4 Configuring Git credentials for Kargo

This section explains how to give Kargo Git write credentials for promotions, make those credentials discoverable, and handle them safely.

Key terms: GitOps repository, Kubernetes Secret, personal access token, repository write scope, kargo.akuity.io/cred-type: git, demo-git-creds, git-clone, git-push, Stage promotion templates, Secret manifest

3.5.5 Defining the Warehouse

This section explains how a Warehouse discovers eligible images as Freight and why Kargo identifies that Freight by content hash rather than image tag.

Key terms: Warehouse, Warehouse controller, Freight, semver constraint, Stages, content hash, image tag, digest

3.5.6 Defining the Stages

This section defines dev, staging, and prod Stages so Freight advances through them in order, with each Stage targeting its own environment.

Key terms: Stage, Warehouse, Freight, direct: true, sources.stages, overlay path, Argo CD Application name, metadata.name, envs/dev, envs/prod

3.5.7 Triggering your first Promotion

This section shows how to trigger a first Promotion, confirm its effects, and advance verified Freight from dev to staging.

Key terms: Promotion, Succeeded phase, GitOps repository, Argo CD Application, Stage’s status, Freight, verification state, image digest, artifact identity, staging Stage

3.6 Troubleshooting your first promotion

Introduces kubectl describe as the main diagnostic tool for a failed first promotion.

Key terms: kubectl describe, status, recent events, per-step execution details

3.6.1 The Warehouse produces no Freight

This section shows how to diagnose a Warehouse that produces no Freight and check two common causes: image selection rules and private-registry credentials.

Key terms: Freight, Warehouse, status.conditions, Healthy, imageSelectionStrategy, semverConstraint, Lexical, NewestBuild, Warehouse controller, Project namespace

3.6.2 The Promotion fails at git-push

This section shows how to diagnose a Promotion that fails at git-push because Kargo cannot authenticate to the Git repository.

Key terms: Promotion, Failed phase, status.steps, git-push, demo-git-creds Secret, repoURL

3.6.3 Argo CD doesn’t sync after a successful promotion

This section gives three checks for diagnosing why Argo CD has not updated the cluster even though a Promotion succeeded and the GitOps commit exists.

Key terms: Promotion, Application, argocd-update, OutOfSync, GitOps repository

3.6.4 Staging refuses to promote

Explains why staging may reject Freight and how completing its dev promotion makes it eligible.

Key terms: Freight, staging Stage, dev Stage, upstream source, Promotion, Succeeded

3.6.5 Reading the controller logs

This section shows when and how to use Kargo controller logs for troubleshooting and encourages testing abnormal conditions to build operational confidence.

Key terms: Kargo controller logs, Warehouse, Stage, reconciliation loop, Freight eligibility, Freight, selfHeal, Promotion, Stage’s history

3.7 Summary

Concepts explained in this chapter

← Chapter 2: The layer nobody designed

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.