cargoship

command module
v0.42.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

README

Cargoship

Latest Release Go version Build Status OpenSSF Scorecard

Cargoship is a Go-based CLI for building, distributing, and applying offline Kubernetes distro packages. It is designed to simplify two core workflows:

  1. Package Creation: Building a self-contained, offline Kubernetes distro package containing everything needed for installation in disconnected or highly-regulated environments.
  2. Cluster Lifecycle Management: Bootstrapping, upgrading, and managing the cluster on target hosts over SSH using the packaged distribution.

Cargoship bridges the gap between offline distro packaging tools and remote cluster lifecycle managers, supporting OCI image and file packaging, secure publishing to OCI registries, and robust SSH orchestration.


Installation

Pre-built binaries

Every release publishes archives for Linux, macOS, and Windows across amd64, arm64, and riscv64. The name carries the OS and the architecture, with amd64 spelled the way uname -m does, so the one for a 64-bit Linux host is cargoship_Linux_x86_64.tar.gz and the arm64 one is cargoship_Linux_arm64.tar.gz:

VERSION=$(curl -fsSL https://api.github.com/repos/colonel-byte/cargoship/releases/latest | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4)
curl -fsSLO "https://github.com/colonel-byte/cargoship/releases/download/${VERSION}/cargoship_Linux_x86_64.tar.gz"
tar -xzf cargoship_Linux_x86_64.tar.gz cargoship
install -m 0755 cargoship /usr/local/bin/cargoship
Linux packages

Releases also carry .rpm, .deb, and .apk packages. Each installs the binary, shell completions for bash, fish and zsh, and the colonel_byte.cargoship Ansible collection onto ansible-core's default collection path:

sudo dnf install ./cargoship_*_linux_amd64.rpm    # or: sudo apt install ./cargoship_*_linux_amd64.deb
Container images
podman run --rm ghcr.io/colonel-byte/cargoship:latest version
Image Contents
ghcr.io/colonel-byte/cargoship The binary on a minimal base
ghcr.io/colonel-byte/cargoship-ubi The binary installed from the .rpm, on AlmaLinux 10
ghcr.io/colonel-byte/cargoship-deb The binary installed from the .deb, on Debian slim
ghcr.io/colonel-byte/cargoship-ansible The .rpm plus ansible-core, on AlmaLinux 10

The -ubi name is historical: that image was based on Red Hat UBI and is now built on AlmaLinux 10, but the published image name has not changed.

From source

Building needs Go 1.27 or newer.

go install github.com/colonel-byte/cargoship@latest

That reaches the network for the module. To build without it, clone the repository instead: the vendor/ tree is committed, so a clone builds with no network access at all, which is how a management node inside an airlock is staged.

git clone https://github.com/colonel-byte/cargoship.git && cd cargoship
mage build:binary    # or: go run ./magefiles/core build:binary
Verifying a download

Release archives and container images are signed with Cosign, using the key published at cosign.pub. Each archive ships a .sigstore.json bundle beside it, and every release carries a checksums.txt:

cosign verify-blob --key cosign.pub --bundle cargoship_Linux_x86_64.tar.gz.sigstore.json cargoship_Linux_x86_64.tar.gz
cosign verify --key cosign.pub ghcr.io/colonel-byte/cargoship:latest

Supported Distributions

Cargoship currently provides native support and integration for the following Kubernetes engines:

  • K3s
  • RKE2
  • Upstream Kubernetes (kubeadm) - installs the pkgs.k8s.io packages and containerd, and applies a CNI the package declares

Core Concepts

Cargoship is built around two primary architectural concepts:

1. Offline Distro Packages

A Cargoship package is a single, compressed archive containing all artifacts necessary to spin up or upgrade a Kubernetes cluster in air-gapped networks. It bundles:

  • Distro-specific metadata and layout descriptors.
  • Required engine configuration templates and system files.
  • OCI images and container artifacts.
  • Checksums and cryptographic signatures for integrity verification.

The package compilation process loads a local distro definition, gathers all specified assets, and produces a single, verifiable archive.

2. Phase-Based Orchestration

Cluster operations are modeled as ordered sequences of reusable, structured "phases." This makes high-level actions (apply, prepare, reset, kube-config, engine-config-sync) predictable, easier to debug, and simple to extend.

For example, the apply workflow runs these phases, in this order:

  1. Connect: Establish secure SSH connections to all target hosts.
  2. OS Detection & Fact Gathering: Identify host operating systems, network facts, and the engine version already installed.
  3. Validation: Verify that host nodes meet the prerequisites, and stop if the cluster holds a node the config does not.
  4. Lock: Take an exclusive host lock, held for the rest of the run, so a second cargoship cannot change the same hosts.
  5. Prepare: Install OS packages, configure sysctl and environment, SELinux and fapolicyd rules, /etc/hosts, and the node firewall.
  6. Upload: Securely transfer package binaries, RPMs or DEBs, configuration templates, and OCI images to the nodes, then import the images. Image tarballs the package no longer carries are removed from the nodes in the same pass -- see Image Tarballs on a Node.
  7. Bootstrap / Upgrade: Render the engine config, initialize control-plane nodes, apply bundled manifests, join workers, and upgrade any node already running an older version.
  8. Engine Config Sync: Reconcile registry, audit, and pod-security config on any node whose config drifted.
  9. Kubeconfig Retrieval and Labelling: Fetch the generated admin credentials and label nodes with their profile group.
  10. Cleanup & Disconnect: Release the lock, clean up temporary artifacts, and close SSH sessions.

The generated reference in docs/phases/ is the authoritative list, including what each phase does under --dry-run.


Usage Examples

Here are the standard workflows for compiling and deploying offline Kubernetes packages with Cargoship.

The commands that change a host - prepare, apply, reset, and engine-config-sync - will not do so without --confirm. Swap it for --dry-run to connect to every host and run the preflight checks for real, reporting what the run would change without changing it.

1. Compile an Offline Package

To build an offline archive containing all required files, binaries, and container images:

# Create a package from the current directory structure
cargoship create .

# Build from a specific path and output to a custom directory
cargoship create ./distro-defs -o ./build/

A build normally fetches the images and files a definition declares from the registries and URLs it names. Where that content has already been collected with hauler or zarf and carried across the airlock, point the build at that store instead and nothing is fetched:

# A hauler store directory, or an archive written by `hauler store save`
cargoship create ./distro-defs --content-store ./haul.tar.zst

# A built zarf package
cargoship create ./distro-defs --content-store ./zarf-package-rke2-content-amd64.tar.zst

Which format the store is comes from what it holds, not from what it is called. Images and files are matched against the reference each tool recorded for the artifact when it was collected, so no mapping has to be written by hand. Anything the store does not hold still comes from its declared source, which makes a partial store usable. A zarf package covers one architecture, so pass --architecture when building a multi-architecture definition from one. The same setting lives in the config file:

distro:
  create:
    content_store: ~/hauls/haul.tar.zst

See Building From a Local Content Store for the collect-and-carry workflow, what each format must contain, and how this compares with --registry-override and --file-override.

Where the build host can reach a registry, a file can also name an OCI reference directly, which is how a growing number of vendors publish air-gapped engine bundles. The entry says which layer it wants and selector.arch supplies the platform, so one tag covering several architectures resolves per entry:

spec:
  config:
    os:
      files:
        # one tarball per platform, published as a single titled layer
        - source: oci://registry.example.com/vendor/engine:v1.37.1
          extractPath: bin/engine
          target: /usr/local/bin/engine
          executable: true
          selector:
            arch:
              - amd64

        # every file in the release as its own titled layer
        - source: oci://ghcr.io/cri-o/bundle:d816c7e
          layer: cri-o/bin/crio
          target: /usr/local/bin/crio
          executable: true
          selector:
            arch:
              - amd64

--registry-override redirects these the way it redirects an image pull. See Declaring a File From an OCI Registry.

A build caches what it fetches under ~/.cache/cargoship, so a rebuild of the same definition reaches the network for little or nothing. Nothing expires that cache -- it has no size limit and grows for as long as definitions name new versions -- so clean-cache is what reclaims it:

# report every area with its size and what would go, removing nothing
cargoship dev clean-cache --dry-run

# keep anything fetched in the last fortnight, drop the rest
cargoship dev clean-cache --older-than 336h

# remove every fetchable area
cargoship dev clean-cache

Run logs and the local dev fleet's images are never removed, and neither is an area this version does not recognise. An age window cannot prune the image layout, which is an index over shared blobs; it is reported as skipped and comes out whole when --older-than is omitted.

2. Prepare Target Nodes

Verify and configure OS-level prerequisites (such as kernel modules, firewall ports, fapolicyd rules, and /etc/hosts) across target machines using your cluster configuration inventory:

cargoship prepare ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm
3. Deploy or Upgrade a Cluster

Bootstrap a new cluster or upgrade an existing one from the compiled package:

cargoship apply ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm

An apply reconciles the node's image directory as well as filling it: a tarball the package has stopped carrying -- including the older tag of an image a version bump replaced -- is deleted from every node, and so is a tarball sitting there that no cargoship run recorded. On a node where something other than cargoship also stages images, keep those by creating a marker file in the image directory, which leaves the package's own images reconciled as normal:

# on the node: keep image tarballs cargoship did not upload, and warn about them every run
sudo touch /var/lib/rancher/k3s/agent/images/cargoship-keep-images

Image Tarballs on a Node covers the naming, both cleanups, and how a kept file is reported.

4. Fetch the Kubeconfig

Retrieve the admin kubeconfig securely from the primary controller:

cargoship kube-config --config ./cargoship-config.yaml
5. Uninstall or Reset Target Nodes

Stop, uninstall, and completely purge the Kubernetes distro and its state from the target hosts:

cargoship reset --config ./cargoship-config.yaml --distro rke2 --confirm
6. Generate an Inventory from Ansible

Translate an Ansible inventory you already maintain into a cargoship cluster inventory, taking each host's role from its Ansible groups:

cargoship inventory from-ansible ./resolved.json -o ./inventory.yaml
7. Publish, Pull, Sign, and Verify a Package

A package can live in an OCI registry rather than on a disk, and every command that takes a package takes an oci:// reference wherever it takes a path:

# Push a built package to a registry
cargoship publish ./build/cargoship-distro-amd64.tar.zst oci://ghcr.io/my-org

# Pull one back down to a local directory
cargoship pull oci://ghcr.io/my-org/my-package:1.0.0 -o ./build/

# Sign a package with a private key
cargoship sign ./build/cargoship-distro-amd64.tar.zst --signing-key ./private-key.pem

# Verify the signature before anything installs from it
cargoship verify ./build/cargoship-distro-amd64.tar.zst --key ./cosign.pub

An operator who cannot reach the registry from the management node moves the package across the airlock with Skopeo instead, then converts the resulting OCI archive into a native package:

# On the connected side: export the package as an OCI archive
skopeo copy --override-os multi docker://ghcr.io/my-org/my-package:1.0.0 oci-archive:my-package.tar:1.0.0

# On the disconnected side: convert it into a package apply can install
cargoship import ./my-package.tar -o ./build/

import reads an OCI Image Layout, as a .tar or as an unpacked directory; see Importing Archives for the other tools that write one, and why a docker-archive cannot carry a package.

A cosign keypair is the only signing method - keyless (Fulcio/OIDC) signing and verification were removed, because they need network the management node does not have; see #848. The commands that load a package - apply, prepare, engine-config-sync, publish, pull, import, validate, schema - verify as part of loading, gated on --verify=never|if-possible|always. verify does nothing but check the signature, which is what makes it the one to run before a playbook.

8. Mirror a Package's Contents into a Registry

publish uploads a package as one artifact, to be pulled back as a package. mirror does the opposite: it unpacks what the package carries into a registry as individually pullable content, so the mirror a fleet already pulls through holds what its nodes will ask for.

# Push every image and file the package carries into a registry
cargoship mirror ./build/cargoship-distro-amd64.tar.zst oci://harbor.internal

# Under a repository prefix, which most hosted registries require
cargoship mirror ./build/cargoship-distro-amd64.tar.zst oci://harbor.internal/cargoship

# Or read the destination from the registry proxy the cluster config already declares
cargoship mirror ./build/cargoship-distro-amd64.tar.zst --config ./cluster.yaml

# Only the images, against a registry on plain HTTP
cargoship mirror ./build/cargoship-distro-amd64.tar.zst oci://registry.internal:5000 --images --plain-http

# Or into a Zarf deployment's in-cluster registry, tunnelled over SSH to a node
cargoship mirror ./build/cargoship-distro-amd64.tar.zst --from-zarf-state --config ./cluster.yaml

# Or both halves at once: the content a node pulls, and the package a consumer installs from
cargoship mirror ./build/cargoship-distro-amd64.tar.zst oci://harbor.internal --publish

# Then ask a registry which packages have been mirrored into it
cargoship ls oci://harbor.internal
cargoship ls --from-zarf-state --config ./cluster.yaml -o json

An image keeps its repository path and its tag, and only the registry host changes: registry.k8s.io/pause:3.10 is pushed as harbor.internal/pause:3.10. That is not cosmetic - it is exactly what a node asks a mirror for, because apply writes that same proxy address into each host's containerd configuration from spec.config.registries[].proxy.url. Passing --config reads the destination from that one field, so what gets pushed and what the nodes ask for cannot drift apart.

--from-zarf-state reads the destination registry and its push credentials from a Zarf deployment's own state secret, over --context or the current kubeconfig context. Zarf's in-cluster registry sits at an address only a node can reach, so add --config and one SSH channel to a controller carries both the state read and the push - port 22 is the only port needed, and the kubeconfig supplies identity rather than reachability. Where the nodes have no sshd at all - k3d, kind, Talos - --via-kube carries the push through the API server's port-forward instead, needing nothing but the kubeconfig, and implying --from-zarf-state so it is the only flag needed. Naming an oci:// address this machine reaches works too, with the credentials still coming from state.

# Mirror into a development cluster that has no SSH
cargoship mirror ./build/cargoship-distro-amd64.tar.zst --via-kube

# Publish with a record, then resolve the newest version from anywhere
cargoship publish ./build/cargoship-distro-amd64.tar.zst oci://ghcr.io/colonel-byte --record
cargoship ls oci://ghcr.io/colonel-byte --name rancher-rke2-multi-cni-cilium -o json

A finished mirror records which package filled it, as a few kilobytes at cargoship:_mirror.NAME.VERSION, and ls reads those records back. Two versions of one package are listed side by side, because the record's tag carries the version - that is a registry's property, not a cluster's. --name lists one package without needing a credential allowed to read the registry's catalogue.

--publish writes the package itself as well, through the same transport and credentials the mirror used, leaving cargoship:_package.NAME.VERSION beside the mirror's own record. Reach for it where something downstream has to install from this registry rather than pull images through it: a mirror alone holds everything a node asks for at runtime and no artifact to install from, which is the shape cluster-api-provider-cargoship reports as "recorded as mirrored into this registry but not published into it".

See Mirroring to a Registry for the naming rules, what a record holds, and how this compares with --registry-override and --content-store.

9. Encrypt Credentials in a Config File

Registry credentials in a cluster inventory are encrypted at rest, with Ansible Vault or with age. The vault command group covers both:

# Encrypt one value for a registry's user/pass/token field
cargoship vault encrypt my-registry-password --vault-password-file ./vault-pass.txt

# Encrypt or decrypt every registry credential in a config file, in place
cargoship vault encrypt-file ./cargoship-config.yaml --vault-password-file ./vault-pass.txt
cargoship vault decrypt-file ./cargoship-config.yaml --vault-password-file ./vault-pass.txt

# Encrypt the values already sitting at given YAML paths, naming each one
cargoship vault encrypt-path ./cargoship-config.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./vault-pass.txt

# Generate an age key pair, and re-wrap an existing file under a new key
cargoship vault keygen
cargoship vault rekey ./cargoship-config.yaml --new-vault-password-file ./new-pass.txt

encrypt-path only encrypts; cargoship decrypts a registry's auth.user, auth.pass, auth.token and tls.ca at apply time, and warns when asked to encrypt a path outside that set. decrypt, decrypt-path, decrypt-file and encrypt-file complete the set; cargoship vault --help lists all eight.

10. Validate a File, or Write Its Schema
# Check an inventory or package definition against its schema; the kind is read from the document
cargoship validate ./cluster.yaml

# A config file declares no kind, so name the schema for it
cargoship validate --kind config ./cargoship-config.yaml

# Write the JSON Schema for one of cargoship's own file formats: inventory, package, or config
cargoship schema inventory -o ./inventory.schema.json

# Checksum a file, or one file inside an archive
cargoship dev sha256sum ./build/cargoship-distro-amd64.tar.zst
11. Record a Run for Audit
# Write a structured record of the run: what ran, against which package, against which fleet,
# and what changed. Written whether the run succeeds or fails, readable only by its owner.
cargoship apply ./build/cargoship-distro-amd64.tar.zst \
  --config ./cluster.yaml --confirm \
  --receipt-path /var/log/cargoship/receipts/apply-20260928-143000.json

# Strip everything that identifies the fleet, ready to attach to a bug report
cargoship dev redact-receipt ./receipt.json -o ./share.json

The receipt carries the invocation and the cargoship that ran it, the package's digests and signature status, the cluster inventory, the phase-by-phase ledger with per-host change reasons and diffs, and any warnings the run raised under outcome.warnings -- a successful run that left something on a host worth looking at says so there. redact-receipt renumbers the hosts host-01, host-02, drops the diff bodies -- an engine configuration diff carries join tokens -- and removes the cluster name, operator and command line, leaving what a maintainer triages from.

A fleet that keeps an audit trail sets the path once in the config file instead, under .distro.receipt_path, where apply, prepare, reset and engine-config-sync all pick it up:

distro:
  # {command} and {timestamp} expand per run, so each receipt lands in its own file
  receipt_path: /var/log/cargoship/receipts/{command}-{timestamp}.json

Those two placeholders are the only ones accepted; anything else is rejected before the run starts, rather than written out literally. --receipt-path overrides the configured value and takes the same placeholders.

12. Iterate on a Definition While Authoring It

Editing a distro.yaml normally costs a build and a separate install, and the artifact between them is most of the wait: a package is compressed on the way out of create and decompressed again on the way into apply, over bytes that never leave the machine. dev apply does both halves in one process and leaves the artifact out:

# build the definition and run the apply phases against it, with no package written
cargoship dev apply ./distro-defs --config ./cargoship-config.yaml --confirm

Everything after the build is the same code apply runs -- values resolution, engine-configuration mapping and template rendering -- so what reaches the hosts is what the built package would have put there. It takes the build-side flags that change what gets built, so a loop can still resolve content locally:

cargoship dev apply ./distro-defs --config ./cargoship-config.yaml \
  --content-store ./haul.tar.zst --confirm

The build still fetches what the definition declares, and still serves it from the shared cache when it is already there, so a second run after an edit usually reaches the network for nothing new. That cache is what Compile an Offline Package describes reclaiming with clean-cache.

This is for a definition under active edit, not for shipping. It writes no artifact to carry, keep, or sign, and it does not verify a signature -- there is nothing to verify, because the package was built by the same process a moment earlier. A release still goes through create, sign and apply. See Authoring a Distro Package for the whole loop and what the build caches between runs.

13. Generate Definitions from a Template

A fleet's package definitions usually differ in a handful of values -- a version, an architecture, a CNI -- and are otherwise the same file. dev render keeps them as one template plus a small values file per package, which is how cargoship's own examples under example/ are generated:

# render a definition from a template and an input file
cargoship dev render --template ./distro.yaml.tmpl --values ./v1.36.4.yaml --out ./packages/v1.36.4

# render a definition and the values file beside it together, merging a common input first
cargoship dev render -t ./distro.yaml.tmpl -t ./values.yaml.tmpl \
  -f ./common.yaml -f ./v1.36.4.yaml -o ./packages/v1.36.4

Each --template is written to --out under its own name with .tmpl dropped, and every template renders against the same merged values, so a value that has to agree between a definition and the values beside it is written once. The template functions are the ones a package's own values templates get -- the sprig set, minus the functions that read host state -- and a value path that resolves to nothing is an error rather than a placeholder in the output.

A rendered distro.yaml is checked against the package schema before anything is written, so a definition that renders but cannot be built is reported here rather than by create. cargoship create ./packages/v1.36.4 is the next step.

See Generating Definitions From a Template for the values-merge order, which template functions are available and which are deliberately not, and how to emit build-time {{ .Values.x }} expressions into the definition.


OpenTofu and Terraform

The same phases run from a declarative configuration through the OpenTofu provider, which lives in colonel-byte/terraform-provider-cargoship and consumes this repository as a library: cargoship_cluster converges a cluster -- install, join and upgrade are one apply, because the engine version already on each host is what tells them apart -- and cargoship_cluster_facts reads a fleet without changing it. It drives cargoship in process, so it still opens every SSH connection itself from the machine OpenTofu runs on.

It grew up here and moved out, so that it could be published under the name the provider registry requires; nothing in cargoship depends on it. See choice-tofu-provider-removal for what moved and what stayed.


Ansible Integration

colonel_byte.cargoship runs the workflows above as ordinary playbook tasks: cargoship_apply, cargoship_prepare, cargoship_reset, cargoship_kube_config, and cargoship_engine_config_sync, plus a cluster role that wraps them. Ansible supplies the inventory and runs one task for the whole fleet; cargoship still opens every SSH connection itself, from the management node the package was staged onto.

For driving zarf itself from a playbook, the colonel_byte.zarf collection lives in colonel-byte/ansible-collection-zarf. It grew up here and moved out; nothing in cargoship depends on it.


Configuration and Schemas

Cargoship relies on strongly-typed YAML definitions to govern its operations:

  • Cluster Inventories: Specify SSH configurations, credentials, host roles, profiles, and load-balancer addresses.
  • Distro Package Definitions: Map out the required binaries, OCI images, and layout settings.
  • Distro Runtime Configs: Configure the underlying distribution engine.

Inventories and package definitions are Kubernetes-style documents under cargoship's own API group:

apiVersion: colonel-byte.dev/v1alpha1
kind: Cluster      # or Distro, for a package definition
metadata:
  name: fleet-cluster

The corresponding JSON schemas are automatically generated from Go structs into schema/, and cargoship schema writes any of them on demand. When authoring configurations in modern editors, refer to these schemas for real-time validation and autocompletion; cargoship validate checks a file against the right one without an editor.

An inventory authoring guide is available in Setting up an inventory, and the full set of guides -- image tarballs, file and registry overrides, credential encryption, multi-architecture packages, firewalls -- is under docs/guides/.

The zarf.dev group is deprecated

These documents used to declare apiVersion: zarf.dev/v1alpha1 with kind: ZarfCluster and kind: ZarfDistro. That group belongs to the upstream Zarf project, which defines its own kinds under it, so cargoship moved to a group it owns.

Both spellings are accepted, in any combination, and a document using the old one needs no change today:

Old New
API group zarf.dev/v1alpha1 colonel-byte.dev/v1alpha1
Inventory kind ZarfCluster Cluster
Package kind ZarfDistro Distro

Everything cargoship writes itself - cargoship inventory from-ansible, the Ansible collection, the OpenTofu provider, the generated example packages - now emits the new spelling. No removal date is set for the old one; when one is, it will be announced in a release before it lands.


Exit Codes

Cargoship is usually driven from a script on the management node, so a failure needs to say what kind of failure it was. Every command uses the same codes:

Code Meaning Worth retrying?
0 Success --
1 A failure that is none of the below - a phase that ran and did not finish, an unrecognised command Not on its own; read the error
2 The invocation is wrong: an unknown flag, a bad flag value, the wrong number of arguments No - the command line needs fixing
3 A file cargoship was pointed at is invalid: it fails its schema, or a config file has an undefined key No - the file needs fixing
4 A host-changing command was run without --confirm. Nothing was touched Yes, with --confirm or --dry-run
5 The fleet could not be reached or would not accept the credentials. No phase did any work Yes - this is the one safe to retry unattended
130 Interrupted with SIGINT, following the conventional 128 + signal Yes

5 is the code worth branching on. It means cargoship stopped at the connection, so nothing on any host changed and a retry starts from the same state - unlike 1, which can mean a run stopped partway through and left a fleet mid-upgrade.

cargoship apply ./build/cargoship-distro-amd64.tar.zst --config ./cluster.yaml --confirm
case $? in
  0) ;;                                        # done
  5) echo "fleet unreachable, will retry" ;;   # safe to run again unattended
  4) echo "refusing to change hosts without --confirm" ;;
  *) echo "failed; read the receipt before retrying" ;;
