liveBook · Manning

Freight

As explained in Kargo in Action

Freight is a Kargo immutable unit representing a tracked artifact version or collection of artifact versions.

Freight is Kargo’s immutable record of a specific artifact version or bundle of versions. A Warehouse creates it when it discovers eligible artifacts; you do not author it by hand. Images are identified by digest and Git revisions by SHA, so a mutable tag cannot silently change what an existing Freight represents. section 3.2.2

Listing 3.2 A Freight object as Kargo creates it (illustrative, not for authoring)
apiVersion: kargo.akuity.io/v1alpha1
kind: Freight
metadata:
  name: 7b2f9a8e3c1d5f4a6b8e9c0d2f1a5b7c    # #1
  namespace: demo
spec:
  origin:
    kind: Warehouse
    name: demo-app                           # #2
  images:
  - repoURL: ghcr.io/kargobook/demo-app
    tag: 1.2.0                               # #3
    digest: sha256:a3b9e7f2c1d4f8a2b6c4e1d7   # #4

Inspect the illustrative Freight object: its content-derived name identifies the bundle, origin names the producing Warehouse, and the image digest fixes identity while the tag remains readable. section 3.2.2

Follow one image through promotion:

  • A Warehouse discovers an eligible registry version and creates Freight pinned to its digest. Run `kubectl get freight -n demo` to check that discovery produced an object. section 3.5 section 3.5.5
  • A Stage subscribes to Freight from a Warehouse or upstream Stage. A Promotion names the Freight and destination Stage, recording that advancement and its outcome. section 3.2
  • For the dev environment, promotion updates the GitOps repository; Argo CD then reconciles the change into the cluster. The same Freight can advance to staging after verification in dev. section 3.5 section 3.5.7

A Freight can bundle an image, chart, and Git revision. Promoting it advances those selected versions together, preserving a coherent artifact set. To inspect what reached a Stage, check its current Freight and verification state rather than relying on an image tag alone. section 3.2.2 section 3.5.7

If no Freight appears, run `kubectl describe warehouse demo-app -n demo` and inspect its conditions. Check whether registry tags match the selection rule; for a private registry, also check that the credentials Secret is in the Project namespace and has the required image-credential label. section 3.6.1

How Kargo in Action covers it

How deep it goes
Defines identity and creation, illustrates object fields, and follows promotion and verification; stops short of hand-authoring Freight.
Examples
Uses a generated Freight YAML object and an image promoted from dev through staging toward production.
What it assumes
Introduces Kargo’s resource relationships while assuming familiarity with Kubernetes namespaces and artifact registries.
What you can do after
Diagnose/debug with it by checking artifact identity, Stage verification, and Warehouse conditions when expected Freight is missing.
How it connects
Connects Warehouse discovery, Stage subscriptions, Promotion records, Project scope, GitOps, and Argo CD reconciliation.

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.