liveBook · Manning

Warehouse

As explained in Kargo in Action

A Warehouse is a Kargo resource that watches artifact sources and produces Freight.

A Warehouse is Kargo’s entry point for artifact discovery. Its controller polls subscribed container registries, Helm chart repositories, or Git repositories and creates Freight for eligible versions. It does not deploy artifacts or choose their destination. Stages draw from the resulting Freight inventory; Promotions record advancements into those Stages. section 3.2.1 section 3.2

Listing 3.1 The demo-app Warehouse subscribed to a container image registry
apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: demo-app                                   # #1
  namespace: demo                                  # #2
spec:
  subscriptions:                                   # #3
  - image:
      repoURL: ghcr.io/kargobook/demo-app          # #4
      semverConstraint: ">=1.0.0 <2.0.0"           # #5

The manifest shows a Warehouse named demo-app in the demo Project namespace. Its image subscription watches ghcr.io/kargobook/demo-app and accepts versions matching >=1.0.0 <2.0.0. A Stage can refer to the Warehouse by name as its Freight origin. section 3.2.1

From image push to deployment

After image 1.1.0 is pushed, the Warehouse discovers it and produces Freight pinned to its digest. A dev Stage can then promote that Freight by updating a GitOps repository. Argo CD, not the Warehouse, reconciles the changed Git state into the cluster. The same Freight can advance to staging once it has been verified in dev. section 3.5 section 3.5.7

A Warehouse can combine subscriptions—for example, an image, chart, and Git repository—so each Freight carries a coherent set of artifact versions. Freight is created automatically and identified by content rather than a mutable image tag. section 3.2.1 section 3.2.2

If no Freight appears after applying a Warehouse:

  • Run kubectl get freight -n demo, then kubectl describe warehouse demo-app -n demo. Check status.conditions for a Healthy=False message. section 3.5.5 section 3.6.1
  • Check whether available tags match semverConstraint or imageSelectionStrategy. Tags such as latest or main will not match a semver range; consider Lexical or NewestBuild for non-semver tags. section 3.6.1
  • For a private image registry, check for a Secret in the Project namespace labeled kargo.akuity.io/cred-type: image. An unlabeled Secret is invisible to the Warehouse controller. section 3.6.1

How Kargo in Action covers it

How deep it goes
Explains subscriptions, version selection, controller polling, verification, and common failures; stops short of controller internals.
Examples
Uses an image-registry Warehouse manifest, an image-to-GitOps promotion, and kubectl checks for absent Freight.
What it assumes
Assumes a Kubernetes Project namespace and an artifact source; introduces Warehouse and Freight relationships before the promotion workflow.
What you can do after
Operate/configure it with a Warehouse manifest and diagnose missing Freight through status, tag selection, and registry credentials.
How it connects
Connects Projects, Freight, Stages, and Promotions through artifact discovery and promotion lineage.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Kargo in Action. The section links point to the parts of the book it draws on.