README
¶
Cargoship
Cargoship is a Go-based CLI for building, distributing, and applying offline Kubernetes distro packages. It is designed to simplify two core workflows:
- Package Creation: Building a self-contained, offline Kubernetes distro package containing everything needed for installation in disconnected or highly-regulated environments.
- 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, arm, 386, and riscv64. The archive names follow uname, so the one for a 64-bit Linux host is cargoship_Linux_x86_64.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, which install the binary along with 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 on Red Hat UBI |
ghcr.io/colonel-byte/cargoship-deb |
The binary installed from the .deb |
ghcr.io/colonel-byte/cargoship-ansible |
The binary plus the Ansible collection and ansible-core |
From source
Building needs Go 1.27 or newer. The repository vendors its dependencies, so a clone builds without network access:
go install github.com/colonel-byte/cargoship@latest
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
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) predictable, easier to debug, and simple to extend.
For example, the apply workflow comprises the following phases:
- Connect: Establish secure SSH connections to all target hosts.
- OS Detection & Fact Gathering: Identify host operating systems and system resources.
- Validation: Verify that host nodes meet the pre-requisites.
- Prepare: Install OS packages, load kernel modules, and configure system firewalls or policies.
- Upload: Securely transfer required package binaries, configuration templates, and OCI images to the nodes.
- Bootstrap / Upgrade: Initialize primary control-plane nodes and join worker nodes.
- Kubeconfig Retrieval: Fetch the generated admin credentials.
- Cleanup & Disconnect: Release locks, clean up temporary artifacts, and close SSH sessions.
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/
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
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
Ansible Integration
Cargoship also ships as an Ansible collection, colonel_byte.cargoship, so the workflows above run 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.
- Running Cargoship as an Ansible Module - the modules, their parameters, check mode, and what
changedmeans. - Generating an Inventory from Ansible - the group and host-variable translation, usable with or without the modules.
- The Ansible Container Image -
ghcr.io/colonel-byte/cargoship-ansible, which carries the binary and the collection together.
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.
The corresponding JSON schemas are automatically generated from Go structs into schema/. When authoring configurations in modern editors, refer to these schemas for real-time validation and autocompletion.
An inventory authoring guide is available in Setting up an inventory.
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/golang/*(Go package reference, from godoc comments)docs/schema/*(Schema field reference, from the same struct reflection asschema/*.json)docs/ansible/<collection>/module_*.mdanddocs/ansible/<collection>/role_*.md(Ansible collection reference)docs/index.mdanddocs/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 module files under ./cmd/zarf -- 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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api defines types shared across cargoship's API groups.
|
Package api defines types shared across cargoship's API groups. |
|
zarf.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. |
|
zarf.dev/v1alpha1/cluster
Package cluster defines the API types for a cluster configuration.
|
Package cluster defines the API types for a cluster configuration. |
|
zarf.dev/v1alpha1/distro
Package distro defines the API types for a distro package.
|
Package distro defines the API types for a distro package. |
|
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. |
|
terraform-provider-cargoship
command
Command terraform-provider-cargoship will be the OpenTofu provider that exposes cargoship as a cargoship_cluster resource: the configuration describes the fleet, cargoship owns the phase ordering, and a tofu apply converges the cluster.
|
Command terraform-provider-cargoship will be the OpenTofu provider that exposes cargoship as a cargoship_cluster resource: the configuration describes the fleet, cargoship owns the phase ordering, and a tofu apply converges the cluster. |
|
zarf/deploy
command
Command zarf_package_deploy answers Ansible as the zarf_package_deploy module.
|
Command zarf_package_deploy answers Ansible as the zarf_package_deploy module. |
|
zarf/init
command
Command zarf_init answers Ansible as the zarf_init module.
|
Command zarf_init answers Ansible as the zarf_init module. |
|
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 ZarfCluster document cargoship installs from.
|
Package ansibleinv translates an Ansible inventory into the ZarfCluster 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 ZarfDistro
|
Package cfg is used to parse an byte array and returns a ZarfDistro |
|
clustercfg
Package clustercfg is used to parse an byte array and returns a ZarfCluster
|
Package clustercfg is used to parse an byte array and returns a ZarfCluster |
|
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. |
|
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. |
|
split
Package split is a copy of the internal code from the zarf package
|
Package split is a copy of the internal code from the zarf package |
|
zarfmod
Package zarfmod lets a small wrapper binary answer Ansible as a zarf module.
|
Package zarfmod lets a small wrapper binary answer Ansible as a zarf module. |
|
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/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), Go package reference docs (golang.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), Go package reference docs (golang.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/gen/zarfflags
Package zarfflags records the flag surface of the zarf commands the Ansible modules wrap.
|
Package zarfflags records the flag surface of the zarf commands the Ansible modules wrap. |
|
pkg/release
Package release publishes release artifacts that goreleaser does not build.
|
Package release publishes release artifacts that goreleaser does not build. |
|
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. |
|
distro
Package distro is used for creating/deploying distro package
|
Package distro is used for creating/deploying distro package |
|
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. |
|
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. |
|
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/archive
Package archive implements the Archive interface for the OCI archive store.
|
Package archive implements the Archive interface for the OCI archive store. |
|
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/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 |
|
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. |
|
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 |
|
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. |
|
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 |