README
¶
Cargoship
Cargoship is a Go-based CLI for building, distributing, and applying offline Kubernetes distro packages.
It is designed for two main jobs:
- create an offline Kubernetes distro package
- bootstrap and manage a cluster from that package over SSH
Cargoship combines ideas from distro packaging tools and remote cluster lifecycle tools, with support for packaging files and OCI images, publishing packages to registries, and applying them to target hosts.
What Cargoship does
Cargoship supports the full lifecycle of an offline distro package:
- create a distro package from a definition directory
- publish a package to an OCI registry
- pull a package from a registry or URL
- prepare hosts before installation
- apply a package to bootstrap or upgrade a cluster
- fetch cluster kubeconfig
- reset or uninstall a cluster
The project currently includes distro integrations for:
- RKE2
- K3s
How it works
Cargoship is organized around two main concepts:
1. Offline distro packages
A distro package contains the artifacts needed to install a Kubernetes distribution in disconnected or controlled environments. That includes:
- distro metadata
- host files
- engine configuration
- OCI images
- checksums and package layout metadata
The package creation pipeline loads a distro definition, assembles package content, and writes an archive for later distribution.
2. Phase-based cluster operations
Cluster operations are modeled as ordered phases. High-level actions such as apply, prepare, reset, and kube-config are composed from reusable phases.
For example, apply includes steps such as:
- connect to hosts
- detect OS
- gather facts
- validate hosts
- prepare hosts
- upload files
- configure the engine
- initialize or upgrade nodes
- update kubeconfig
- release locks and disconnect
This phase model makes cluster operations structured, debuggable, and easier to extend.
Configuration model
Cargoship uses typed YAML definitions for:
- cluster inventory/config
- distro package definitions
- distro runtime config
These schemas are generated from Go types and written into schema/, which makes YAML authoring easier in editors that support JSON schema references.
The docs include an inventory authoring guide and example schema usage.
Documentation
Project docs are built with mdBook and live under docs/.
Generated docs include:
- CLI command reference
- phase documentation
- summary/navigation content
Docs are generated from real code so the command and phase documentation stay aligned with implementation.
Build and development workflow
This repo uses Mage for task automation and Dagger for the main build pipeline.
Mage responsibilities
Mage targets are used for:
- local builds
- Dagger builds
- end-to-end tests
- docs generation
- schema generation
Dagger responsibilities
Dagger is used as the default build path for producing binaries across platforms.
Generated outputs
Automation in this repo maintains:
build/cargoship_*docs/commands/*docs/phases/*docs/SUMMARY.mdschema/*.json
Examples
The example/ directory contains sample distro content for:
k3srke2
These examples are useful for understanding package structure and authoring your own distro definitions.
Release and CI
The repository includes GitHub workflows for:
- dependency validation
- build/test checks
- e2e runs
- docs deployment
- release automation
Releases are driven by GoReleaser, with checksum and signing support.
Design notes
A few notable implementation patterns in the repo:
- side-effect registration for distro and OS modules
- phase-oriented orchestration for cluster workflows
- generated docs and schemas from source code
- offline-first packaging centered around files, images, and checksums
Inspiration
This project is clearly influenced by tools such as:
while focusing on offline distro packaging plus SSH-based cluster lifecycle management.
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
src
|
|
|
api
Package api for core logic shared between the api resources
|
Package api for core logic shared between the api resources |
|
api/zarf.dev/v1alpha1
Package v1alpha1 is for the shared File logic across both the cluster and distro api's
|
Package v1alpha1 is for the shared File logic across both the cluster and distro api's |
|
api/zarf.dev/v1alpha1/cluster
Package cluster is for the api representation of Cluster
|
Package cluster is for the api representation of Cluster |
|
api/zarf.dev/v1alpha1/distro
Package distro is for the api representation of Distro Package
|
Package distro is for the api representation of Distro Package |
|
cmd
Package cmd is where the commands for cargoship
|
Package cmd is where the commands for cargoship |
|
config
Package config is a holder of commonly used multiple times
|
Package config is a holder of commonly used multiple times |
|
config/lang
Package lang holds the cli helping text
|
Package lang holds the cli helping text |
|
internal/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 |
|
internal/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 |
|
internal/dns
Package dns contains DNS related functionality.
|
Package dns contains DNS related functionality. |
|
internal/riglogger
Package riglogger add settings that overrides the rig.Logger
|
Package riglogger add settings that overrides the rig.Logger |
|
internal/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 |
|
pkg/action
Package action are various actions used by the package
|
Package action are various actions used by the package |
|
pkg/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. |
|
pkg/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. |
|
pkg/distro
Package distro is used for creating/deploying distro package
|
Package distro is used for creating/deploying distro package |
|
pkg/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 |
|
pkg/images
Package images is functionality related to interacting with oci images.
|
Package images is functionality related to interacting with oci images. |
|
pkg/lint
Package lint contains functions for verifying yaml files are valid
|
Package lint contains functions for verifying yaml files are valid |
|
pkg/node
Package node is used for status related functions
|
Package node is used for status related functions |
|
pkg/oci/archive
Package archive implements the Archive interface for the OCI archive store.
|
Package archive implements the Archive interface for the OCI archive store. |
|
pkg/oci/cache
Package cache are a sub-section of function from defense-unicorn pkg oci cache package
|
Package cache are a sub-section of function from defense-unicorn pkg oci cache package |
|
pkg/packager/assemble
Package assemble builds a Cargoship package on disk
|
Package assemble builds a Cargoship package on disk |
|
pkg/packager/layout
Package layout is used to defining the distro package files
|
Package layout is used to defining the distro package files |
|
pkg/packager/load
Package load for loading a given package
|
Package load for loading a given package |
|
pkg/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. |
|
pkg/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 |
|
pkg/utils
Package utils is for commonly used functions
|
Package utils is for commonly used functions |
|
pkg/utils/build
Package build is logic shared across dagger and mage
|
Package build is logic shared across dagger and mage |
|
types
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 |
|
types/distrocfg
Package distrocfg defines the standard interface that all distro config settings
|
Package distrocfg defines the standard interface that all distro config settings |
|
types/distrocfg/registry
Package registry is used to register a distro
|
Package registry is used to register a distro |
|
types/os
Package os is for running commands on a remote host
|
Package os is for running commands on a remote host |
|
types/os/linux
Package linux is implementing the interface github.com/colonel-byte/cargoship/src/types/os.Configurer for Linux based hosts
|
Package linux is implementing the interface github.com/colonel-byte/cargoship/src/types/os.Configurer for Linux based hosts |
|
types/os/linux/enterpriselinux
Package enterpriselinux is implementing the interface github.com/colonel-byte/cargoship/src/types/os.Configurer for Enterprise Linux hosts
|
Package enterpriselinux is implementing the interface github.com/colonel-byte/cargoship/src/types/os.Configurer for Enterprise Linux hosts |