esac

These numbers are a compatibility promise. A new classification gets a new code; an existing one is not repurposed.


Development and Build Workflows

Task automation is built using Mage, which drives builds, tests and code generation with the host Go toolchain.

Mage Automation

Mage handles tasks including local compilation, e2e test execution, schema updates, and documentation generation. Key generated files include:

  • build/cargoship_* (Release binaries)
  • docs/commands/* (Cobra command references)
  • docs/phases/* (Orchestration phase explanations)
  • docs/schema/* (Schema field reference, from the same struct reflection as schema/*.json)
  • docs/ansible/<collection>/module_*.md and docs/ansible/<collection>/role_*.md (Ansible collection reference)
  • docs/index.md and docs/security.md (this file and .github/SECURITY.md, with their links rewritten for the book)
  • docs/SUMMARY.md (mdBook layout manifest)
  • schema/*.json (YAML validations)
Continuous Integration (CI) and Releases

GitHub Actions workflows run lint checks, dependency validation, cross-compilation, and end-to-end tests for every pull request. Releases are managed through GoReleaser, automating build signing, verification, and asset publishing.


Inspiration

Cargoship draws major design and engineering inspiration from:

  • k0sproject/k0sctl - For elegant SSH-based multi-node orchestration and configuration patterns.
  • zarf-dev/zarf - For air-gapped image and file packaging and offline-first design.

Documentation

Overview

Package main is the development entry point for the cargoship CLI, so that `go run . <command>` keeps working from a checkout.

The released binary is built from ./cmd/cargoship, and that is the one every artifact comes from: .goreleaser.yaml, magefiles/pkg/build.Binary, the container images, and the e2e suites all name it. The repository builds more than one binary now -- the cargoship CLI and the zarf Ansible -- and Go allows one main package per directory, so the released entry point moved into a directory of its own rather than staying at the root.

This file is a convenience, not a second product. It runs the same command tree against the same configurers; what it deliberately leaves out is the Ansible module dispatch that ./cmd/cargoship/main.go runs before Cobra:

  • A module is selected by the name the binary was invoked under -- a cargoship_<action> symlink to the installed binary. `go run .` compiles to a temporary file named after this package, so it can never carry such a name, and the branch would be unreachable here.
  • The CARGOSHIP_ANSIBLE_MODULE environment variable does select a module without a symlink, and that is the path to reproduce a module run by hand. It has no effect through this entry point. Use `go run ./cmd/cargoship` for that, or the built binary.

See the package documentation of internal/ansiblemod and docs/agent/choice-ansible-module.md for what the module path does, and cmd/ansible.go for where it is entered.

Directories

Path Synopsis
api
Package api defines types shared across cargoship's API groups.
Package api defines types shared across cargoship's API groups.
colonel-byte.dev/v1alpha1
Package v1alpha1 defines file types shared by the cluster and distro APIs.
Package v1alpha1 defines file types shared by the cluster and distro APIs.
colonel-byte.dev/v1alpha1/cluster
Package cluster defines the API types for a cluster configuration.
Package cluster defines the API types for a cluster configuration.
colonel-byte.dev/v1alpha1/distro
Package distro defines the API types for a distro package.
Package distro defines the API types for a distro package.
cmd
Package cmd is where the commands for cargoship
Package cmd is where the commands for cargoship
cargoship command
Package main is the entry point for the cargoship binary
Package main is the entry point for the cargoship binary
flags
Package flags provides shell completion functions for cargoship CLI flags.
Package flags provides shell completion functions for cargoship CLI flags.
Package config is a holder of commonly used multiple times
Package config is a holder of commonly used multiple times
lang
Package lang holds the cli helping text
Package lang holds the cli helping text
internal
ansibleinv
Package ansibleinv translates an Ansible inventory into the Cluster document cargoship installs from.
Package ansibleinv translates an Ansible inventory into the Cluster document cargoship installs from.
ansiblemod
Package ansiblemod lets the cargoship binary answer Ansible as a module.
Package ansiblemod lets the cargoship binary answer Ansible as a module.
cfg
Package cfg is used to parse an byte array and returns a Distro
Package cfg is used to parse an byte array and returns a Distro
clustercfg
Package clustercfg holds the age/vault key material and the encrypt, decrypt and rekey operations over a cluster configuration document.
Package clustercfg holds the age/vault key material and the encrypt, decrypt and rekey operations over a cluster configuration document.
dns
Package dns contains DNS related functionality.
Package dns contains DNS related functionality.
heartbeat
Package heartbeat writes live phase execution progress to a status file on disk so long-running operations (such as Ansible modules) can be monitored externally in real-time.
Package heartbeat writes live phase execution progress to a status file on disk so long-running operations (such as Ansible modules) can be monitored externally in real-time.
logging
Package logging provides an slog.Handler that fans a record out to several handlers, each with its own independent level filter.
Package logging provides an slog.Handler that fans a record out to several handlers, each with its own independent level filter.
receipt
Package receipt builds the structured record of one cargoship run.
Package receipt builds the structured record of one cargoship run.
magefiles
core command
pkg/build
Package build handles compiling cargoship binaries with appropriate compiler and linker flags.
Package build handles compiling cargoship binaries with appropriate compiler and linker flags.
pkg/devtools/dnfpins
Package dnfpins queries AlmaLinux 10 repodata over HTTP and updates package pins across Dockerfiles and .goreleaser.yaml.
Package dnfpins queries AlmaLinux 10 repodata over HTTP and updates package pins across Dockerfiles and .goreleaser.yaml.
pkg/devtools/microvmrun
Package microvmrun is the presentation half of the Dev VM targets: it drives test/microvm and formats what that package returns for a terminal.
Package microvmrun is the presentation half of the Dev VM targets: it drives test/microvm and formats what that package returns for a terminal.
pkg/devtools/osv
Package osv manages osv-scanner.toml overrides in vendor/ to prevent non-Go manifests from degrading OpenSSF Scorecard Vulnerability checks.
Package osv manages osv-scanner.toml overrides in vendor/ to prevent non-Go manifests from degrading OpenSSF Scorecard Vulnerability checks.
pkg/gen/completion
Package completion generates the shell completion scripts under hack/completion.
Package completion generates the shell completion scripts under hack/completion.
pkg/gen/docs
Package docs runs every generator the book is built from: the pages (this file), phase docs (phase.go), Ansible collection reference docs (ansible.go), and the two pages copied in from outside docs/ (book.go).
Package docs runs every generator the book is built from: the pages (this file), phase docs (phase.go), Ansible collection reference docs (ansible.go), and the two pages copied in from outside docs/ (book.go).
pkg/gen/engineconfig
Package engineconfig manages upstream k3s/RKE2 source pins, source pulls, and config struct codegen.
Package engineconfig manages upstream k3s/RKE2 source pins, source pulls, and config struct codegen.
pkg/gen/examples
Package examples renders the example distro.yaml packages under example/ from the shared templates, one per distro flavor and release tag.
Package examples renders the example distro.yaml packages under example/ from the shared templates, one per distro flavor and release tag.
pkg/gen/schema
Package schema generates and renders JSON schemas from Go API types.
Package schema generates and renders JSON schemas from Go API types.
pkg/testrunner
Package testrunner implements runners for end-to-end and fuzz test suites.
Package testrunner implements runners for end-to-end and fuzz test suites.
pkg/util
Package util provides general filesystem, git, markdown, and execution helpers for magefiles.
Package util provides general filesystem, git, markdown, and execution helpers for magefiles.
pkg
action
Package action are various actions used by the package
Package action are various actions used by the package
coci
Package coci contains functions for interacting with Cargoship packages stored in OCI registries, derived from github.com/zarf-dev/src/pkg/zoci.
Package coci contains functions for interacting with Cargoship packages stored in OCI registries, derived from github.com/zarf-dev/src/pkg/zoci.
coci/layers
Package layers contains functions for interacting with Cargoship layers stored in OCI registries, derived from github.com/zarf-dev/src/pkg/zoci.
Package layers contains functions for interacting with Cargoship layers stored in OCI registries, derived from github.com/zarf-dev/src/pkg/zoci.
contentstore
Package contentstore holds the pieces shared by the readers of a local content bundle -- a hauler store, a zarf package -- so that two readers of the same OCI layout cannot drift apart in how they open it or how they key an image reference.
Package contentstore holds the pieces shared by the readers of a local content bundle -- a hauler store, a zarf package -- so that two readers of the same OCI layout cannot drift apart in how they open it or how they key an image reference.
distro
Package distro is used for creating/deploying distro package
Package distro is used for creating/deploying distro package
distrogen
Package distrogen renders package definitions - a distro.yaml and whatever files sit beside it - from Go templates.
Package distrogen renders package definitions - a distro.yaml and whatever files sit beside it - from Go templates.
engineconfig/extract
Package extract statically parses k3s/RKE2's pkg/cli/cmds source (via go/ast) to recover the urfave/cli flag list they declare, without ever compiling or importing that package.
Package extract statically parses k3s/RKE2's pkg/cli/cmds source (via go/ast) to recover the urfave/cli flag list they declare, without ever compiling or importing that package.
engineconfig/gen
Package gen turns an extract.Manifest into a Go struct source file: one field per resolved, non-alias flag, tagged with the flag's real kebab-case name as its yaml key.
Package gen turns an extract.Manifest into a Go struct source file: one field per resolved, non-alias flag, tagged with the flag's real kebab-case name as its yaml key.
fileoverride
Package fileoverride redirects the file downloads a distro definition declares to an internal mirror or to a directory of pre-staged assets, the way images.RegistryOverride redirects image pulls.
Package fileoverride redirects the file downloads a distro definition declares to an internal mirror or to a directory of pre-staged assets, the way images.RegistryOverride redirects image pulls.
firewall
Package firewall renders cargoship's backend-neutral firewall configuration onto whichever host firewall a node runs.
Package firewall renders cargoship's backend-neutral firewall configuration onto whichever host firewall a node runs.
haulerstore
Package haulerstore reads a hauler store (https://github.com/hauler-dev/hauler) as a source of images and files for a package build.
Package haulerstore reads a hauler store (https://github.com/hauler-dev/hauler) as a source of images and files for a package build.
helmvalues
Package helmvalues renders Helm-style value templates and reads and writes the nested interface values those templates draw on.
Package helmvalues renders Helm-style value templates and reads and writes the nested interface values those templates draw on.
helpers
Package helpers are a sub-section of function from defense-unicorn pkg helpers package
Package helpers are a sub-section of function from defense-unicorn pkg helpers package
images
Package images is functionality related to interacting with oci images.
Package images is functionality related to interacting with oci images.
kubetunnel
Package kubetunnel reaches a service inside a cluster through the Kubernetes API server's port-forward subresource.
Package kubetunnel reaches a service inside a cluster through the Kubernetes API server's port-forward subresource.
lint
Package lint contains functions for verifying yaml files are valid
Package lint contains functions for verifying yaml files are valid
node
Package node is used for status related functions
Package node is used for status related functions
oci/platform
Package platform defines canonical CPU architecture identifiers and validation helpers used by cargoship when targeting specific platforms in OCI workflows.
Package platform defines canonical CPU architecture identifiers and validation helpers used by cargoship when targeting specific platforms in OCI workflows.
packager/actions
Package actions runs the onCreate actions in a distro package.
Package actions runs the onCreate actions in a distro package.
packager/assemble
Package assemble builds a Cargoship package on disk
Package assemble builds a Cargoship package on disk
packager/layout
Package layout is used to defining the distro package files
Package layout is used to defining the distro package files
packager/load
Package load for loading a given package
Package load for loading a given package
phase
Package phase is all the various phases used for bootstrapping a cluster.
Package phase is all the various phases used for bootstrapping a cluster.
retry
Package retry provides simple retry wrappers for functions that return an error
Package retry provides simple retry wrappers for functions that return an error
riglogger
Package riglogger bridges cargoship's context-scoped logger into rig v2's slog-based logging.
Package riglogger bridges cargoship's context-scoped logger into rig v2's slog-based logging.
schema
Package schema serves the JSON Schema documents cargoship generates for its own file formats, out of the binary rather than over the network.
Package schema serves the JSON Schema documents cargoship generates for its own file formats, out of the binary rather than over the network.
signing
Package signing provides cosign-compatible signing and verification for cargoship packages, against an ordinary cosign keypair.
Package signing provides cosign-compatible signing and verification for cargoship packages, against an ordinary cosign keypair.
tunnel
Package tunnel reaches a service inside a cluster over an SSH connection to one of its nodes.
Package tunnel reaches a service inside a cluster over an SSH connection to one of its nodes.
utils
Package utils is for commonly used functions.
Package utils is for commonly used functions.
utils/build
Package build is the build flag logic shared across mage and the CLI
Package build is the build flag logic shared across mage and the CLI
zarfpackage
Package zarfpackage reads a built zarf package (https://github.com/zarf-dev/zarf) as a source of images and files for a package build.
Package zarfpackage reads a built zarf package (https://github.com/zarf-dev/zarf) as a source of images and files for a package build.
zarfstate
Package zarfstate reads the registry half of a Zarf deployment's state secret, so that a mirror can be pointed at a registry Zarf already stands up and authenticate against it with the credentials Zarf already generated.
Package zarfstate reads the registry half of a Zarf deployment's state secret, so that a mirror can be pointed at a registry Zarf already stands up and authenticate against it with the credentials Zarf already generated.
Package test provides e2e tests for Cargoship
Package test provides e2e tests for Cargoship
e2e/cluster
Package cluster holds the e2e tests that need a real multi-node cluster: the install command group, driven against containers provisioned by bootloose.
Package cluster holds the e2e tests that need a real multi-node cluster: the install command group, driven against containers provisioned by bootloose.
microvm
Package microvm brings a fleet of Enterprise Linux virtual machines up and down on the developer's own machine, under plain qemu, and renders a Cluster inventory pointing at them.
Package microvm brings a fleet of Enterprise Linux virtual machines up and down on the developer's own machine, under plain qemu, and renders a Cluster inventory pointing at them.
Package types is a little bit of a hacky way to generate the cargo-ship-config jsonschema
Package types is a little bit of a hacky way to generate the cargo-ship-config jsonschema
distrocfg
Package distrocfg defines the standard interface that all distro config settings
Package distrocfg defines the standard interface that all distro config settings
distrocfg/registry
Package registry is used to register a distro
Package registry is used to register a distro
os
Package os is for running commands on a remote host
Package os is for running commands on a remote host
os/linux
Package linux is implementing the interface github.com/colonel-byte/cargoship/types/os.Configurer for Linux based hosts
Package linux is implementing the interface github.com/colonel-byte/cargoship/types/os.Configurer for Linux based hosts
os/linux/enterpriselinux
Package enterpriselinux is implementing the interface github.com/colonel-byte/cargoship/types/os.Configurer for Enterprise Linux hosts
Package enterpriselinux is implementing the interface github.com/colonel-byte/cargoship/types/os.Configurer for Enterprise Linux hosts

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL