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
