Chapter 3: Getting started with Kargo
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
- Kargo’s delivery stack role. Describe Kargo’s responsibility between CI and GitOps, distinguishing promotion governance from building artifacts and deploying them.
- Kubernetes-native operating model. Explain what Kubernetes-native means for how Kargo represents and operates its resources.
- Project scope and boundary. Explain that a Project provides the team-or-service scope for Kargo resources through a Kubernetes namespace and its RBAC, and that the other resources live within that boundary.
- Artifact promotion path. Trace how a Warehouse discovers an artifact and produces immutable Freight, how a Stage subscribes to eligible Freight, and how a Promotion records its advancement into a Stage.
- Warehouse discovery role. Explain how a Warehouse discovers artifacts and what it does not do.
- Immutable Freight identity. Explain why a Freight continues to identify the same artifacts even if an image tag is later repushed, and how that supports promotion lineage.
- Atomic artifact bundles. Explain how one Freight can carry multiple artifact versions and what happens when it is promoted to a Stage.
- Stage eligibility and ordering. Explain how a Stage models an environment, determines which Freight is eligible, and enforces promotion order through its subscriptions.
- Stage promotion step execution. Trace what the described dev Stage steps do with a Freight version and distinguish continuous eligibility evaluation from Promotion execution.
- Promotion as a durable event. Explain that a Promotion represents one explicit advancement of specific Freight to a specific Stage and remains in the cluster after it runs, making the advancement queryable.
- Promotion status and inspection. Trace how the Promotion controller updates status as template steps run, and explain what status reveals for automation, auditing, and failure diagnosis.
- Project scope and isolation. Explain how a Project groups one team’s or service’s Kargo resources, and what Kargo creates when the Project is created. Describe why separate teams typically use separate Projects.
- Sequential promotion handoffs. Trace the order from discovery of a new image version through Freight eligibility, Promotion creation, and the GitOps repository update.
- Git-mediated Argo CD handoff. Explain how Argo CD enters the promotion sequence and what the Stage controller may check afterward.
- Kubernetes cluster prerequisites. Describe the cluster and privileges needed to install Kargo, including why a local cluster is sufficient for the examples.
- Cert-manager installation dependency. Explain why cert-manager must be installed before the default Kargo installation and what happens if it is absent.
- Required workstation tools. State which workstation tools are needed for installation and what each is used for, including the kubectl context check and Helm version requirement.
- Helm installation and CRDs. Describe the installation sequence: create a dedicated namespace, generate admin credentials, and install the Kargo Helm chart. Explain that CRD installation varies by chart version, so missing-CRD errors may require consulting that version’s release notes.
- Post-installation health checks. Explain why an error-free Helm install does not finish verification. Describe checking for all four CRDs and inspecting controller health and logs for reconciliation and RBAC errors, even if pods appear healthy.
- Image discovery and Freight identity. Trace how a new demo-app image becomes Freight: the Warehouse finds a version that satisfies its semver constraint and produces a Freight object pinned to the image digest.
- Git handoff and workload reconciliation. Trace the dev Promotion from its GitOps edit to a running pod, and distinguish Kargo’s Git-writing work from Argo CD’s reconciliation work.
- Upstream Freight stage ordering. Explain why staging can advance only Freight that has passed through dev, and production only Freight that has passed through staging.
- Kargo and Argo CD roles. Explain that Kargo orchestrates promotions while Argo CD reconciles the resulting changes into the cluster.
- GitOps reconciler compatibility. Distinguish Kargo’s Git-based promotion steps, which work with other GitOps reconcilers, from its Argo CD-specific argocd-update step.
- Shared GitOps repository roles. Explain how Kargo and Argo CD use the GitOps repository: Kargo writes to it during promotions, and Argo CD reads from it during reconciliation.
- Project namespace and resources. Explain why a Project must be created before other Kargo resources and what Kargo creates when the Project is created.
- Applications for each environment. Describe why the Argo CD Applications must exist before promotions and how the dev, staging, and prod Applications differ.
- Stage authorization and project association. Explain what the authorized-stage annotation and project label do on an Application.
- Git write credentials. Explain why Kargo needs GitOps repository write access and describe the credential to store in a Kubernetes Secret in the demo Project namespace.
- Secret discovery and reference. Explain how Kargo discovers the Git credential Secret and how Stage promotion templates refer to it.
- Warehouse inventory and Freight discovery. Explain that a Warehouse defines the artifacts Kargo tracks and supplies the Freight inventory for downstream Stages. Describe how its controller polls the registry and creates one Freight object per image version that meets the semver constraint.
- Content hashes versus image tags. Justify why Kargo names Freight by content hash rather than image tag, using the example of a tag being repushed to a different digest.
- Stage subscriptions and ordering. Explain how the three Stages subscribe to Freight sources and why staging can receive only Freight already verified in dev.
- First Promotion execution and confirmation. Describe how to start a Promotion and tell when it has completed. Explain how the GitOps repository and Argo CD Application confirm the dev update.
- Verified dev Freight eligibility. Explain why the same Freight can advance to staging and why unverified Freight is rejected.
- Kargo resource diagnostics. Explain how kubectl describe helps locate a promotion failure by showing a Kargo resource’s status, recent events, and per-step execution details.
- Warehouse failure diagnosis. Describe how to investigate a Warehouse that produces no Freight by inspecting its status conditions before checking likely causes.
- Git push authentication checks. Describe how to recognize a git-push authentication failure and check the token’s write scope, the credential Secret’s namespace, and the repository URL format in order.
- Post-promotion Argo CD checks. Describe how to troubleshoot an unchanged cluster after a successful Promotion: confirm the Argo CD Application exists, check that the Stage names it exactly, and verify Argo CD can access the GitOps repository.
- Staging Freight eligibility. Explain why staging rejects Freight that has not passed through dev, and what makes it eligible.
- Controller log troubleshooting. Describe when to inspect Kargo controller logs and how to narrow them to a misbehaving resource.
What it builds on
- Nothing an auditor can read (chapter 2) · The difficulty of reconstructing promotion decisions from the existing delivery layer.
- Where Kargo fits in the delivery stack (chapter 1) · The placement of Kargo in the delivery stack.
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.
- The GitOps promotion gap: Explain why reliable GitOps deployment does not, by itself, answer who decides what goes into Git, when, under what conditions, and with whose approval.
Why it matters: It explains why a team might need Kargo even when Argo CD deployments are working well. - Kargo’s delivery stack role: Describe Kargo’s responsibility between CI and GitOps, distinguishing promotion governance from building artifacts and deploying them.
Why it matters: This boundary clarifies what Kargo adds to an existing CI and GitOps toolchain. - Kubernetes-native operating model: Explain what Kubernetes-native means for how Kargo represents and operates its resources.
Why it matters: A team familiar with Kubernetes can work with Kargo using familiar resources, tools, and controller concepts.
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.
- Project scope and boundary: Explain that a Project provides the team-or-service scope for Kargo resources through a Kubernetes namespace and its RBAC, and that the other resources live within that boundary.
Why it matters: The Project boundary tells you where a promotion graph and its access controls belong. - Artifact promotion path: Trace how a Warehouse discovers an artifact and produces immutable Freight, how a Stage subscribes to eligible Freight, and how a Promotion records its advancement into a Stage.
Why it matters: Following one artifact through the resources makes the promotion graph easier to read.
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.
- Warehouse discovery role: Explain how a Warehouse discovers artifacts and what it does not do.
Why it matters: This separates artifact discovery from the later work of promoting and deploying an artifact. - Subscription eligibility and access: Describe how a Warehouse subscription limits eligible versions and what registry access requires.
Why it matters: Source access and version constraints determine whether a Warehouse produces the Freight you expect. - Project scope and bundled sources: Explain how Warehouse names and multiple subscriptions work within a Project.
Why it matters: This explains how Stages identify an artifact source and how a service’s related artifacts can travel together.
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.
- Immutable Freight identity: Explain why a Freight continues to identify the same artifacts even if an image tag is later repushed, and how that supports promotion lineage.
Why it matters: An immutable identity lets you tell which build was promoted, even after a tag changes. - Freight creation and origin: Describe how Freight objects are created and what their name and origin indicate.
Why it matters: These fields help you recognize a Freight and trace where it came from. - Atomic artifact bundles: Explain how one Freight can carry multiple artifact versions and what happens when it is promoted to a Stage.
Why it matters: Promoting a bundle together prevents a Stage from receiving an arbitrary mix of artifact versions.
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.
- Stage eligibility and ordering: Explain how a Stage models an environment, determines which Freight is eligible, and enforces promotion order through its subscriptions.
Why it matters: A Stage’s subscriptions determine which artifact versions can move into each environment. - Stage promotion step execution: Trace what the described dev Stage steps do with a Freight version and distinguish continuous eligibility evaluation from Promotion execution.
Why it matters: It connects an eligible Freight version to the Git change and reconciliation that advance an environment.
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.
- Promotion as a durable event: Explain that a Promotion represents one explicit advancement of specific Freight to a specific Stage and remains in the cluster after it runs, making the advancement queryable.
Why it matters: The persistent object lets you find a record of an advancement after it has finished. - Promotion creation options: Describe how a Promotion can be created by auto-promotion policy, the UI, or the kargo CLI or kubectl, and distinguish the command-line inputs and naming options described here.
Why it matters: You can choose a convenient way to request an advancement without changing what resource Kargo processes. - Promotion status and inspection: Trace how the Promotion controller updates status as template steps run, and explain what status reveals for automation, auditing, and failure diagnosis.
Why it matters: The same resource shows both what happened and where to start investigating if it failed.
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.
- Project scope and isolation: Explain how a Project groups one team’s or service’s Kargo resources, and what Kargo creates when the Project is created. Describe why separate teams typically use separate Projects.
Why it matters: The Project determines where a team’s Kargo resources live and how they are separated from other teams’ resources. - Controller-based problem diagnosis: Distinguish the Warehouse, Stage, and Promotion controllers by their jobs, and identify which controller’s logs to check for discovery, eligibility, or mid-promotion failures.
Why it matters: Matching a symptom to its controller gives you a focused first place to investigate. - Sequential promotion handoffs: Trace the order from discovery of a new image version through Freight eligibility, Promotion creation, and the GitOps repository update.
Why it matters: The ordered handoffs show what has to happen before a deployment change can reach Git. - Git-mediated Argo CD handoff: Explain how Argo CD enters the promotion sequence and what the Stage controller may check afterward.
Why it matters: This boundary clarifies why a completed Kargo Git update and an Argo CD cluster sync are separate events.
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.
- Kubernetes cluster prerequisites: Describe the cluster and privileges needed to install Kargo, including why a local cluster is sufficient for the examples.
Why it matters: Checking the cluster and permissions first prevents avoidable installation failures. - Cert-manager installation dependency: Explain why cert-manager must be installed before the default Kargo installation and what happens if it is absent.
Why it matters: This dependency explains a specific startup failure you can avoid before installing Kargo. - Required workstation tools: State which workstation tools are needed for installation and what each is used for, including the kubectl context check and Helm version requirement.
Why it matters: Having the right tools and Helm version ready makes the installation steps executable. - Later walkthrough tools: Distinguish tools required for installation from those used starting with the first promotion walkthrough.
Why it matters: This distinction helps you prepare for the walkthrough without treating its tools as installation blockers.
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.
- Helm installation and CRDs: Describe the installation sequence: create a dedicated namespace, generate admin credentials, and install the Kargo Helm chart. Explain that CRD installation varies by chart version, so missing-CRD errors may require consulting that version’s release notes.
Why it matters: Knowing the installation sequence and CRD caveat helps you get Kargo ready before creating its resources. - Admin credentials and Helm settings: Explain why the plaintext admin password must be saved securely and distinguish it from the temporary hash and signing-key variables. State why both Helm --set values are required and what --wait adds.
Why it matters: Keeping the login password while supplying the required Helm settings avoids losing access or failing installation. - Post-installation health checks: Explain why an error-free Helm install does not finish verification. Describe checking for all four CRDs and inspecting controller health and logs for reconciliation and RBAC errors, even if pods appear healthy.
Why it matters: Verification catches installation faults before they become confusing failures when you create Kargo resources.
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.
- Image discovery and Freight identity: Trace how a new demo-app image becomes Freight: the Warehouse finds a version that satisfies its semver constraint and produces a Freight object pinned to the image digest.
Why it matters: It identifies the specific artifact that moves through the promotion chain. - Git handoff and workload reconciliation: Trace the dev Promotion from its GitOps edit to a running pod, and distinguish Kargo’s Git-writing work from Argo CD’s reconciliation work.
Why it matters: The Git commit is the handoff point between promotion and deployment. - Environment paths and Applications: Describe how the GitOps repository and Argo CD Applications connect each environment’s desired state to its Kubernetes namespace.
Why it matters: Separate paths and Applications let a promotion change one environment while Argo CD syncs the matching namespace. - Upstream Freight stage ordering: Explain why staging can advance only Freight that has passed through dev, and production only Freight that has passed through staging.
Why it matters: Upstream Freight selection keeps later environments from advancing an artifact before it passes through earlier ones.
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.
- Kargo and Argo CD roles: Explain that Kargo orchestrates promotions while Argo CD reconciles the resulting changes into the cluster.
Why it matters: This distinction clarifies which tool is responsible for each part of the examples. - Argo CD installation state: Describe what to check after installing Argo CD and distinguish an installed instance from one configured with applications.
Why it matters: Running components confirm installation without implying that an application is ready to sync. - GitOps reconciler compatibility: Distinguish Kargo’s Git-based promotion steps, which work with other GitOps reconcilers, from its Argo CD-specific argocd-update step.
Why it matters: It explains why these examples require Argo CD even though some Kargo steps can work with other reconcilers.
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.
- Shared GitOps repository roles: Explain how Kargo and Argo CD use the GitOps repository: Kargo writes to it during promotions, and Argo CD reads from it during reconciliation.
Why it matters: This distinction explains why both tools must point to the GitOps repository. - Independent environment image pins: Describe how the forked repository represents application images across environments and what promotions will change.
Why it matters: Separate image pins let a promotion advance one environment without requiring the others to advance with it. - Forked repository URL setup: Describe how to prepare the example repository and adapt its URL in the later YAML examples.
Why it matters: Using the fork’s URL consistently makes the later configurations refer to your repository.
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.
- Project namespace and resources: Explain why a Project must be created before other Kargo resources and what Kargo creates when the Project is created.
Why it matters: The Project establishes where the application’s Kargo resources live before you create them. - Project creation verification: Describe how to check that Kargo processed an applied Project and what to do if the namespace is not found.
Why it matters: Checking the namespace catches a Project that was applied but not processed by Kargo.
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.
- Applications for each environment: Describe why the Argo CD Applications must exist before promotions and how the dev, staging, and prod Applications differ.
Why it matters: An environment needs its own Application in place before its promotion can ask Argo CD to reconcile. - Stage authorization and project association: Explain what the authorized-stage annotation and project label do on an Application.
Why it matters: These fields determine whether a Stage can trigger a sync and whether its Application appears with it in the Kargo UI. - GitOps path and automated reconciliation: Explain how an Application's source path and automated sync policy relate to Kargo's GitOps changes.
Why it matters: Argo CD must watch the directory Kargo changes for those changes to reach the cluster.
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.
- Git write credentials: Explain why Kargo needs GitOps repository write access and describe the credential to store in a Kubernetes Secret in the demo Project namespace.
Why it matters: Without suitable write credentials, Kargo cannot push a promotion’s image-tag changes. - Secret discovery and reference: Explain how Kargo discovers the Git credential Secret and how Stage promotion templates refer to it.
Why it matters: A Secret that exists but lacks the Git credential label will not be found by Kargo’s Git steps. - Git token safety: Describe how to handle the token-bearing Secret in a learning environment versus a shared or production cluster.
Why it matters: The exercise’s convenient credential setup should not become an unsafe production practice.
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.
- Warehouse inventory and Freight discovery: Explain that a Warehouse defines the artifacts Kargo tracks and supplies the Freight inventory for downstream Stages. Describe how its controller polls the registry and creates one Freight object per image version that meets the semver constraint.
Why it matters: It connects the images in a registry to the Freight available for promotion. - Content hashes versus image tags: Justify why Kargo names Freight by content hash rather than image tag, using the example of a tag being repushed to a different digest.
Why it matters: A stable Freight reference lets you identify the artifact that was actually observed, even if someone later changes its 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.
- Stage subscriptions and ordering: Explain how the three Stages subscribe to Freight sources and why staging can receive only Freight already verified in dev.
Why it matters: The subscriptions determine which Freight each environment can promote. - Environment-specific Stage settings: Describe how the Stage definitions target their respective environment overlays and Argo CD Applications, including the required Application-name match.
Why it matters: Each Stage must point to the overlay and Application for the environment it represents.
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.
- First Promotion execution and confirmation: Describe how to start a Promotion and tell when it has completed. Explain how the GitOps repository and Argo CD Application confirm the dev update.
Why it matters: These checks distinguish a completed Promotion from the Git and Argo CD changes it produces. - Stage lineage and Freight identity: Explain what the Stage status records after promotion and why the Freight’s image digest matters.
Why it matters: The status connects the Stage’s current version and verification state to a stable artifact identity. - Verified dev Freight eligibility: Explain why the same Freight can advance to staging and why unverified Freight is rejected.
Why it matters: The upstream requirement prevents staging from accepting Freight that has not been verified in dev.
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.
- Kargo resource diagnostics: Explain how kubectl describe helps locate a promotion failure by showing a Kargo resource’s status, recent events, and per-step execution details.
Why it matters: It gives you a starting point for finding which part of a promotion failed.
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.
- Warehouse failure diagnosis: Describe how to investigate a Warehouse that produces no Freight by inspecting its status conditions before checking likely causes.
Why it matters: The status message gives you a starting point instead of guessing why Freight is absent. - Image tag selection mismatch: Explain how a Warehouse's image selection settings can prevent it from finding registry tags, and describe the suggested adjustments.
Why it matters: A working registry can still yield no Freight when its tags do not match the Warehouse's selection rule. - Private registry credential visibility: Explain why a Warehouse may fail to list tags from a private registry even when a credential Secret exists.
Why it matters: Checking both the Secret's namespace and label can reveal why private-registry tags are unavailable.
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.
- Git push authentication checks: Describe how to recognize a git-push authentication failure and check the token’s write scope, the credential Secret’s namespace, and the repository URL format in order.
Why it matters: These checks narrow a failed push to the credentials Kargo needs to write to the 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.
- Post-promotion Argo CD checks: Describe how to troubleshoot an unchanged cluster after a successful Promotion: confirm the Argo CD Application exists, check that the Stage names it exactly, and verify Argo CD can access the GitOps repository.
Why it matters: These checks narrow down why a completed promotion has not produced a cluster change.
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.
- Staging Freight eligibility: Explain why staging rejects Freight that has not passed through dev, and what makes it eligible.
Why it matters: This helps you recognize a rejected staging promotion as an ordering safeguard rather than a bug.
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.
- Controller log troubleshooting: Describe when to inspect Kargo controller logs and how to narrow them to a misbehaving resource.
Why it matters: Resource-specific logs can reveal what the controller encountered when the earlier checks did not identify the problem. - Abnormal condition practice: Explain why the section recommends deliberately testing abnormal conditions, using its examples of observable behavior.
Why it matters: Watching how the system responds to deliberate disruptions makes unexpected behavior less daunting in operation.
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
- artifact promotionThe controlled advancement of an artifact version from one deployment environment to another.
- WarehouseA Warehouse is a Kargo resource that watches artifact sources and produces Freight.
- FreightFreight is a Kargo immutable unit representing a tracked artifact version or collection of artifact versions.
- stageAn explicit environment node in a Kargo promotion progression that represents a deployment state for artifact versions.
- KargoKargo is an open-source, Kubernetes-native promotion control plane for governing artifact advancement across deployment environments.
- ProjectA Project is a Kargo resource that scopes delivery resources to a Kubernetes namespace and its associated access controls.
- semantic version constraintA rule that selects versions according to Semantic Versioning ordering or range conditions.
- cryptographic hashA digest is a content-derived identifier, typically a cryptographic hash, that uniquely identifies an artifact version.
- custom resource definitionA Kubernetes API extension that defines a new resource type and its schema for storing domain-specific objects.
- argocd-update promotion stepThe argocd-update promotion step is a Kargo promotion-step type that updates an Argo CD application or related deployment state.
- Argo CD applicationAn Argo CD application is an Argo CD resource that defines an application's desired state, source, destination, and synchronization behavior.
- progression graphA directed graph representing deployment environments as stages and the governed paths by which artifacts advance between them.
- ArgoCDArgo CD is a GitOps continuous delivery tool that continuously reconciles Kubernetes application state with version-controlled configuration.
- image tagA mutable human-readable label associated with a container image version in a registry.
- GitOps repositoryA GitOps repository is a Git repository whose declarative configuration represents the desired state of an environment.
- promotion control planeAn architectural layer that coordinates artifact advancement between environments independently of build and runtime synchronization.
- Kargo Promotion controllerA Kargo Kubernetes controller that executes steps for Promotion resources and records their status.
- container imageA container image is a packaged, immutable filesystem and metadata representation used to instantiate a container.
- stage controllerA Stage controller is a Kargo controller that evaluates Freight eligibility for a Stage and manages promotion eligibility and verification.
- Kubernetes controllerA control loop that observes Kubernetes resources and acts to move their actual state toward the declared desired state.
- artifact identityArtifact identity is the information that uniquely specifies a deployable artifact version, including identifiers such as a digest and provenance data.
- audit trailAn audit trail is a chronological record of actions, decisions, identities, and evidence that permits operational activity to be verified.
- productionA production environment is the operational environment that serves software to its real users or dependent systems.
- staging environmentA pre-production environment where an application version is validated before production.
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.
