Cargoship

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

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.
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/

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

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, 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. 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.

9. Validate a File, or Write Its Schema

# Check an inventory, package definition, or config file against its schema
cargoship validate ./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 sha256sum ./build/cargoship-distro-amd64.tar.zst

10. 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 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, and the phase-by-phase ledger with per-host change reasons and diffs. 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.

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.

• Running Cargoship as an Ansible Module - the modules, their parameters, check mode, and what changed means.
• 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 collections 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.

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.

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:

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.

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.

Security Policy

Supported versions

Cargoship is pre-1.0 and releases from main on every conventional commit that warrants one, so fixes land in a new minor release rather than being backported. Only the most recent release line receives security fixes; upgrade before reporting an issue against an older tag.

Reporting a vulnerability

Report privately through GitHub: open a draft advisory. Do not open a public issue, and do not include a working exploit against a third party’s cluster.

You should expect an acknowledgement within 3 business days and an assessment – whether we consider it a vulnerability, and the severity we assign – within 10 business days. Confirmed issues are fixed in the next release, and we aim to publish the advisory within 90 days of the report, sooner when a fix is already out. You will be credited in the advisory unless you ask not to be.

Include the output of cargoship version, the host OS of the management node, the Kubernetes engine involved (K3s or RKE2), the commands that reproduce the behaviour, and what an attacker gains.

Scope

In scope: the cargoship CLI and the packages under the module root; package signing and the verification path (--verify, --key); credential handling in clustercfg, including the vault splice and age encryption; SSH orchestration against target hosts; and the release workflow and the artifacts it publishes.

Out of scope: vulnerabilities in K3s, RKE2, containerd, or any other upstream component Cargoship packages – report those to the project that owns them; anything that requires an attacker to already have root on the management node, which by design holds the cluster’s credentials; resource exhaustion from deliberately malformed or oversized packages supplied by the operator themselves; and misconfiguration of a user’s own cluster.

Verifying a release

Release archives, checksums.txt, and container images are signed with cosign using the key whose public half is cosign.pub in this repository, archives ship with an SBOM, and every tag also publishes ai-bom.json – the AI-usage disclosure manifest described below – attested and signed the same way.

cosign verify-blob --key cosign.pub --bundle checksums.txt.sigstore.json checksums.txt
cosign verify --key cosign.pub ghcr.io/colonel-byte/cargoship:<tag>

See the GoReleaser reference for the full set of published artifacts.

AI-assisted development

Cargoship’s code, docs, and design records are written with AI coding agents in the loop. See AI usage for what’s used and how it’s reviewed. Each release publishes ai-bom.json, a per-release snapshot of that disclosure – verify it the same way as the other release artifacts, above.

Security in CI

Pull requests and main are scanned by CodeQL, dependencies are updated by Dependabot, and supply-chain practices are scored weekly by OpenSSF Scorecard. Results appear in the repository’s Security tab. vendor/ costs points on a couple of Scorecard checks it can’t avoid given the repository’s need to build without network access; choice-osv-vendor-overrides and choice-binary-artifact-opa-wasm explain why.

age Encryption

This guide explains how Cargoship encrypts registry credentials in a cluster configuration with age, and how to read them back out. age is an alternative to Ansible Vault, not a replacement for it: the same commands write both formats, one configuration can hold both, and an apply reads whichever format each value carries.

For the Ansible Vault side of the same commands, see vault-encryption. Everything that guide says about YAML paths, anchors and aliases, dry runs, and the in-place rewrite is true here as well; this guide covers only what differs.

Why age

The draw is the key model rather than the cipher.

Ansible Vault is a shared passphrase. Everyone who has to run an apply has the same secret, which means the secret has to be distributed, and revoking one person’s access means rotating it for everybody.

age is public key encryption. You encrypt a credential to a set of public keys – the recipients – and it can only be read with one of the matching private keys, the identities. A machine that only has to encrypt needs no secret at all: a CI job that commits a configuration holds the public keys and nothing more. Revoking access means re-encrypting to a smaller recipient set, which is one command over the whole file and touches no other key.

Ansible Vault remains the better fit when a single operator or a single shared credential store is the whole story, and it is what an existing configuration already uses. Neither format is going away.

What Cargoship Decrypts

The same four fields per registry, in either format:

Cargoship tells the formats apart by the value’s own header. Ansible Vault ciphertext starts with $ANSIBLE_VAULT; age ciphertext is armored, so it starts with -----BEGIN AGE ENCRYPTED FILE----- and ends with -----END AGE ENCRYPTED FILE-----. A value carrying neither is plaintext and is passed through untouched.

Nothing records the format in the schema, and no flag selects it for reading. That is what lets one document mix the two. A document encrypted with age does carry a note of the age recipients it was encrypted to, but that is a record of what was done rather than a field anything reads a value’s format from – see What the File Records.

Keys

Making a Key Pair

Cargoship makes a key pair itself, so the age distribution is not something you have to install first:

cargoship vault keygen --output ~/.age/cargoship.key

It writes the identity – the private key, AGE-SECRET-KEY-1... – to the file with mode 0600, and prints the recipient – the public key, age1... – to stderr. It will not overwrite a file that already exists: replacing an identity makes every value encrypted to the old key unreadable, by anyone, permanently. Move the old file aside if you mean to replace it.

age-keygen -o ~/.age/cargoship.key does the same thing and writes the same file. The format is age’s, not Cargoship’s, which is the point: the key stays usable with age --decrypt and anything else that speaks it.

The public key is also in the file, on a # public key: comment line, so you can recover it later:

cargoship vault keygen --public-key ~/.age/cargoship.key

age-keygen -y ~/.age/cargoship.key is the equivalent, and -y is the short flag here too.

Omitting --output writes the private key to stdout instead, which makes the redirect work:

cargoship vault keygen > ~/.age/cargoship.key
chmod 600 ~/.age/cargoship.key

The chmod matters in that form and not the other: a redirect creates the file with whatever mode your shell gives it. Run bare, with no redirect, the command warns – the key is then on the screen and in that terminal’s scrollback.

The public key is not a secret. Commit it, publish it, put it in a ticket.

Recipients: the Keys That Encrypt

Three flags name recipients, and all three are repeatable:

--age-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
--age-recipients-file ./recipients.txt

A recipients file holds one public key per line. Blank lines are ignored, and a line beginning with # is a comment, so the file doubles as the list of who can read the configuration:

# alice, platform team
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# bob, platform team
age19h0ngeasgxd5vpcfavgavma2m39cmq3a2xlhggs6u0r5rtscx5ms0gw4jh

# the CI runner's deploy key
age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg

The comment has to be on its own line. A # after a key on the same line is read as part of the key, and the file fails to parse with the line number. This is age’s own format, and age --recipients-file reads the same file.

SSH public keys go in the same flags and the same file; see Using an SSH Key.

Every recipient named across every flag is encrypted to, so a value can be readable by several people at once. This is the normal case, not a migration state.

When no recipient flag is given, Cargoship reads CARGOSHIP_AGE_RECIPIENTS, which holds whitespace-separated public keys:

export CARGOSHIP_AGE_RECIPIENTS="age1ql3z... age19h0n..."

A recipients file that parses to no keys at all is an error rather than nothing to do, because carrying on would fall back to writing Ansible Vault ciphertext under a password the operator did not ask to use.

Identities: the Keys That Decrypt

--age-identity-file ~/.age/cargoship.key

Repeatable, and a single file may hold several identities. Every identity Cargoship has been given is tried against a value, so holding keys for two teams in one file works.

When no identity flag is given, Cargoship reads CARGOSHIP_AGE_IDENTITY_FILE, which holds exactly one path. A list would need a separator, and every separator worth choosing is legal in a file name.

Using an SSH Key

An ssh-ed25519 or ssh-rsa key works anywhere an age key does, and goes in the same three flags. There are no --ssh-* flags, because there is no point in making an operator work out which kind of key they hold before choosing a flag:

cargoship vault encrypt-file ./cluster.yaml --age-recipient "$(cat ~/.ssh/id_ed25519.pub)"
cargoship vault encrypt-file ./cluster.yaml --age-recipients-file ./authorized_keys
cargoship vault decrypt-file ./cluster.yaml --age-identity-file ~/.ssh/id_ed25519

This is worth doing because the keys already exist. A team that maintains an authorized_keys file can encrypt a configuration to it as it stands – options in front of a key and comments behind it parse fine – and nobody has to generate, distribute, or lose a new key.

A recipients file may mix the two kinds freely, which is what makes a gradual move onto native age keys possible:

# alice, on her age key already
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# bob, still on his SSH key
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample bob@example.com

A line that is neither – an ecdsa-sha2-nistp256 key, say, which age does not support – fails the whole file with its line number rather than being skipped. Skipping it would encrypt to fewer people than the file lists, and the one who finds out is the one who cannot decrypt.

Three things differ from a native age key:

• A passphrase-protected private key is prompted for on a terminal, and fails without one. The prompt happens only once a value turns out to be encrypted to that key, and the decrypted key is then reused for the rest of the run. Under CI, or with input piped in, the command fails immediately and says so; it does not read the passphrase out of standard input and does not hang. If that is where the key has to be used, decrypt it first with ssh-keygen -p.
• The public key is not derived from the private one. cargoship vault keygen --public-key reads age identity files only. ssh-keygen already wrote the public key into the .pub file beside the key, and ssh-keygen -y -f ~/.ssh/id_ed25519 prints it again.
• SSH recipients are not anonymous. See Recipients Are Anonymous below.

Upstream’s own advice is that these key types exist for compatibility with keys you already have, and that a native age key is preferable otherwise. cargoship vault keygen makes one.

Nothing Is Discovered

Cargoship reads key material from the flags, the config file, and those two environment variables. It reads nothing else. It does not look in ~/.config/sops/age/keys.txt, it does not look in $XDG_CONFIG_HOME/age, it does not read an age agent, and it does not pick your SSH key up out of ~/.ssh because it happens to be there.

The one path derived rather than given is the .pub file beside a passphrase-protected SSH key, which older key formats do not carry their public key inside. That path comes from the identity file the operator named on the command line, and is read only when that key needs a passphrase.

This matches ResolveVaultPassword, which has always behaved the same way, and it is deliberate: an apply that succeeds on one operator’s machine because of a file the configuration never mentions is an apply nobody can reason about.

Keys in the Config File

All three flags can be defaulted from the age section of cargoship-config.yaml, so a team can commit its recipient set once instead of restating it on every command:

age:
  recipients:
    - age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
    - age19h0ngeasgxd5vpcfavgavma2m39cmq3a2xlhggs6u0r5rtscx5ms0gw4jh
  recipients_files:
    - /etc/cargoship/recipients.txt
  identity_files:
    - /home/operator/.age/cargoship.key

Each key is a list, and each is the equivalent of repeating its flag. A recipient in the config file counts as choosing age exactly as the flag does – see below.

Put only public keys in a committed config file. identity_files holds paths, not keys, so it is safe to commit when the path is a per-machine convention; it is still a per-operator choice, and the environment variable is often the better home for it.

Choosing the Format Cargoship Writes

Reading never involves a choice: the value’s header decides. Writing does, and Cargoship resolves it like this:

1. An age recipient given on the command line or in the config file wins, even when CARGOSHIP_VAULT_PASSWORD or ANSIBLE_VAULT_PASSWORD is set in the environment. Those variables are typically set once in a shell profile on a machine that already uses vault, and an operator who passes --age-recipient is asking for age, not for a complaint about a variable they set months ago.

2. An age recipient and an explicit --vault-password-file together is an error:

   age recipients and a vault password file were both given; pass one or the other,
   since a value is written in a single format
   

   Both flags name the key to write with. Picking one would mean writing a secret under a key the operator did not choose, which is worth stopping for rather than guessing well.

3. Otherwise Ansible Vault, exactly as before.

With no key material at all, every vault command fails up front:

no encryption key found: set --vault-password-file or the
CARGOSHIP_VAULT_PASSWORD/ANSIBLE_VAULT_PASSWORD environment variable, or pass
--age-recipient and --age-identity-file

An apply is the exception. A configuration holding no encrypted credential needs no key, so an apply accepts an empty keyring and only fails if it meets a value it cannot read.

The Commands

The cargoship vault group is the same group, and it keeps its name – renaming it would break every operator’s scripts:

cargoship vault encrypt [VALUE]
cargoship vault encrypt-path FILE YAML_PATH [YAML_PATH...]
cargoship vault encrypt-file FILE
cargoship vault decrypt [VALUE]
cargoship vault decrypt-path FILE YAML_PATH [YAML_PATH...]
cargoship vault decrypt-file FILE
cargoship vault rekey FILE
cargoship vault keygen [IDENTITY_FILE]

keygen is the only one of them that takes no key material, since it is the command that makes some.

Encrypting a Value

cargoship vault encrypt my-registry-password --age-recipient age1ql3z...

The output is an armored age block that you paste into the configuration at the right indentation, the same way a $ANSIBLE_VAULT block is pasted. vault encrypt-path does that part for you.

Passing a secret as an argument leaves it in your shell history and in the process list. Prefer stdin, or the hidden prompt you get when stdin is a terminal:

cargoship vault encrypt --age-recipient age1ql3z... < ./registry-token.txt

Decrypting a Value

cargoship vault decrypt --age-identity-file ~/.age/cargoship.key < ./encrypted-token.txt

An armored age value begins with dashes, so passing it as an argument does not work – the shell hands it to Cargoship intact, but the flag parser reads the leading ----- as a flag and fails with bad flag syntax. Use stdin, as above, or put -- after all of the flags so that everything following it is read as an argument:

cargoship vault decrypt --age-identity-file ~/.age/cargoship.key -- "$CIPHERTEXT"

$ANSIBLE_VAULT values do not have this problem, which is why it only comes up now.

When no configured identity can read the value, the error says what the value was encrypted to:

none of the configured age identities can decrypt this value; it is encrypted to
X25519 recipients

That is as specific as it can be. See Recipients Are Anonymous.

Encrypting a Whole Configuration

cargoship vault encrypt-file ./cluster.yaml --age-recipient age1ql3z...

Every registry credential in the file that is plaintext is encrypted to the recipients; anything absent, empty, or encrypted already in either format is skipped. Comments, key order, and the rest of the document survive byte for byte.

Running it twice changes nothing the second time, so it is safe in a script or a pre-commit hook, and running it over a half-encrypted configuration finishes the job.

There is one consequence of that worth stating plainly. encrypt-file never moves a credential between formats, and never re-encrypts one to a new recipient set. Running it with new recipients against a file whose credentials are already encrypted does nothing to the file. It does not do it quietly, though – every credential it left alone is reported, with the reason:

WRN left this credential as it was: it is encrypted to age recipients already, and cargoship
    cannot tell whether they are the ones you named, because age ciphertext does not record its
    recipients; run 'cargoship vault rekey' with an identity to re-encrypt it to the recipients
    you want  file=./cluster.yaml path=$.spec.config.registries[0].auth.pass
INF nothing to encrypt: every registry credential is encrypted already, or there are none to encrypt

The same warning appears when the formats differ, naming the one the value is in and the rekey invocation that moves it. Warnings are written to stderr, so --dry-run piped to a file still produces a clean document.

To change which keys a configuration is encrypted to, use rekey.

Decrypting a Whole Configuration

cargoship vault decrypt-file ./cluster.yaml --age-identity-file ~/.age/cargoship.key

Every encrypted registry credential becomes plaintext again, whatever format it was in, and anything that is not encrypted is skipped. If any value fails to decrypt, the command fails and the file is not touched at all.

Give both --age-identity-file and --vault-password-file to decrypt a document holding both formats. That combination is fine here: it is only encrypting that has to choose one format, and only then that giving both is an error.

Mixed Documents

A configuration can hold both formats at once, and not only while migrating:

    registries:
      - name: harbor.internal
        auth:
          user: robot
          pass: |-
            $ANSIBLE_VAULT;1.1;AES256
            31333438393936323663373461353533373034663339316335386139363535383531643464613539
            ...
      - name: ghcr.io
        auth:
          user: ci
          pass: |-
            -----BEGIN AGE ENCRYPTED FILE-----
            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBB...
            -----END AGE ENCRYPTED FILE-----

An apply given both a vault password and an identity file reads this document without complaint. A legacy credential nobody wants to touch can stay vaulted indefinitely while everything new is written to age.

Migrating from Ansible Vault

rekey is the migration, and there is no other command for it:

cargoship vault rekey ./cluster.yaml \
  --vault-password-file ./vault-pass.txt \
  --age-recipient age1ql3z...

Every vaulted registry credential in the file is read with the password and written back to the recipients, in one pass. The plaintext is never written to the file: each value is decrypted and encrypted again in memory, so there is no window in which the configuration on disk is readable, and nothing to clean up if the command fails partway. --dry-run prints the result to stdout and leaves the file alone.

The same rule that has always governed rekey applies: rotate the whole file, not one value at a time. If any encrypted value in the file cannot be read with the key given, the command stops before writing anything and names the path.

--new-vault-password-file and --age-recipient together is an error. Each names the key to rekey onto, and honouring one would mean silently ignoring the other.

To go the other way – age back to Ansible Vault – read with the identity and write with a new password:

cargoship vault rekey ./cluster.yaml \
  --age-identity-file ~/.age/cargoship.key \
  --new-vault-password-file ./vault-pass.txt

Revoking Access

Removing someone’s key from a recipients file changes nothing on its own. The ciphertext in the configuration was encrypted to them and still is. Re-encrypt it:

cargoship vault rekey ./cluster.yaml \
  --age-identity-file ~/.age/cargoship.key \
  --age-recipients-file ./recipients.txt

Reading needs an identity that is still in the file; writing uses the new, smaller recipient set. Afterwards the removed key can no longer read the configuration.

Treat the credential itself as compromised anyway if the person had it. Re-encryption removes their access to the file; it does not un-tell them a password they have already read. The registry credential should be rotated at the registry too.

Afterwards, metadata.encryption.age.recipients lists the set you rekeyed to, so the removal is visible in the diff rather than only in the re-randomized ciphertext. That list is a note rather than a check – see What the File Records – but it is the reason a second operator can tell, from the file alone, whether the revocation has happened yet.

If you are not sure whether a configuration has already been rekeyed, running encrypt-file with the recipient set you want is a safe way to ask: it re-encrypts nothing, and it warns if what the file records is not what you named.

Naming the recipient set the file already uses re-encrypts every value to those same recipients:

cargoship vault rekey ./cluster.yaml \
  --age-identity-file ~/.age/cargoship.key \
  --age-recipients-file ./recipients.txt

age re-randomizes every encryption, so each value comes back as different ciphertext holding the same plaintext for the same recipients – useful when the ciphertext has been somewhere you would rather it had not been.

Cargoship reports this as a rekey rather than as the re-salt it is, because it cannot tell the two apart: the recipients you name may or may not be the ones the values already carry, and the ciphertext does not say. With Ansible Vault, where omitting --new-vault-password-file unambiguously means “the key this file already has”, the same command is reported as a re-salt.

An identity on its own is not enough. rekey --age-identity-file key.txt with no recipients names nothing to write with and fails:

no vault password and no age recipients were provided

Checking Before an Apply

An apply verifies every encrypted value as soon as it has resolved the keys – before it connects to any host, and on a sync, before it starts draining nodes. A missing identity fails the command immediately rather than part-way through a cluster change.

With age this check matters more than it did with a shared password. A value encrypted to the wrong recipient set is indistinguishable from a correct one until something tries to read it, and nothing else in the pipeline will.

To check a configuration by hand without writing plaintext anywhere:

cargoship vault decrypt-file ./cluster.yaml --age-identity-file ~/.age/cargoship.key --dry-run > /dev/null

Or run the real preflight without touching a host:

cargoship apply ./cluster.yaml --age-identity-file ~/.age/cargoship.key --dry-run

Recipients Are Anonymous

An age header written to a native age1... recipient does not say who the value was encrypted to. The X25519 stanza holds an ephemeral share and nothing else – no key identifier, no fingerprint – by design, so that ciphertext does not leak its audience.

SSH recipients are the exception. An ssh-ed25519 or ssh-rsa stanza carries a short 32-bit hash of the public key, so someone holding a copy of the ciphertext and a list of candidate public keys can tell which of them it was encrypted to. If who can read a configuration is itself something you do not want in a committed file, use native age keys.

Either way, two things follow, because Cargoship reads no stanza at all – age keeps that parser internal, so nothing here can see even the recipient hash:

• Cargoship cannot tell you whether a value is already encrypted to the recipients you have in hand. It can only tell you that it is encrypted, and – since it writes down the recipients it used – what the file says it was encrypted to. Those are different claims, and the second one is a note, not a check; see What the File Records. This is why encrypt-file skips an encrypted value rather than checking it, why it warns about every value it skipped rather than staying quiet, and why changing recipients is rekey’s job.
• An error about a value you cannot read can never name the key you are missing. none of the configured age identities can decrypt this value is the whole of what is knowable.

docs/agent/choice-age-encryption.md records the reasoning in full.

What the File Records

Because the ciphertext cannot say who it was encrypted to, the document says it instead. After an age encryption, metadata carries the recipient set the run used:

apiVersion: colonel-byte.dev/v1alpha1
kind: Cluster
metadata:
  name: e72
  encryption:
    age:
      recipients:
        - age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
        - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... alice@laptop
      lastModified: "2026-09-16T10:30:00Z"
spec:
  config:
    registries: ...

An SSH recipient keeps its authorized_keys comment, because that is the part that says whose key it is. Keys appear in the order you named them, and a key named twice – on a flag and again in a recipients file – appears once. lastModified is when Cargoship last rewrote the credentials in the document.

It Is a Note, Not a Guarantee

This is the one place in a Cargoship configuration where the file makes a claim about itself that nothing can verify, and it is worth being precise about what that means.

Cargoship writes this block and never reads it back as key material. Not on encrypt-file, not on rekey, not on an apply. rekey with an identity and no recipients still fails with no age recipients configured, exactly as it did before this block existed – it will not quietly encrypt to whatever the file happens to list.

That restriction is the whole safety argument. If any command encrypted to the keys named in the file, a one-line edit in a pull request would silently redirect every credential in it to the author’s key, and the resulting ciphertext would be indistinguishable from a correct one. So the block is inert: Cargoship writes it, compares against it, and acts on neither.

What that buys you, concretely:

• Reading the file tells you which keys it was encrypted to, which is otherwise unknowable without trying every private key you have.
• A code review can see a recipient set change, in the diff, as a line of YAML rather than as a wall of re-randomized ciphertext.
• encrypt-file can tell you that the recipients you just named are not the ones the file claims – which is a much more useful thing to hear than “skipped, and I cannot tell you why”.

And what it does not buy you: an edited list is a lie the file tells, and nothing in Cargoship will catch it. Treat the block the way you would treat a comment – accurate because the tooling wrote it and the diff is reviewed, not because anything enforces it.

When It Is Written and Removed

• encrypt-file writes it when it encrypted at least one credential to age. A run that encrypted nothing changes nothing, including the timestamp, so running the command twice still leaves the file byte for byte identical.
• rekey rewrites it with the recipients it wrote to, and removes it when the target is Ansible Vault – a list of age keys that open nothing in the file is worse than no list at all.
• decrypt-file removes it, unless age ciphertext remains somewhere in the document. A recipient list above a file full of plaintext reads as a file that is still protected.
• A metadata mapping written in flow style – metadata: {name: e72} – has nowhere to put the block. Cargoship encrypts the credentials as usual and warns that it could not record them; writing a nested block into a flow mapping would leave a document that no longer parses, with the credentials already encrypted into it.

Nothing else in Cargoship touches the block. An apply ignores it, and a document without one works exactly as it did before.

When the Recipients Disagree

Running encrypt-file against a file that is already encrypted skips every credential, as it always has. When the file records a different recipient set from the one you named, the skip warnings are joined by one that says so:

WRN the credentials this run left as they were are recorded as encrypted to age recipients
    other than the ones you named  file=./cluster.yaml
    recorded="age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"
    named="age19h0ngeasgxd5vpcfavgavma2m39cmq3a2xlhggs6u0r5rtscx5ms0gw4jh"
    hint="run 'cargoship vault rekey' with an age identity and these recipients to re-encrypt it to them"

The comparison is on the keys themselves, so an authorized_keys comment added or removed, and a recipients file reordered, are not drift. The skip warnings beside it still say what they always did – that the value is age ciphertext and Cargoship cannot tell what it opens with. Both are true, and they answer different questions: one is about the ciphertext, this one is about what the document claims.

Older Binaries

The metadata block is new, and cargoship validate rejects fields it does not know about. A configuration carrying the block therefore fails validate on a Cargoship built before it existed. An apply is unaffected – it ignores unknown fields – and so is decryption, since the block has nothing to do with reading a value.

Interoperability with age

Cargoship writes the same armored format age --armor writes, so the tools read each other:

cargoship vault encrypt hunter2 --age-recipient age1ql3z... > ct.txt
age --decrypt --identity ~/.age/cargoship.key ct.txt

printf hunter2 | age --encrypt --armor --recipient age1ql3z... > ct.txt
cargoship vault decrypt --age-identity-file ~/.age/cargoship.key < ct.txt

What Is Not Supported

• ssh-agent. A passphrase-protected SSH key is prompted for directly; a key held in an agent is not reachable, because age’s SSH support needs the private key itself rather than a signing oracle.
• SSH key types other than ssh-ed25519 and ssh-rsa. ecdsa-* and sk-* keys are not supported by age.
• age passphrases (scrypt). age can encrypt to a passphrase instead of a public key. Cargoship does not expose that, because it is the thing Ansible Vault already does here – a shared secret – and having two ways to spell it would help nobody.
• Plugins (age-plugin-yubikey and friends). Cargoship links the age library rather than shelling out to the age binary, and plugin support is a property of the binary.

Notes

• A failed command never touches the file. The rewrite goes to a temporary file alongside the original and is renamed over it, so an interruption cannot leave a half-written configuration.
• The file’s mode is preserved across a rewrite.
• Armored age ciphertext is longer than the plaintext it holds by a fixed overhead of a couple of hundred bytes, so a short password becomes a block several lines long. This is normal, and why every command writes it as a YAML block scalar rather than a quoted string.

Running the Collection from the Container

The cargoship-ansible image is a management node in a container: ansible-core on an AlmaLinux 10 base, plus the signed cargoship RPM, which carries the binary and the colonel_byte.cargoship collection. It exists so that a fleet can be converged from a playbook without staging Ansible, the collection and the binary onto a VM by hand. This guide covers what has to be mounted into it, why the package mount is read-only, and the two things that break a run before it reaches the fleet: the UID the container runs as, and host key checking.

For the modules themselves – their parameters and what changed means – see ansible-module, and for the inventory they translate, ansible-inv. Nothing about either changes inside the container.

podman pull ghcr.io/colonel-byte/cargoship-ansible:v0.37.0

The image has no ENTRYPOINT, because a run legitimately reaches for ansible-playbook, ansible-inventory, ansible-galaxy or cargoship itself; name the command you want. The collection is installed to /usr/share/ansible/collections, which is already on ansible-core’s default collections path, so ansible-playbook resolves colonel_byte.cargoship.cargoship_apply with no configuration. HOME is /home/nonroot, the working directory is /workspace, and the process runs as UID and GID 65532.

The image carries cargoship and the collection, and nothing for talking to the cluster afterwards. kubernetes.core is present because the base carries the full ansible distribution, but the Python client its modules import is not, so a k8s task fails at import time; there is no helm or kubectl either. A play that converges the cluster and then applies manifests to it needs an image of your own, built FROM this one with those added.

Every Path in a Playbook Is a Path Inside the Container

Cargoship runs in the container and connects to the fleet from there, so package, inventory_path, vault_password_file and ansible_ssh_private_key_file all name paths the container can see – not paths on the machine that started it. Mount each one at the same path it has on the host wherever you can. It costs nothing and it means the inventory reads the same whether the run happens in the container or on a management node that installed the package.

An apply leaves update_kubeconfig on by default, which merges the cluster’s admin credentials into KUBECONFIG when it is set and ~/.kube/config otherwise – inside the container, a file under /home/nonroot that goes away with the container. Mount a kubeconfig, name one with the kubeconfig parameter, or pass update_kubeconfig: false and fetch it deliberately with cargoship_kube_config; what you should not do is leave the default and wonder where the credentials went.

Everything under /home/nonroot is already created and owned by 65532 in the image, so a run with none of the optional mounts works – it just starts cold each time and keeps nothing. The cache is the one worth adding first, and it has a section of its own below.

Reaching a Cluster on the Same Host

The same rule catches addresses, not just paths, and a local k3d cluster is where it bites first. k3d kubeconfig get <name> writes server: https://0.0.0.0:41609, naming the port k3d published on the host; 0.0.0.0 inside the container is the container’s own network namespace, where nothing is listening. A task given that kubeconfig fails on a connection refused that reads like a cluster that is down, and the cluster is fine.

Two addresses do reach it, and the serving certificate is what limits it to two. k3d starts k3s with --tls-san 0.0.0.0 and --tls-san k3d-zarf-serverlb, on top of k3s’s own 127.0.0.1 and localhost, so a name the certificate does not carry – host.docker.internal, or the bridge gateway address – fails verification even once it routes.

Joining the cluster’s own network is the arrangement to prefer. Rewrite the server to the load balancer’s name inside that network:

mkdir -p build/tmp
k3d kubeconfig get zarf | sed -E 's|https://0.0.0.0:[0-9]{5}|https://k3d-zarf-serverlb:6443|' > build/tmp/zarf-config.yaml
chmod 0644 build/tmp/zarf-config.yaml

Then attach the container to that network and mount what it wrote:

docker run --rm \
  --network k3d-zarf \
  -v "$PWD/build/tmp/zarf-config.yaml":/home/nonroot/.kube/config:ro,z \
  -e KUBECONFIG=/home/nonroot/.kube/config \
  -v "$PWD":/workspace:ro,z \
  ghcr.io/colonel-byte/cargoship-ansible:v0.37.0 \
  ansible-playbook init.yaml

Rewriting k3d’s own output rather than hand-writing a kubeconfig keeps the embedded CA and client certificate intact. docker is deliberate here: the k3d network is docker’s, and rootless podman cannot attach to it. The load balancer’s name resolves inside that network for as long as the cluster exists, so this survives a k3d cluster stop && k3d cluster start that republishes the API on a different host port.

Reaching the published port instead means host networking, since that port is bound on the host:

k3d kubeconfig get zarf | sed 's|https://0.0.0.0:|https://127.0.0.1:|' > kubeconfig.yaml
chmod 0644 kubeconfig.yaml

docker run --rm \
  --network host \
  -v "$PWD/kubeconfig.yaml":/home/nonroot/.kube/config:ro,z \
  -e KUBECONFIG=/home/nonroot/.kube/config \
  ghcr.io/colonel-byte/cargoship-ansible:v0.37.0 \
  zarf tools kubectl get nodes

It is the shorter way to a one-off check, and it costs the container’s network namespace, which a run that also opens SSH connections to a fleet should not give up lightly. The port is whatever docker port k3d-zarf-serverlb 6443 reports, and it is reassigned every time the cluster is recreated. zarf tools kubectl is the smoke test to reach for because the image has no kubectl of its own.

Either way the kubeconfig is mounted read-only – zarf reads it and writes nothing back – and it has to be readable by UID 65532, which is what the chmod 0644 on the copy is for. A mounted directory has to be traversable by that UID too, so a playbook tree under a 0700 directory arrives as a /workspace the container cannot open, and ansible-playbook reports a playbook it could not find rather than a permission error.

None of this applies to a real fleet. A cluster cargoship installed is reached over the network like any other host, and cargoship_kube_config – or an apply’s update_kubeconfig, above – is what puts its credentials where a later task can find them.

The Package Mount Is Read-Only Because Nothing Writes to It

A distro package is the one input large enough that copying it into an image, or into the container’s writable layer, is a real cost – it carries every image and file the cluster installs. It is also read-only by nature: cargoship apply reads the package and writes to the fleet, never back into the artifact. Mounting it :ro costs nothing and turns a whole class of mistake, a run that mutates the staging directory every other run depends on, into an error at the moment it is attempted.

podman run --rm \
  --userns=keep-id:uid=65532,gid=65532 \
  -v /srv/staging:/srv/staging:ro,z \
  -v "$PWD":/workspace:ro,z \
  -v ~/.ssh/fleet_ed25519:/home/nonroot/.ssh/fleet_ed25519:ro,z \
  -v ~/.ssh/known_hosts:/home/nonroot/.ssh/known_hosts:z \
  -v ~/.cargoship-cache:/home/nonroot/.cargoship-cache:z \
  ghcr.io/colonel-byte/cargoship-ansible:v0.37.0 \
  ansible-playbook -i inventory.yaml converge.yaml

On a host with SELinux enforcing – Fedora, RHEL, and anything derived from them – a volume needs a label option or the container cannot read it. Use z, the shared label, for anything the host or another container also uses, which is all of the above. Z relabels the content privately to one container, and applying it to a shared staging directory takes that directory away from every other reader on the host, including the next container. Docker takes the same options; it is the label, not the runtime, that decides this.

Mounting the Cache Read-Write

The cache is where cargoship keeps what it fetches – OCI artifacts it pulls, and the release assets the example generation reads – under ~/.cargoship-cache, which is /home/nonroot/.cargoship-cache in the container. It is the only mount in this guide that exists purely to make the next run faster, and the only one that is worthless read-only: a cache that cannot be written to is a cache that is empty on every run, and a read-only mount turns what would be a slow run into a failed write.

podman run --rm \
  --userns=keep-id:uid=65532,gid=65532 \
  -v ~/.cargoship-cache:/home/nonroot/.cargoship-cache:rw,z \
  -v /srv/staging:/srv/staging:ro,z \
  -v "$PWD":/workspace:ro,z \
  ghcr.io/colonel-byte/cargoship-ansible:v0.37.0 \
  ansible-playbook -i inventory.yaml converge.yaml

rw is the default for a bind mount and is written out here only to say that it is meant: the package above it is ro on purpose, and the pair reads as a decision rather than an omission. Create the directory on the host first – mkdir -p ~/.cargoship-cache – because a bind mount whose source does not exist is created by the runtime as an empty directory owned by root, which the container cannot then write to.

The same UID rule as everywhere else decides whether the write succeeds, and there are three ways to satisfy it. --userns=keep-id:uid=65532,gid=65532 maps your host UID onto the one the container runs as, which is the right answer when the cache lives in your home directory and you want to look at it afterwards. chown -R 65532:65532 ~/.cargoship-cache is the right answer under Docker or rootful Podman, where there is no mapping to arrange. Podman’s :U option – -v ~/.cargoship-cache:/home/nonroot/.cargoship-cache:rw,z,U – recursively chowns the source to the container’s user for you, which is convenient and also permanent, so do not point it at a directory anything else on the host owns.

A named volume avoids the question entirely, and is the better arrangement on a dedicated staging host where nobody needs to read the cache from outside:

podman volume create cargoship-cache
podman run --rm \
  -v cargoship-cache:/home/nonroot/.cargoship-cache \
  -v /srv/staging:/srv/staging:ro,z \
  -v "$PWD":/workspace:ro,z \
  ghcr.io/colonel-byte/cargoship-ansible:v0.37.0 \
  ansible-playbook -i inventory.yaml converge.yaml

A new named volume is populated from the image path it is mounted over, ownership included, so it arrives owned by 65532 with no mapping, no chown and no SELinux label option to choose. It survives --rm, and podman volume rm cargoship-cache is how you discard it deliberately.

To put the cache somewhere other than the default path, set it in the environment as DISTRO_ZARF_CACHE, or as zarf_cache in a cargoship configuration file – the modules take no parameter for it, so a playbook cannot pass it per task. The --zarf-cache flag does the same thing for a cargoship command run directly in the container – it is named for zarf’s cache, which is what it is, and it takes cargoship’s path. The default printed in docs/commands is the one this repository’s own cargoship-config.yaml sets, not the built-in ~/.cargoship-cache a container resolves, since viper searches the working directory for a configuration file and a checkout has one.

The UID Is What Actually Breaks First

The image runs as 65532, and a private key mounted from your home directory is owned by you and readable only by you. Under rootless Podman your UID maps to root inside the container by default, so the key arrives owned by a user that is not the one reading it, and the run fails on a key it can see and cannot open. --userns=keep-id:uid=65532,gid=65532 maps your host UID to 65532 inside, which makes every mount above land with an owner that matches the process.

Under Docker, or rootful Podman, there is no mapping to arrange: the file has to be readable by UID 65532 on the host. Give the staging directory and the key to that UID (chown -R 65532:65532 /srv/staging), which is the usual arrangement for a dedicated staging host. Running the image with --user "$(id -u):$(id -g)" instead looks simpler and is not: /home/nonroot and its subdirectories are owned by 65532, so the cache, known_hosts and Ansible’s own temporary directory all become unwritable, and the failures arrive late and read like something else.

When using SSH multiplexing (ControlMaster) with Ansible inside the container, configure ControlPath (or mount a tmpfs volume) where nonroot has write permissions. If an inventory points to a host home directory (e.g. /home/<user>/.ssh/sockets), mount a writable tmpfs with permissive mode (--tmpfs /home/<user>/.ssh/sockets:rw,mode=0777) or point ControlPath to /home/nonroot/.ssh/sockets. Also avoid using :z SELinux relabeling flags on the host ~/.ssh directory when mounting SSH keys, as relabeling host SSH directories can disrupt host sshd services.

Host Keys

Cargoship verifies host keys against ~/.ssh/known_hosts – /home/nonroot/.ssh/known_hosts in the container – and appends a key it has not seen before, which is trust on first use. A fresh container has no such file, so with nothing mounted every host in the fleet is trusted on the first connection of every run, and the file recording that decision is thrown away with the container. That is weaker than it looks: it is not a first use, it is a first use each time.

Two ways out, in order of preference. Mount a known_hosts file writable, as above, so the first run records what it saw and every later run verifies against it. Or point SSH_KNOWN_HOSTS at a file you seeded beforehand; a read-only mount is fine here, but only because every key is already in it – cargoship still has to be able to append when one is not, and a read-only file fails that write.

Setting SSH_KNOWN_HOSTS=/dev/null disables host key verification entirely. It is useful for a lab and is not a workaround for the paragraph above: a management node that accepts any host key accepts a machine standing in for a controller.

SSH Agents Work, With the Socket Mounted

Cargoship reads SSH_AUTH_SOCK and offers the agent’s keys, so an agent on the host serves a run in the container once its socket is mounted and the variable points at it.

podman run --rm \
  --userns=keep-id:uid=65532,gid=65532 \
  -v "$SSH_AUTH_SOCK":/run/ssh-agent.sock:z \
  -e SSH_AUTH_SOCK=/run/ssh-agent.sock \
  -v /srv/staging:/srv/staging:ro,z \
  -v "$PWD":/workspace:ro,z \
  ghcr.io/colonel-byte/cargoship-ansible:v0.37.0 \
  ansible-playbook -i inventory.yaml converge.yaml

An agent is the better arrangement when the key is protected by a passphrase, since nothing has to hold the passphrase inside the container, and it leaves no key file to mount read-only and forget about. It is worse when the run is unattended, because an agent is a session that has to be unlocked by somebody; a key file with a dedicated fleet key is the right answer there.

Encrypting the Generated Inventory on Disk

When inventory_path is set to keep the generated ZarfCluster document across runs, that file normally holds decrypted registry passwords in plaintext with 0600 permissions. To prevent plaintext credentials from remaining on the host staging filesystem, pass age recipients to the role or CLI:

- name: Install cluster
  ansible.builtin.include_role:
    name: colonel_byte.cargoship.cluster
  vars:
    cargoship_action: apply
    cargoship_package: /srv/staging/rke2.tar.zst
    cargoship_inventory_path: /srv/staging/cluster-inventory.yaml
    cargoship_age_recipients:
      - age1wjqegc62gpyvp4yfdqfk4vclfgdh3awlv03rgthcje398a860p7qpglp6w
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIO9OkpTcjwWLH2fo8SUTVjb2NYEc6w996Cwr0wL2cRDx operator@example.com

When cargoship_age_recipients (or --age-recipient on cargoship inventory from-ansible) is provided, cargoship encrypts every registry credential (user, pass, token, tls.ca) into age ciphertext blocks before writing the document to disk.

To decrypt the credentials at apply time, supply the private key via cargoship_age_identity_files:

    cargoship_age_identity_files:
      - /home/nonroot/.ssh/id_ed25519
      - /srv/staging/keys/age.key

Mount the identity file into the container (e.g. -v ~/.ssh/id_ed25519:/home/nonroot/.ssh/id_ed25519:ro), ensure it has 0600 permissions owned by UID 65532, or set age.identity_files in cargoship-config.yaml. Cargoship reads the private key and decrypts the credentials in memory when executing phases.

Air-Gapped Runs Need No Network of Their Own

Everything the convergence installs comes out of the package, so the container needs a route to the fleet and to nothing else. It does not need a registry, a proxy, or a route off the management network, and the image pull is the only step in this guide that touches the internet – do it on the machine that has a route, save the image with podman save, and load it where it runs.

What Not to Mount

Do not mount the container runtime’s socket, a whole home directory, or /etc from the host. The image needs four kinds of thing – a package, a playbook tree, credentials for the fleet, and somewhere to write – and each of them is better named individually than swept in with a parent directory. A resolved Ansible inventory already carries credentials for hosts that are not this cluster, which is why the collection’s action plugin forwards only the variables cargoship reads; mounting your whole home directory undoes that care at the filesystem level.

Do not bake credentials into an image of your own with COPY. An image layer keeps what it is given even after a later layer removes it, and this image is published to a registry that the key’s owner does not control.

Generating an Inventory from Ansible

Cargoship can build its cluster inventory from an Ansible inventory you already have, deriving each host’s role from the Ansible groups it belongs to. This guide covers that translation: the group mapping, the host variables cargoship reads, and the rules the translation follows. The same translation runs inside a playbook, where cargoship is the Ansible module; the modules, the collection, and the cluster role are covered in Running Cargoship as an Ansible Module.

Ansible supplies the inventory and nothing else. It does not connect to the fleet, gather facts on it, or run a task per host. Cargoship opens every SSH connection itself, from the node it runs on – a management node outside the cluster, which is the node the package and images were staged onto. See choice-ansible-module for why the work is split that way.

What the translation reads

Cargoship does not parse an Ansible inventory file. Resolving an inventory means group membership, group_vars, host_vars, dynamic inventory plugins, and the precedence rules over all of them; Ansible does that and hands over the merged result. What cargoship reads is a JSON document holding that result:

{
  "groups": {
    "all": ["kc01", "kc02", "kw01", "db01"],
    "controller": ["kc01", "kc02"],
    "worker": ["kw01"],
    "databases": ["db01"]
  },
  "hostvars": {
    "kc01": {"ansible_host": "10.1.2.3", "cargoship_hostname": "distro-kc01"},
    "kc02": {"ansible_host": "10.1.2.4", "cargoship_hostname": "distro-kc02"},
    "kw01": {"ansible_host": "10.1.2.5", "cargoship_hostname": "distro-kw01"},
    "db01": {"ansible_host": "10.1.2.9"}
  },
  "cluster": {
    "name": "bubbles",
    "loadbalancer": "bubbles-kc.test.com"
  }
}

groups and hostvars are Ansible’s own, verbatim. cluster holds the settings that belong to the cluster rather than to any host, which an Ansible inventory has no way to carry: the cluster name, the load balancer address, and optionally profiles, registries, and values. Those are the same fields .spec.config takes in a hand-written inventory – see the inventory guide.

Translate it:

cargoship inventory from-ansible ./resolved.json -o ./inventory.yaml
cargoship validate ./inventory.yaml

The command reads stdin when given no file, and writes to stdout when given no --output, so it composes. --name and --loadbalancer override what the document says, which is how one projection of a fleet becomes more than one cluster without being rewritten.

Roles come from groups

By default the Ansible group named controller supplies the control-plane nodes, and the group named worker supplies the rest. Those are cargoship’s own role names, so the default guesses at no Ansible convention.

Set roleGroups to map cargoship’s two roles onto the group names your inventory actually uses:

{
  "roleGroups": {
    "controller": ["k8s_masters"],
    "worker": ["k8s_workers", "k8s_infra"]
  }
}

A role may take more than one group. Only controller and worker exist; naming any other role is an error.

Three rules govern what comes out:

• A host in none of the mapped groups is left out. The db01 host in the example above is not part of the cluster and does not appear in the generated inventory. A play’s inventory legitimately carries hosts that have nothing to do with Kubernetes.
• A host in groups mapped to two different roles is an error, naming the host and both groups. There is no precedence rule, because there is no defensible one: picking a role silently would install a cluster nobody asked for.
• Controllers are written first, and the first controller becomes the cluster leader. Within a role, hosts come out in the order the mapping names the groups, and within a group, in the order the inventory lists the hosts. If it matters which node bootstraps the cluster, put it first in the first controller group.

If roleGroups names a group the inventory does not define, that is an error – a misspelled group name there has no other symptom. The default mapping is not held to that, so a cluster of nothing but control-plane nodes needs no worker group.

Host variables

Connection details come from the Ansible variables you already set. Everything cargoship needs beyond those comes from variables under a cargoship_ prefix.

ansible_host and cargoship_hostname are different facts and both are kept: the first is where cargoship connects, the second is what the node calls itself. When neither is set, the name the inventory knows the host by serves as both.

The structured variables – cargoship_host, cargoship_files, cargoship_bastion, cargoship_node_labels, cargoship_node_taints, cargoship_environment – take exactly the shape the inventory schema documents for the field they configure, so there is one vocabulary to learn rather than two:

cargoship_profile: control
cargoship_node_labels:
  adrp.xyz/purpose-control: "true"
cargoship_host:
  ports:
    - port: "6443"
      protocol: tcp
  firewall:
    rules:
      - name: allow-metrics
        action: allow
        source: 10.0.0.0/8
        port: "9100"
        protocol: tcp
cargoship_bastion:
  address: 10.0.0.1
  user: jump
  port: 22

A bastion is declared as its own variable rather than read out of ansible_ssh_common_args. Cargoship does not parse SSH argument strings, and an inventory that reaches its fleet through a jump host via ansible_ssh_common_args has to say so again here.

Misspelled variables are errors

A variable under the cargoship_ prefix that cargoship does not read is an error, and so is an unknown key inside one of the structured variables. Ansible has no notion of a variable belonging to anyone, so a misspelled cargoship_profil would otherwise sit in hostvars looking set and doing nothing, and a misspelled key would be dropped on the way in. A misspelled variable and an unset one are indistinguishable at install time, which is too late to find out.

Variables under the ansible_ prefix that are not in the table are ignored. There are hundreds of them, they belong to Ansible’s own connection plugins, and they are not cargoship’s to police.

Checking the result

The generated document is validated against the inventory schema before it is written, so a translation that produced something invalid fails here rather than ten minutes into an apply. Check it yourself as well, and read it: it is an ordinary cluster inventory, and it is the exact document cargoship installs from.

cargoship inventory from-ansible ./resolved.json -o ./inventory.yaml
cargoship validate ./inventory.yaml
cargoship apply ./package.tar.zst --config ./inventory.yaml --confirm

The generated file carries connection details and is written with mode 0600.

A playbook does not run these commands itself. The modules write and validate the same document, and the path they write it to is the inventory_path parameter described in Running Cargoship as an Ansible Module.

Running Cargoship as an Ansible Module

Cargoship runs inside a playbook as an Ansible module. The cargoship binary is the module: it is installed as a set of symlinks named cargoship_<action>, and a symlink’s name selects the action. There is no separate module package and nothing to install on the managed nodes.

The inventory a module takes is the one described in Generating an Inventory from Ansible – Ansible’s resolved groups and hostvars, plus a cluster block – and the group mapping and host variables documented there apply here unchanged. This guide covers the modules themselves: how the collection is installed, how a task is written, and what its result means. The parameter reference for each module and for the cluster role is generated from the collection and lives in the collection reference.

Ansible supplies the inventory and nothing else. It does not connect to the fleet, gather facts on it, or run a task per host. Every task runs on one management node outside the cluster – the node the package and images were staged onto – and cargoship opens every SSH connection itself from there. See choice-ansible-module for why the work is split that way.

Five modules ship, one per fleet action: cargoship_apply, cargoship_prepare, cargoship_engine_config_sync, cargoship_reset, and cargoship_kube_config. Package creation is not among them – it builds an artifact from a definition in a repository, which belongs in a pipeline rather than in a convergence run.

Working inventories and a playbook for each of the five are in ansible/examples, along with a script that translates an inventory without running a play.

- name: Converge engine configuration
  cargoship_engine_config_sync:
    package: /srv/staging/rke2-1.31.tar.zst
    inventory_path: /srv/staging/generated-inventory.yaml
    inventory:
      groups: "{{ groups }}"
      hostvars: "{{ hostvars }}"
      cluster:
        name: bubbles
        loadbalancer: bubbles-kc.test.com
    vault_password_file: /srv/staging/vault-pass
  delegate_to: localhost
  no_log: true

The task runs on the management node – connection: local when the Ansible controller is that node, delegate_to when they are separate. Cargoship connects to the fleet itself, from there.

Installing the collection

The modules live in the colonel_byte.cargoship collection. The RPM and deb packages install it to /usr/share/ansible/collections, which is on ansible-core’s default collections path, so on a management node that installed cargoship from a package there is nothing further to do.

Installing from a tarball or a checkout instead, install the collection, then point its module files at the binary. Each release carries a built colonel_byte-cargoship-<version>.tar.gz and a cosign bundle beside it; the collection is not published to Galaxy, because the node that installs it has no route to it.

cosign verify-blob --key cosign.pub \
  --bundle colonel_byte-cargoship-0.37.0.tar.gz.sigstore.json \
  colonel_byte-cargoship-0.37.0.tar.gz
ansible-galaxy collection install colonel_byte-cargoship-0.37.0.tar.gz
./hack/ansible-link-modules.sh ~/.ansible/collections/ansible_collections/colonel_byte/cargoship /usr/local/bin/cargoship

From a checkout, build the tarball first with hack/ansible-build-collection.sh ./bin/ansible, which is the same script the release pipeline runs.

That last step is not optional and has no equivalent in Galaxy’s own packaging. Ansible resolves a task name to a module file, so each action needs a file named after it; the files are symlinks to the one cargoship binary, which is what the packages create and what the script creates by hand. A collection installed without them fails with the module not being found.

The collection carries one action plugin per module. It runs inside ansible-playbook, on the interpreter Ansible is already running on, and does one thing: copy groups and hostvars into the module’s inventory parameter so you do not have to. Nothing is installed on the fleet, and running cargoship by hand still needs no Python.

It also accepts a parameters dict and merges it into the rest, which is how the role passes a caller-supplied set of parameters without templating the whole of a task’s arguments – something Ansible warns about, and rightly. A parameter given both directly and inside parameters is an error naming it.

The plugin forwards the four ansible_* connection variables listed in Generating an Inventory from Ansible and every cargoship_* variable, and drops the rest. A host’s resolved variables routinely carry credentials for things that are not this cluster, and a module’s parameters are written to a file on disk.

When defining profiles inside cargoship_cluster in YAML, note type constraints: concurrency (e.g. "1", "50%") and port definitions (ports[].port, e.g. "6443") are unmarshaled as strings by the underlying schema. Quote numeric strings in YAML to prevent JSON numeric unmarshaling failures.

Parameters

inventory takes the document described in Generating an Inventory from Ansible, groups and hostvars included. Everything else maps onto a flag of the command the module runs.

The parameter reference lives with the modules rather than here, so that it cannot drift from what the binary accepts: cargoship_apply, cargoship_prepare, cargoship_engine_config_sync, cargoship_reset, and cargoship_kube_config. Each page lists every parameter the module takes, its type, and the flag it renders. Modules is the index, and covers why the surfaces differ from one another.

Of the five, cargoship_engine_config_sync is the most Ansible-shaped thing cargoship does: it converges configuration across a fleet that is already installed.

A parameter the module does not know is an error naming it. A parameter left unset is left unset: the module passes no flag for it, so whatever your cargoship configuration file sets still applies. That is why label_nodes: false and omitting label_nodes are different.

Signature verification

public_key and verify are the package signature parameters, and they are the key-based ones only. Keyless verification identifies a signer against a Fulcio root and a transparency log, which needs network access a management node inside an airlock does not have. Verify a keyless-signed package with cargoship package verify before the play, where the flags and their exclusions are all available.

Key material

Key material is always named by a path, never given by value. Ansible writes a module’s parameters into a file on the managed node, and a password passed by value would be a password written to a file you did not choose the mode of. Set no_log: true on the task regardless: a binary module has no per-parameter no_log, so the task-level setting is what suppresses the arguments and the result.

The cluster role

The role is the shorter way to write the same task. It picks the module from cargoship_action, assembles the inventory parameter, and sets run_once, delegate_to, and no_log for you.

- name: Install the cluster
  ansible.builtin.include_role:
    name: colonel_byte.cargoship.cluster
  vars:
    cargoship_action: apply
    cargoship_package: /srv/staging/rke2-1.31.tar.zst
    cargoship_cluster:
      name: bubbles
      loadbalancer: bubbles-kc.test.com
    cargoship_args:
      vault_password_file: /srv/staging/vault-pass
      timeout: 45m

Every variable the role takes, with its default, is on role_cluster. Anything the role does not name a variable for goes in cargoship_args, which is passed to the chosen module verbatim.

Every task in the role carries run_once: true. Cargoship converges the whole fleet in one run, so a play over the fleet’s own inventory would otherwise run a full convergence once per host. It defaults cargoship_no_log: true to protect decrypted credentials and fleet inventories from terminal and CI logs, which is why cargoship_show_result exists: the debug task prints cargoship’s sanitized report without exposing secrets.

Check mode and changed

--check runs cargoship’s dry run. Phases opt into it one at a time – a phase that has not said how it behaves under a dry run is reported and not run – so a check-mode task connects, detects, gathers facts, and validates the hosts, and reports the rest as phases it would have run.

Under check mode, changed means what Ansible means by it there: a real run would change something. It is true when a phase that knows how to tell had work outstanding – a fleet whose engine configuration has drifted – and false when every such phase found nothing to do.

cargoship_kube_config is the exception. cargoship kube-config has no dry run, so under --check the module reports skipped: true and runs nothing at all. That is what Ansible does with a module that has declared it does not support check mode; a binary module has nowhere to declare it, so it says so in its result instead.

What changed is worth

changed is built from what the phases themselves report, and a phase has to opt in. cargoship.changedSignal says how much of the run is covered:

Today the engine configuration sync phases report and the rest do not, so an ordinary run reads partial. That is deliberate: a phase that has said nothing cannot make changed true, and it is not treated as having changed nothing either. KubeConfig and LabelNodes are the two in the undeclared list that can genuinely change something – the local kubeconfig and the node role labels – so if a handler of yours depends on either, gate on the result rather than on changed.

cargoship.phasesRan and cargoship.phasesPlanned name the phases the run executed and, under check mode, the ones it reported instead of running. Ansible sees one result for the whole fleet, so these stand in for the per-host detail a task-per-host module would give you.

The result

{
  "changed": true,
  "msg": "synchronised engine configuration across the fleet",
  "cargoship": {
    "module": "engine_config_sync",
    "inventoryPath": "/srv/staging/generated-inventory.yaml",
    "inventoryKept": true,
    "checkMode": false,
    "command": ["cargoship", "engine-config-sync", "..."],
    "phasesRan": ["Connect", "Detect OS", "Sync Registry Config Controller"],
    "changedSignal": "partial",
    "changedUndeclared": ["Connect", "Detect OS"]
  }
}

command is the command line the module ran, so a failure can be reproduced by hand on the management node. inventoryPath is the generated document. A run that fails leaves it on disk whether or not you named the path, because it is the first thing to look at when a failure reads like the wrong cluster; a run that succeeds removes it unless the path was yours.

Cargoship’s own logging goes to stderr, which Ansible captures and shows on failure. Per-host detail lives there, not in the result: Ansible sees one task for the whole fleet, not one result per host.

Live progress

A fleet-wide apply is one Ansible task that runs for several minutes, so the modules report where they are while they run. The action plugin prints one line per phase transition:

[cargoship] Phase 01/12: Connect to hosts [running]
[cargoship] Phase 01/12: Connect to hosts [done]
[cargoship] Phase 02/12: Detect host operating systems [running]

The counter is the phase’s position in the list for that module, so docs/phases/apply.md and its siblings read as the same sequence. A phase that fails is printed [failed], ahead of the failure Ansible itself reports.

None of this needs configuring. The action plugin creates a temporary status file, points the module at it, polls it while the module runs, and removes it afterwards whether the run succeeded or not.

Driving the binary directly gets the same progress through the same mechanism: set CARGOSHIP_STATUS_FILE to a path and cargoship rewrites that file as each phase starts and finishes, holding one JSON object – phase, index, total, status (running, completed, or failed), timestamp, and error on a failure. The file is replaced atomically on every transition, so a reader either sees the previous phase or the current one, never a half-written object. It is removed when the run finishes. Leave the variable unset and cargoship writes nothing.

File Override Guide

This guide explains how to redirect the files Cargoship downloads when creating a package, so a build can run against an internal mirror or against assets staged on disk ahead of time.

It is the file-download counterpart to the registry override guide, which covers the same idea for container images.

What a File Override Does

A distro definition declares two kinds of external artifact. Container images are pulled from OCI registries. Files and OS packages are downloaded over HTTP from whatever URLs .spec.config.files and .spec.config.os.files name – https://rpm.rancher.io/..., https://github.com/..., and so on.

--registry-override has always covered the first kind. A file override covers the second: it rewrites the front of a file’s source URL at package-create time, so the bytes come from a mirror instead of the upstream host. On a build host that cannot reach the public internet, this is the difference between building a package and hand-editing every URL in the distro definition first.

This only affects where create downloads from. What ends up in the package is byte-for-byte what the definition declared, because the declared checksum is still enforced – see Integrity below.

Setting an Override

Overrides are specified as source=target pairs, either on the command line or in the config file. source is a URL prefix. target is either a replacement URL prefix or a local directory.

Flag

cargoship create ./distro-defs --file-override https://rpm.rancher.io=https://mirror.example.com/rpm-rancher

The flag is repeatable, so several hosts can be redirected in one create:

cargoship create ./distro-defs \
  --file-override https://rpm.rancher.io=https://mirror.example.com/rpm-rancher \
  --file-override https://github.com=https://mirror.example.com/github-releases

A comma-separated value works too, which is occasionally easier to pass through a wrapper script:

cargoship create ./distro-defs --file-override https://rpm.rancher.io=https://mirror.example.com/rpm,https://github.com=https://mirror.example.com/gh

Config File

The same mapping can be set under .distro.create.file_override in your config file, so it doesn’t need to be repeated on every invocation:

distro:
  create:
    file_override:
      https://rpm.rancher.io: https://mirror.example.com/rpm-rancher
      https://github.com: https://mirror.example.com/github-releases
      https://pkgs.k8s.io: /srv/staged/pkgs-k8s

Flag values take precedence over the config file. They replace it rather than merging with it: passing any --file-override on the command line means the config file’s mappings are not used for that run, so a command line that overrides one host has to name every host it still wants redirected. This is the same behavior as --registry-override.

Building From a Local Directory

A target that is not an http:// or https:// URL names a directory of files already on disk, which lets a build run with no network at all and without standing up an internal HTTP server:

cargoship create ./distro-defs --file-override https://rpm.rancher.io=/srv/staged/rpm-rancher

The path under the source prefix is appended to the directory. A file declared as:

source: https://rpm.rancher.io/public/centos/9/x86_64/k3s-selinux.rpm

is then read from /srv/staged/rpm-rancher/public/centos/9/x86_64/k3s-selinux.rpm. Mirroring the upstream layout with wget --mirror, or with whatever your artifact store exports, is usually the least effort way to populate the directory.

A relative target is resolved against the working directory when the flag is parsed, not against the distro definition, so it means what it looks like it means from the shell you typed it in.

Prefix Matching

A source can be as broad as a host (https://github.com) or as narrow as a path prefix (https://github.com/rancher). When more than one override could match a file, the longest matching source wins:

cargoship create ./distro-defs \
  --file-override https://github.com=https://mirror.example.com/gh \
  --file-override https://github.com/rancher=https://mirror.example.com/rancher

Here, https://github.com/rancher/rke2/releases/... resolves against the more specific https://github.com/rancher override, while https://github.com/k3s-io/k3s/releases/... falls back to the broader one.

Matching is done on the parsed URL rather than on the raw string, and a path prefix has to end at a path separator. Both of those matter in practice:

• An override for https://github.com does not match https://github.com.example.invalid/..., which a plain string prefix would have captured.
• An override for https://github.com/rancher does not match https://github.com/rancher-dev/....

The scheme, host, and port all have to match exactly. An override for https://files.example.com does not apply to http://files.example.com or to https://files.example.com:8443.

A file whose source is already a local path is never overridden. There is nothing to redirect.

Integrity

Rewriting where a file comes from does not change what the file has to be.

Every overridden file is checked against the shasum its distro definition declares, exactly as it would be without the override. If a mirror serves a modified, corrupted, truncated, or simply out-of-date artifact, the build fails with a checksum mismatch naming the file, and nothing is written into the package. A file that fails for any reason – a failed download, a failed extraction, a missing local file – fails the whole create rather than being skipped.

A file that declares no shasum cannot be overridden. Cargoship refuses the build and names the file. Without a declared checksum there is nothing to compare a mirror’s bytes against, and “the file came from wherever this flag pointed” is not a property worth shipping in an offline package. If you hit this, add the upstream checksum to the distro definition; that is the fix, and it improves the definition whether or not you use an override.

When a file declares an extractPath, the override applies to the archive that is downloaded, and the shasum continues to be checked against the extracted file rather than the archive – unchanged from how extraction already worked.

Auditing a Built Package

A package built with file overrides records two things in its distro.yaml, and the difference between them is the point.

.build.fileOverrides is the configuration the build was given, alongside .build.registryOverrides:

build:
  fileOverrides:
    https://rpm.rancher.io: https://mirror.example.com/rpm-rancher
    https://github.com: /srv/staged/github

.build.fileSources is what that configuration actually did – one entry per file an override redirected:

build:
  fileSources:
    - path: files/0/k3s
      declared: https://rpm.rancher.io/public/k3s
      resolved: https://mirror.example.com/rpm-rancher/public/k3s
      override: https://rpm.rancher.io
      shasum: 0a15685b072d0afcc218eceea5a93216a6accb48ff9e122bbc53c643c87b4a21

The configuration alone cannot answer the questions an audit actually asks. An override can be configured and match nothing – the https://github.com entry above did not, since no file source started with it. And when several prefixes overlap, only the resolved entry tells you which one won for a given file. Each fileSources entry is self-contained: this file, from this place, verified against this digest.

Two properties worth knowing:

• A package built with no overrides has neither key, so it is byte-for-byte what it would have been before this feature existed.
• Entries are written in the order the files were staged, which is the order they appear in the definition, so --reproducible still produces identical output.

resolved names a path on the build host when the override pointed at a local directory, as in /srv/staged/github above. That discloses that much of the build host’s layout to anyone who reads the package. It is recorded deliberately – a provenance record that omits where the bytes came from is not one – but it is worth knowing before you stage assets under a path you would rather not publish.

None of this is what makes the package trustworthy. The enforced checksums are. This is the record of how it was built.

Host Firewall Configuration Guide

Cargoship configures the firewall on every node that runs one. It picks the firewall per node, from the node’s operating system and from what is running on it, so a single inventory can target a mix of Enterprise Linux hosts running firewalld, Debian or Ubuntu hosts running ufw, and hosts that manage nftables directly. Firewall management is opt-in: it only runs when cargoship apply is given the --firewall flag.

Every node cargoship manages gets three things: the private address of every other node in the cluster is trusted, the engine’s pod and service CIDR blocks are trusted, and the ports listed in .host.ports are opened. Anything beyond that comes from the rules in .host.firewall.rules.

Backends

Cargoship never runs ufw enable. A node whose ufw is inactive is left alone, because bringing up a default-deny firewall from a remote phase would cut the SSH connection cargoship is running over. Enable ufw yourself, with a rule that keeps SSH reachable, before pointing cargoship at the node.

A node whose only nftables content comes from kube-proxy or the CNI is deliberately not a match. Every node in a running cluster has a non-empty ruleset, so matching on that would claim hosts whose operator never configured a firewall at all.

Choosing a backend

The node’s operating system decides first. Each OS module names the firewall front end its distribution ships: firewalld on Enterprise Linux and SUSE, ufw on Debian and Ubuntu. Distributions that ship no front end – Alpine, Arch, CoreOS, Flatcar, Slackware – name none.

The second row is the deliberate part. An operator who installed a front end and left it down has made a decision about the node’s firewall posture, and cargoship does not take that decision away: it neither starts the service nor reaches past the stopped front end to write rules into the nftables underneath it, where the front end would overwrite them the moment it came up. Cargoship logs the node it skipped, and the apply continues.

This affects a stock Ubuntu node, which ships ufw installed and inactive. Run ufw enable on those nodes, with a rule that keeps SSH reachable, before cargoship apply --firewall.

The fallback match runs in the table order above, and nftables is last on purpose: firewalld and ufw are both front ends onto nftables, so a host running either would match the nftables backend as well. The nftables backend is for the hosts that never had a front end – Debian and Arch nodes configured by hand, and the minimal or immutable images such as CoreOS and Flatcar that ship no firewall front end at all.

Ports

The .host.ports list is the simple case, and it works the same on every backend. It opens a port, or an inclusive port range, to any source:

spec:
  hosts:
    - hostname: distro-kc01
      role: controller
      host:
        ports:
          - port: 6443
            protocol: tcp
          - port: 30000-32767
            protocol: tcp

Rules

The .host.firewall.rules list is the backend-neutral rule model. Each rule needs an action; every other field is a match, and an omitted match means “any”.

spec:
  hosts:
    - hostname: distro-kc01
      role: controller
      host:
        firewall:
          rules:
            - name: allow-metrics
              action: allow
              source: 10.0.0.0/8
              port: "9100"
              protocol: tcp
            - name: ingress-http
              action: allow
              direction: forward
              ingress: public
              egress: trusted
              port: "80"
              protocol: tcp

Rules on a profile

Rules can also be set on a profile, under .spec.config.profiles.<name>.host.firewall.rules. Every host that selects the profile gets them. This is the usual place for a rule that belongs to a role rather than to one machine, e.g. opening the API server port on every control-plane node.

spec:
  config:
    profiles:
      control:
        host:
          ports:
            - port: 6443
              protocol: tcp
          firewall:
            rules:
              - name: allow-metrics
                action: allow
                source: 10.0.0.0/8
                port: "9100"
                protocol: tcp
  hosts:
    - hostname: distro-kc01
      role: controller
      profile: control
      host:
        firewall:
          rules:
            - name: allow-backup
              action: allow
              source: 10.0.9.4
              port: "2049"
              protocol: tcp

The host above ends up with both rules. Firewall rules union with the profile’s rather than replacing them, so a host can add one rule of its own without giving up the baseline its profile sets. Rules are matched by name, and a host rule wins over a profile rule of the same name – that is how a host overrides one rule from its profile, or turns a profile allow into a deny for itself.

Rules with no name are matched by their fields instead, so a host that repeats a profile rule verbatim still only gets it once. Name your rules if you intend to override them.

The rest of .host still replaces rather than unions: a host that lists any ports of its own inherits none of its profile’s, and the same holds for the legacy policy map.

How rules land on each backend

The backends express the same rule differently, and two fields mean something slightly different on each.

Because ingress and egress name zones on firewalld and interfaces on the other two, a forward rule is the one part of the model that is not portable across a mixed-OS cluster. Set forward rules on a profile that only matches hosts of one OS family.

Idempotency

Every backend can be applied repeatedly without accumulating rules. On firewalld, cargoship writes the same ipset, service, and policy files each run and lets firewall-cmd skip what is already present. On ufw, cargoship records the rules it applied in /var/lib/cargoship/ufw.rules; on the next run, any rule in that file that the current inventory no longer asks for is deleted from ufw before the current rules are applied. Rules cargoship owns are tagged with a cargoship: comment, visible in ufw status, so they can be told apart from rules added by hand. Rules added by hand are never touched.

On nftables, idempotency needs no state file: the rendered ruleset is cargoship’s whole desired state, and it is loaded with an add table, delete table, and redefinition of inet cargoship in one transaction, so a rule the current inventory dropped is gone once the transaction commits. The add before the delete is what keeps the script working on a node cargoship has not configured before.

nftables and the cluster’s own rules

Kube-proxy in nftables mode, and every CNI, keep their service and network policy rules in the same subsystem cargoship writes to. Cargoship never flushes the ruleset and never reads or writes a table other than its own, because a global flush would break cluster networking until those components resynced.

Two consequences are worth knowing. Every base chain cargoship writes has an accept policy, the same reason cargoship never runs ufw enable: a default-drop policy applied from a remote phase would cut the connection cargoship is running over. And an accept in cargoship’s chain ends only that chain, not the netfilter hook, so a rule in an operator’s own table can still drop traffic cargoship allowed. Unlike firewalld’s trusted zone, cargoship’s trust is not the last word on a packet.

Cargoship’s rules survive a reboot through an include "/etc/cargoship/nftables.nft" line added to whichever boot-time file the distro reads, /etc/nftables.conf or /etc/sysconfig/nftables.conf. That file is appended to, once, and never rewritten. A host with neither file gets a warning rather than an error: the rules are loaded for this boot, but nothing will reload them at the next one.

Legacy firewalld policies

The older .host.policy map still works and is still firewalld-only. It maps a policy name to a firewalld policy written verbatim to /etc/firewalld/policies/<name>.xml:

spec:
  hosts:
    - hostname: distro-kc01
      role: controller
      host:
        policy:
          k8s-forward:
            target: ACCEPT
            ingress:
              name: public
            egress:
              name: trusted
            ports:
              - port: "80"
                protocol: tcp

Prefer a direction: forward rule under .host.firewall.rules for new configuration; it does the same thing on firewalld and also works on ufw and nftables hosts.

Adding a backend

A backend is a firewall.Backend implementation in pkg/firewall: a Name, a Detect that reports whether the backend manages a given node, an Installed that reports whether the firewall is present on the node at all, and an Apply that makes the node match a firewall.Plan. Register it in the backends list in pkg/firewall/firewall.go, in match order, and the apply phase picks it up with no further wiring.

A backend that is a distribution’s own front end also needs the OS modules for that distribution to return its Name from PreferredFirewall, in types/os/linux. That method is declared on each leaf OS module rather than on a shared base such as EnterpriseLinux, because those modules embed both their base and configurer.Linux at the same depth, which leaves a method promoted from either one ambiguous.

Importing Archives Guide

This guide explains how to convert an OCI Image Layout - a Skopeo oci-archive file, or an unpacked layout directory - into a native Cargoship package (.tar.zst) with cargoship import.

The Air-Gap Workflow

In an air-gapped workflow, packages are often published to an OCI registry on an internet-connected staging network, then copied to removable media using container tools like Skopeo.

Because Cargoship packages are multi-platform artifacts whose OCI manifest lists record the platform OS as "multi" (inherited from the OCI packaging specification), pass --override-os multi when pulling with Skopeo so its platform filter matches:

# Export the package from an OCI registry as an oci-archive
skopeo copy --override-os multi \
  docker://registry.example.com/cargoship/my-package:1.0.0 \
  oci-archive:my-package.tar:1.0.0

Once transferred across the airlock into the disconnected environment, cargoship import converts the archive into a native Cargoship package archive that cargoship apply can install.

Basic Usage

Run cargoship import on the archive:

cargoship import my-package.tar

The command:

1. Unpacks the archive, if it is not already a directory, and reads its index.json.
2. Selects the manifest matching the target architecture, descending into a nested index for a multi-arch package.
3. Extracts and verifies all package layers (binaries, engine configurations, container images, and checksums).
4. Writes the native compressed archive (cargoship-<name>-<arch>-<version>.tar.zst) into the current directory.

To write the native package to a specific directory, pass -o, --output:

cargoship import my-package.tar --output /srv/cargoship/packages/

Importing Unpacked Directories

If the archive has already been extracted on disk as an OCI layout directory (containing oci-layout, index.json, and blobs/), pass the directory path directly:

cargoship import ./extracted-oci-dir/ -o ./build/

Other Tools That Write an OCI Layout

Any tool that writes an OCI Image Layout can feed cargoship import. Two common ones:

# oras: copy a package out of a registry into a layout directory, or into a layout tar
oras cp --to-oci-layout registry.example.com/cargoship/my-package:1.0.0 ./my-package:1.0.0
oras backup --output my-package.tar registry.example.com/cargoship/my-package:1.0.0

# crane: --format=oci writes a layout directory (its default, tarball, does not work - see below)
crane pull --format=oci registry.example.com/cargoship/my-package:1.0.0 ./my-package

Why There Is No docker-archive Support

cargoship import reads an OCI Image Layout only. A Docker image archive, the format docker save and crane pull --format=tarball write, cannot carry a Cargoship package, for two independent reasons:

• No tool can produce one. A Cargoship package is an OCI artifact with a custom config media type (application/vnd.cargoship.config.v1+json). Skopeo refuses to write it as a docker-archive, failing with unsupported image-specific operation on artifact with type "application/vnd.cargoship.config.v1+json"; oras has no docker-archive output at all; and the Docker daemon cannot pull an artifact with a non-image config, so docker save never sees one.
• The format cannot carry what the import needs. A docker-archive’s manifest.json records only Config, RepoTags, and Layers. There is no field for OCI annotations, so org.opencontainers.image.title - which is how a package layer declares whether it is distro.yaml, checksums.txt, or an image blob - is dropped. Even a hand-built docker-archive would arrive with its layers unidentifiable.

Use oci-archive or an OCI layout directory instead. Every tool above can write one.

Verifying Signatures

If the package was signed before export, pass --key and --verify to validate its Cosign signature as part of the import:

cargoship import my-package.tar --verify=always --key ./cosign.pub

Multi-Architecture Packages

A distro package normally targets one CPU architecture. A package can instead target several, so that one artifact installs a cluster whose control-plane and worker hosts do not all run the same architecture. This guide covers declaring the architectures, selecting files per architecture, and how such a package is built, published, pulled, and applied.

Declaring Architectures

metadata.architectures lists every architecture the package targets:

apiVersion: colonel-byte.dev/v1alpha1
kind: Distro
metadata:
  name: rancher-k3s-multi
  version: 1.36.4-k3s1
  architectures:
    - amd64
    - arm64

The supported values are amd64, arm64, and riscv64. Listing the same architecture twice is an error, as is listing one cargoship does not support.

metadata.architecture, the scalar field, stays valid for a package targeting a single architecture and means exactly the same thing as a one-entry list. Set one or the other, not both: when both are set the list wins. A definition that sets neither takes the architecture of the machine running cargoship create.

Selecting Files Per Architecture

Most upstream projects publish one binary per architecture, at a different URL and with a different checksum. Write one file entry per architecture, each landing on the same target, and let selector.arch decide which one a host receives:

files:
  - source: https://github.com/k3s-io/k3s/releases/download/v1.36.4%2Bk3s1/k3s
    target: /usr/local/bin/k3s
    executable: true
    shasum: 835873f37245fc615f547a2fe2af9402a347875f13fa64a1f136de644955ea3f
    selector:
      package: binary
      arch:
        - amd64
  - source: https://github.com/k3s-io/k3s/releases/download/v1.36.4%2Bk3s1/k3s-arm64
    target: /usr/local/bin/k3s
    executable: true
    shasum: c920706346d5ad4e5cd3c7bf1bb09ce71ebe07fec829e513e40f1caf98aed8bb
    selector:
      package: binary
      arch:
        - arm64

An entry with no arch selector goes to every host, the same way an entry with no profile selector goes to every role. That is what the architecture-independent files – unit files, scripts, noarch RPMs – want.

selector.arch may only name architectures the definition declares. A file selecting x86_64 in a package targeting amd64 fails at create time rather than silently never uploading. example/k3s-multi, example/rke2-multi-cni-canal and example/rke2-multi-cni-cilium are complete definitions written this way, generated from the same templates as the single-architecture examples, and the example/upstream-cilium, example/upstream-canal and example/upstream-flannel flavors are generated the same way, installing Kubernetes from upstream packages for both architectures plus the CNI each one bakes in.

Building

cargoship create builds every architecture the definition declares into one package. Images are pulled for each of them, so a two-architecture package with images takes roughly twice as long to build and is roughly twice the size.

The archive is named cargoship-<name>-<arch>-<version>.tar.zst, and a package covering more than one architecture takes multi in the architecture position, since no single architecture describes what it carries:

cargoship-rancher-k3s-multi-multi-1.36.4-k3s1.tar.zst

Narrowing With --architecture

--architecture (-a) narrows a definition to one of the architectures it declares, which is how you build a single-architecture package from a multi-architecture definition:

cargoship create example/k3s-multi/v1_36/v1.36.4-k3s1 -a arm64

It narrows; it does not override. Asking for an architecture the definition does not declare is an error, because the file entries for that architecture were never written. For the same reason it cannot re-target a definition that names a single architecture: -a arm64 against an architecture: amd64 definition fails rather than producing an amd64 package labelled arm64. A definition that names no architecture at all is the one case where the flag chooses freely, since there is nothing to contradict.

Narrowing does not invalidate the entries for the architectures left behind. A definition declaring amd64 and arm64 narrowed to amd64 still carries its arm64 file entries, and those entries are still checked against the full declared list.

Publishing

A package is one set of blobs whatever the architecture count, so it publishes as a single manifest. The image index tagged at the package version is what makes it resolvable per architecture: it lists that one manifest digest once for every architecture the package covers.

--tag names the tag instead. On publish it changes the OCI reference alone, leaving the package’s own metadata.version as built, which is what a promotion between registries wants: the same package published under staging and then under a release tag. On create it goes further and overrides metadata.version itself, so the package is built as that version and the index it publishes to is tagged accordingly. Both work per architecture the same way the version does, so an amd64 and an arm64 package given the same tag resolve under one index.

cargoship publish cargoship-rancher-k3s-multi-multi-1.36.4-k3s1.tar.zst oci://registry.example.com/distros

Ordinary platform resolution therefore works from either architecture, and every consumer lands on the same blobs. Publishing to a tag that already holds an index leaves the entries for architectures the package does not cover alone, so publishing an amd64 package and then an arm64 one of the same version leaves both resolvable under the one tag.

Because example packages and templates evolve as new features and settings are introduced, packages published under a general release tag may be updated across Cargoship releases. If an environment requires an immutable, consistent image, either build the definition locally using cargoship create or pull the package using its precise tag containing the short commit SHA (e.g. <version>-<job>-<short git commit>).

Pulling

cargoship pull resolves the architecture of the machine it runs on, or the one given with -a, against the index:

cargoship pull oci://registry.example.com/distros/rancher-k3s-multi:1.36.4-k3s1 -o .

A multi-architecture package resolves from any architecture it covers, and the pulled archive is identical whichever one resolved it.

When nothing in the index matches and the package holds a single manifest, that manifest is pulled anyway: it is the only thing a matching platform could have resolved to, and an arm64 package is worth having on an amd64 workstation to inspect, sign, or push elsewhere. Pulling a package is not running it. An index holding several distinct manifests and none for the requested architecture is still an error, since choosing between those is what platform matching is for.

Applying

Each host in the inventory receives the files its own architecture selects, so a mixed-architecture cluster installs from the one package: an arm64 worker gets the arm64 binary, an amd64 controller gets the amd64 one, and both get the entries with no arch selector. Images are likewise exported per host architecture, so each host loads a tarball holding the images built for it.

Package Values

A cargoship package ships with a set of values: Helm-style configuration, addressed by dotted paths, that a cluster can override without rebuilding the package. Values reach the engine configuration in two ways – structural mappings, and Go templates that read .Values – and they are also available to the files a package uploads and to the actions that build it.

This guide covers authoring values in a package, overriding them from a cluster inventory or the command line, and choosing between mappings and templates.

Declaring values in a package

Values live under spec.values of a distro.yaml:

spec:
  values:
    files:
      - values.yaml
      - overrides/prod.yaml
    schema: values.schema.json

files are merged in order, key by key, with a later file winning over an earlier one. Each entry is a path relative to the package definition, an absolute path, or a URL. Cargoship copies them into the package as values/<index>-<basename>, so two files that share a base name do not collide.

schema is a JSON Schema document the merged values must satisfy. Cargoship checks the values against it while building the package and refuses to build when they do not match, so a typo is caught by whoever builds the package rather than by whoever installs it. The schema must not use $ref. Set "additionalProperties": false on the root object: without it, a misspelled top-level key in a cluster inventory is silently ignored instead of rejected.

A values file is ordinary YAML:

cilium:
  encryption:
    enabled: false
  hubble:
    ui:
      enabled: false
      ipv6: false

Overriding values

Values are resolved from three sources, each winning over the one before it:

1. The values files the package ships with.
2. spec.config.values in the cluster inventory.
3. One or more --values <file> flags on the command line.

The inventory carries the values a cluster always wants:

kind: Cluster
spec:
  config:
    values:
      cilium:
        encryption:
          enabled: true

The flag carries the ones that change between runs:

cargoship apply ./package.tar.zst --config inventory.yaml --values ./encryption-off.yaml

--values may be given more than once, with a later file winning over an earlier one, and it is accepted by cargoship apply, cargoship prepare, and cargoship engine-config-sync. There is no -f shorthand.

Merging is per key, not per document. An override that sets cilium.encryption.enabled leaves every other key under cilium as the package defined it.

The merged values are checked against the package’s schema again at install time, so an inventory that sets a key the package does not accept fails before anything is written to a host.

That check happens when the package is installed, which is late to learn that a key is misspelled. cargoship schema inventory --package <package> composes the package’s values schema into the inventory schema, so an editor completes and checks spec.config.values while the inventory is being written:

cargoship schema inventory --package ./package.tar.zst -o ./inventory.schema.json

--package accepts a package source directory as well as a built one, so a package author can point an editor at a definition that has not been built yet. The composed schema describes the override subtree on its own, while cargoship validates the overrides merged with the values the package ships, so required is dropped from it – a key the package’s own values.yaml supplies is not required of the operator. It catches an unknown key, a wrong type, and a name outside an enum or pattern; it does not claim to reproduce install-time validation. See the inventory guide for wiring it into an editor.

cargoship validate runs that same composed schema without an editor, which is the form that fits CI:

cargoship validate ./inventory.yaml --package ./package.tar.zst

Mappings

A mapping projects one value onto one place in the engine configuration:

spec:
  values:
    mappings:
      - source: .cilium.encryption.enabled
        target: .manifest.rke2-cilium.encryption.enabled

source is read out of the resolved values. target is written relative to spec.config.engine. Both paths must begin with a dot. A source the values do not define is left alone, so the package’s own engine configuration stands as the default.

Mappings are structural: the value keeps its YAML type, and nothing in the package has to be written as a template. They are the right tool when a value lands on exactly one key.

A mapping that cannot be applied – a path without a leading dot, or a target underneath a chart entry that is a YAML string rather than a map – is reported as a warning when the package is built, and again when it is installed. It does not fail the build. The feature is new, and a hard failure on a package that installs correctly today is the wrong first move.

Templates

A template reads .Values directly, anywhere in the engine configuration:

spec:
  config:
    engine:
      manifest:
        rke2-cilium:
          encryption:
            enabled: "{{ .Values.cilium.encryption.enabled }}"

A scalar that is entirely one template is re-typed after rendering, the same way Helm’s --set typing works, so the example above lands in the generated HelmChartConfig as a YAML boolean rather than the string "true". A scalar that mixes text and templating stays a string.

Rendering happens before the mappings are applied, and before the engine configuration is validated. Package-authored text is therefore what gets executed: a value supplied by a cluster inventory that happens to contain {{ is written through as literal text, never evaluated.

Conditionals

Templating can do the one thing mappings cannot: decide whether a block of configuration exists at all. Rendering walks the parsed structure one scalar at a time and never re-parses a document, so a conditional only works inside a chart entry written as a YAML block scalar:

spec:
  config:
    engine:
      manifest:
        rke2-cilium: |-
          kubeProxyReplacement: true
          encryption:
            enabled: {{ .Values.cilium.encryption.enabled }}
          {{- if .Values.cilium.hubble.ui.enabled }}
          hubble:
            enabled: true
            ui:
              enabled: true
          {{- else }}
          hubble:
            enabled: false
          {{- end }}

Both shapes are in the examples: example/rke2-cilium-vsphere spends its values through mappings, and example/rke2-multi-cni-cilium spends the same values through a templated block scalar.

Which to reach for

Use a mapping when a value has one destination and its type should survive untouched. Use a template when one value drives several keys, when the value needs reshaping on the way, or when the package has to emit or omit a whole block. A package may use both.

A chart entry carries more than its values

Everything above writes a chart entry under spec.config.engine.manifest as the chart’s Helm values and nothing else. An entry may instead be a wrapper, which names the values under a values key and says two more things about the chart:

spec:
  config:
    engine:
      manifest:
        rke2-cilium:
          enabled: true
          images:
            - docker.io/rancher/mirrored-cilium-cilium:v1.20.2
            - docker.io/rancher/mirrored-cilium-hubble-ui:v0.13.6
          values: |-
            kubeProxyReplacement: true

Why images belong to a chart

imageConfig.images is one flat list, and nothing about it records which chart an image is for. So a cluster that turns Hubble’s web interface off is still sent mirrored-cilium-hubble-ui and -ui-backend, and a cluster running no vSphere CSI is still sent its ten driver images - exported to a tarball, pushed over SSH to every node, and left on disk. On an air-gapped link that is the expensive kind of waste.

Naming an image under the chart that needs it is what lets cargoship skip it. A chart with enabled: false has none of its images exported or uploaded, and because the upload phase removes image tarballs it did not write this run, disabling a chart on a later apply takes its images back off the hosts.

The package still carries every image. cargoship create pulls all of them and a published package holds all of their blobs, whatever any chart’s enabled says - a package whose contents depended on the cluster it was going to be installed on would be a different package per cluster. The saving is in what crosses the wire to the hosts, not in the size of the tarball an operator carries across the air gap.

A chart that is not enabled also gets no HelmChartConfig, for the same reason a disabled one does not: there is nothing to configure when the images are not on the node.

Deciding it from an inventory

enabled is an ordinary place for a value to land, so a cluster decides it:

spec:
  values:
    mappings:
      - source: .addons.vsphere.csi.enabled
        target: .manifest.rancher-vsphere-csi.enabled

Mappings are applied before any phase runs, so by the time the upload phase picks images the answer is in hand.

A chart is only switchable if the package says so. enabled defaults to true, and so does an entry that omits it – including every entry written in the bare form. A cluster reaches spec.config.engine only through a mapping or a template the package itself declares; a cluster’s own engine section carries node labels and taints and nothing else. So a chart whose entry has no enabled key, and no mapping onto one, cannot be turned off by an inventory or by --values at all. Exposing the switch is the package author’s decision, and not exposing it is how a package says a chart is not optional.

Note that enabled is about the chart’s images, not about whether the engine installs it – the disable key below is that, and the two are not wired together. See todo-chart-disable-image-gating for what that currently costs.

Both shapes are accepted, and one is going away

An entry is read as a wrapper when it has a values key, and as the chart’s values themselves when it does not. That is the whole rule, and it is deliberately narrow: a chart’s own values may well have a top-level enabled or images key - cilium has enablePolicy, and rancher-vsphere-csi really does take an images list - so neither of those can tell the two shapes apart. The cost is that a chart whose values have a top-level values key cannot use the wrapper, and has to stay in the bare form.

Two consequences worth knowing:

• A typo in a wrapper key is silent. Because a bare entry is any mapping, enabledd: false is indistinguishable from a Helm value by that name. It validates, and the chart’s images ship. Nothing warns.
• The bare form is what v1beta1 drops. It is supported for as long as v1alpha1 is, and a package written today needs no change; a package written now for a chart that will grow images is better off in the wrapper.

Disabling bundled addons

RKE2 and K3s both install a set of charts of their own – ingress, a load balancer, metrics, DNS – and both are told to leave one out through a single disable key in config.yaml. Every example package exposes that key as a value, so which addons a cluster runs is a cluster’s decision rather than a packaging one:

# values.yaml, in the package
addons:
  disabled:
    - rke2-ingress-nginx

# distro.yaml, in the package
spec:
  values:
    mappings:
      - source: .addons.disabled
        target: .config.disable

An inventory names the charts it wants left out:

spec:
  config:
    values:
      addons:
        disabled:
          - rke2-ingress-nginx
          - rke2-traefik
          - rke2-traefik-crd

The list is replaced, not merged. Values merge per key, and a list is one value, so an inventory that sets addons.disabled decides the whole list. Repeat the entries the package disables by default – rke2-ingress-nginx above – or they come back.

This works because a mapping copies the value as it stands, lists included. Templating cannot produce a list: rendering re-types a fully templated scalar into a boolean, a number, or a string, never into a sequence. A value that has to reach the engine as a list has to arrive through a mapping.

The names are the chart names the engine itself uses, and which ones a build packages is a property of that build rather than of the engine: RKE2 1.37 carries rke2-gateway-api-crd and rke2-security-responder, RKE2 1.34 carries neither, and K3s calls its charts by bare names (coredns, servicelb, traefik, local-storage, metrics-server, runtimes). Rather than keep a list here that drifts from what is packaged, every example’s values.schema.json carries its own version’s charts as suggestions under addons.disabled, which an editor offers as completions. That list is generated from the engine’s source – see mage and thirdparty-src – so it is the vocabulary that build advertises. Read the schema next to the distro.yaml you are installing.

The suggestions are not the whole vocabulary. The engine’s --disable help text is where the list comes from, and it is not exhaustive: RKE2 bundles rke2-runtimeclasses and never names it there. A schema that rejected everything outside the list would reject a chart the engine would have honored, so addons.disabled accepts any chart name and the list only drives completion. An unknown name reaches config.yaml unchanged: cargoship warns that the build packages no such component and leaves the entry in place, since dropping it would quietly install the very chart the cluster asked to be without. A typo is visible in that warning rather than at validation time.

Two other things follow from disabling a chart:

• No HelmChartConfig is written for it. A package may configure a chart under spec.config.engine.manifest and still have it disabled by an inventory. Cargoship skips the manifest for a disabled chart rather than configuring something that will not be installed, and a file left over from an earlier run is removed the next time the node is synced. A chart whose entry sets enabled: false is skipped the same way, for the same reason - its images are not on the node either.
• Agents are unaffected. disable is a server-only key. It is dropped from an agent’s config.yaml along with every other controller-only key, and only controllers carry chart manifests in the first place.

Pod Security Admission levels

Every example package writes a Pod Security admission configuration, and the level it enforces is a value rather than a packaging decision:

# values.yaml, in the package
podSecurity:
  defaults:
    enforce: restricted
    audit: restricted
    warn: restricted

# distro.yaml, in the package
spec:
  values:
    mappings:
      - source: .podSecurity.defaults.enforce
        target: .podSecurity.plugins[0].configuration.defaults.enforce
      - source: .podSecurity.defaults.audit
        target: .podSecurity.plugins[0].configuration.defaults.audit
      - source: .podSecurity.defaults.warn
        target: .podSecurity.plugins[0].configuration.defaults.warn

Each key takes one of privileged, baseline, or restricted, which the schema enforces, and all three default to restricted. A cluster that has to run a workload the restricted profile rejects can lower one of them without rebuilding:

spec:
  config:
    values:
      podSecurity:
        defaults:
          enforce: baseline

The three are separate on purpose. enforce is the only one that rejects a pod; audit and warn record it and tell the client about it. Lowering enforce to baseline while leaving audit and warn at restricted runs the workload and still reports every pod that would not have passed, which is the shape to reach for while a workload is being brought up to the profile rather than exempted from it.

Only the levels are values. The -version keys, the exemptions, and the plugin itself stay with the package: an exemption list is a property of what the package installs – kube-system, rook-ceph, and zarf are exempted because the charts in the package need it – and a cluster that edited it would be deciding for components it did not choose. Anything beyond the three levels is a package edit.

What renders

Templating is deliberately not applied everywhere. Three surfaces render:

• spec.config.engine – always, without an opt-in. This is the subtree that becomes the engine’s configuration and its HelmChartConfig manifests.

• spec.config.files and spec.config.os.files – per file, when the entry sets template: true. It defaults to false, because most files are binaries or archives that a template pass would corrupt.

  spec:
    config:
      files:
        - source: audit-policy.yaml
          target: /etc/rancher/rke2/audit-policy.yaml
          template: true
  

  The file is rendered once, in place in the extracted package, before any phase uploads it.

• spec.actions.onCreate – per action, when the action sets template: true. This renders at build time, on the machine building the package, and covers the action’s cmd and its wait block.

spec.config.os.sysctl, spec.config.os.environment, spec.config.os.fapolicyd, and spec.config.os.selinux do not render.

A template that names a value the package does not define is an error, not an empty string, on every surface.

Rendered manifests on a running cluster

The HelmChartConfig manifests a template produces are written to the engine’s manifest directory, which the Rancher engines re-read on their own. Cargoship marks them as not requiring a restart: cargoship engine-config-sync compares them on disk, writes the drift in place, and logs the paths it wrote. No node is drained for a values change that lands only in manifests.

Available functions

Templates are rendered with the sprig-compatible function set from sprout, which is what a Helm chart author already expects: toYaml, upper, b64enc, default, quote, the arithmetic and list helpers, and the rest.

Four functions are removed: env, expandEnv, expandenv, and getHostByName. A package author writes the templates and an operator runs them, so leaving these in place would let a package read the operator’s environment into chart values, or resolve names against the operator’s DNS. Helm removes the same four for the same reason. They are removed rather than stubbed, so a package that uses one fails to parse instead of quietly rendering an empty string.

Five functions Helm defines and sprig itself lacks are added back: toToml, fromToml, toYamlPretty, fromYamlArray, and fromJsonArray. As in Helm, these report a parse failure in band – in the returned value – rather than failing the render.

Create-only functions

Four more functions are available to onCreate actions, and only there:

Pulling a missing artifact into the cache is the whole point of a create action, so these belong there. They are not available to values, manifests, files, or anything that runs at install time: a template that renders chart values should not be able to probe the deploy host or issue HTTP requests. A template that names one outside an action fails at parse time.

Each of these returns its error rather than a zero value, so a cache directory that cannot be read stops the build instead of reading as “the file is not there” and sending the package down the wrong branch.

Because the create-time function set is cargoship’s own, cargoship – not the vendored Zarf action runner – renders onCreate actions. Zarf still executes them, with its shells, retries, timeouts, and output capture unchanged, and .Constants and .Variables still resolve. Actions are rendered one at a time, in order, so a variable one action sets is readable by the next.

spec:
  actions:
    onCreate:
      before:
        - description: pull the chart
          template: true
          cmd: |
            {{- if not (cachedFileExists "charts/cilium.tgz") }}
            curl -sSLo {{ cachedFilePath "charts/cilium.tgz" }} {{ .Values.cilium.chartURL }}
            {{- end }}

One consequence of resolving values before the build runs: an onCreate action cannot produce a values file that the same build then reads. Values are resolved, schema-checked, and packaged before the first action runs.

Verifying a package

Build the package and read the rendered output back:

cargoship create ./example/rke2-multi-cni-cilium/v1_36/v1.36.4-rke2r1
cargoship apply <package> --config inventory.yaml --dry-run

Values are resolved, the schema is checked, and every surface is rendered before the first phase runs, so a bad value or a template that names a key the package does not define fails ahead of any change to a host. A dry run stops there.

Per-Profile Update Concurrency

This guide explains why a cluster admin may want to set a different concurrency limit per node profile, and how to configure it.

The problem with one global concurrency limit

-c/--concurrency and -w/--work-concurrency cap how many hosts, or how many workers, Cargoship touches at once, but that limit applies flat across the whole cluster. A cluster is rarely uniform, though. It often mixes roles with very different blast radii if something goes wrong mid-update:

• Infra nodes may run stateful services, ingress, or storage where taking more than one down at a time risks an outage or data unavailability.
• General worker nodes may be numerous, stateless, and behind a load balancer, where updating a quarter of them at once is safe and finishes far faster than one at a time.

A single global limit forces a tradeoff: set it low enough to protect the sensitive infra nodes, and worker upgrades crawl; set it high enough for fast worker upgrades, and infra nodes risk being updated too aggressively.

Setting concurrency per profile

Every profile under .spec.config.profiles accepts its own concurrency, which overrides the CLI’s -c/-w value for hosts using that profile only. It accepts either a fixed count or a percentage of the hosts that share the profile:

spec:
  config:
    profiles:
      infra:
        concurrency: "1"
      worker:
        concurrency: "25%"

With this configuration:

• Hosts with profile: infra are always updated one at a time, regardless of the -w flag value.
• Hosts with profile: worker are updated 25% at a time, rounded up, with a minimum batch size of 1 so a small worker pool never stalls at “0 at a time.”
• A profile that sets no concurrency (or a host with no profile) falls back to the -w flag value, same as before this feature existed.

A percentage is resolved against the number of hosts in that profile, not the whole cluster, so 25% on a 4-host worker profile means 1 host at a time, and 25% on a 40-host worker profile means 10 at a time.

This applies everywhere Cargoship batches worker operations: initializing, upgrading, draining, deleting, and uninstalling the engine.

Choosing values

• Use a fixed low count ("1", "2") for profiles running singleton or quorum-sensitive services, where losing more than N nodes at once breaks availability.
• Use a percentage ("25%", "50%") for horizontally scaled, stateless profiles where speed matters more than caution, and the remaining capacity can absorb the load while a batch updates.
• Use "100%" (or leave concurrency unset with -w 0) for profiles where all hosts can safely update simultaneously, e.g. a dev/test cluster.

Registry Override Guide

This guide explains how to redirect the images Cargoship pulls when creating a package, and how to authenticate to the resulting registry at apply time using an Ansible Vault-encrypted credential.

For the same idea applied to the files and OS packages a distro definition downloads over HTTP, see the file override guide.

What a Registry Override Does

By default, cargoship create pulls images from the registries referenced in your source manifests (e.g. docker.io, ghcr.io). A registry override rewrites the registry portion of an image reference at package-create time, so images are instead pulled from a mirror – for example an internal pull-through cache or an air-gapped registry.

This only affects where create pulls from. It doesn’t touch the cluster the package is later applied to; for authenticating the cluster’s container engine to a registry, see Authenticating to the Registry below.

Setting an Override

Overrides are specified as source=override pairs, either on the command line or in the config file.

Flag

cargoship create --registry-override docker.io=mirror.example.com

The flag is repeatable, so multiple registries can be overridden in one create:

cargoship create \
  --registry-override docker.io=mirror.example.com \
  --registry-override ghcr.io=mirror.example.com/ghcr

Config File

The same mapping can be set under .distro.create.registry_override in your config file, so it doesn’t need to be repeated on every invocation:

distro:
  create:
    registry_override:
      docker.io: mirror.example.com
      ghcr.io: mirror.example.com/ghcr

Flag values take precedence over the config file when both are set.

Prefix Matching

A source can be as broad as a registry (docker.io) or as narrow as a specific repository prefix (docker.io/library). When more than one override could match an image, the longest matching source wins:

cargoship create \
  --registry-override docker.io=mirror.example.com \
  --registry-override docker.io/library=mirror.example.com/library-cache

Here, docker.io/library/nginx resolves against the more specific docker.io/library override, while docker.io/someorg/app falls back to the broader docker.io override.

Authenticating to the Registry

Once images are being pulled from your mirror, the cluster’s container engine also needs credentials for it at apply time. This is configured separately, in the cluster inventory file’s .spec.config.registries (see the inventory guide):

spec:
  config:
    registries:
      - name: docker.io
        proxy:
          url: https://mirror.example.com:5000
        auth:
          user: myuser
          pass: hunter2

name is the registry the images were originally referenced from, and proxy.url is the mirror the engine pulls from instead. Cargoship writes both into /etc/rancher/<engine>/registries.yaml: the pair becomes a mirrors entry, and the credentials become a configs entry keyed by the mirror’s host and port. proxy.url may carry a scheme and a path. A URL given without a scheme is completed to https://, and the host is taken from it for the configs key, which is what the engine matches on.

Cargoship writes registries.yaml as root with mode 0640, so the engine’s group can read the mirror list while the credentials in it stay off limits to everyone else. Cargoship does not copy user and pass into registries.yaml as they are given. It encodes the pair into a single credential – base64 of user:pass – and writes that as the engine’s auth directive, so the password does not sit on every node as plain text. Base64 is an encoding, not encryption, so treat the resulting file as a secret regardless.

Use token on its own when the registry issues one directly. It is a different credential from a password, not another way to spell one, so Cargoship writes it as the engine’s identity_token directive rather than as basic auth. A token given alongside user and pass wins:

        auth:
          token: abc123

proxy is optional. Leave it out to authenticate a registry Cargoship pulls from directly, without redirecting anything – a private registry that hosts your own images, say:

      - name: nexus.example.com
        auth:
          user: myuser
          pass: hunter2

That writes a configs entry keyed by nexus.example.com and no mirrors entry. An entry that carries neither a proxy.url, credentials, nor tls configures nothing, and apply rejects it by name rather than writing an empty entry. So does a proxy block with no url in it, and a registry listed twice, which would otherwise mean the second entry quietly replacing the first.

The rest of the entry is checked the same way, when the inventory file is read and before apply connects to anything. name is the registry part of an image reference, so it carries no scheme and no repository path: docker.io, not https://docker.io and not docker.io/library. (* is the exception – engines read it as every registry.) proxy.url has to name a host and use http or https, and any credentials in it belong in auth instead. A proxy.rewrite pattern has to compile as a regular expression and rewrite to something, since the engine compiles it on the node, where failing means a failed pull rather than a rejected document. user and pass are a pair; half of one authenticates nothing and reaches you as a 401 from the registry rather than as the missing half it is.

Several registries may share one mirror – a single Nexus proxying docker.io, ghcr.io, and quay.io under different paths is the usual shape – and cargoship writes one configs entry for the host they have in common. Those entries have to agree: if two registries resolve to the same host but ask for different credentials or different TLS settings, only one of them could survive into the file, so apply reports the conflict by name instead of picking one.

Encrypted credentials are the exception. Both age and Ansible Vault salt each encryption, so encrypting one password twice produces two different blocks, and two entries carrying the same credential would read as a mismatch for as long as they are still ciphertext – which is the whole time this check runs, since it runs before anything is decrypted. So when every credential field both entries set is encrypted, and neither sets token, cargoship takes them as agreeing rather than reporting a conflict that exists only in the ciphertext. Everything else is compared as written: plaintext credentials that differ still conflict, differing TLS settings still conflict, and so does a token on either side, encrypted or not. A token is a whole credential by itself, so two of them cannot be assumed to be one credential encrypted twice.

Writing pass: hunter2 in plaintext works, but puts a real credential in the inventory file. Cargoship also accepts an encrypted value in user, pass, token, or tls.ca, in either of two formats: an Ansible Vault block starting with $ANSIBLE_VAULT, or an age block starting with -----BEGIN AGE ENCRYPTED FILE-----. The header tells them apart, so nothing has to be told which format a file uses, and a file part-way through a migration between them applies the same as one that is not. Either is decrypted automatically when the package is applied. The rest of this page uses Ansible Vault; see the age guide for the age format and its keys.

Registry TLS

A registry serving a certificate the host does not already trust needs a tls block. It takes paths to files already on the host:

spec:
  config:
    registries:
      - name: docker.io
        proxy:
          url: https://mirror.example.com:5000
        tls:
          caFile: /etc/pki/ca-trust/source/anchors/mirror-ca.pem
          certFile: /etc/ssl/certs/mirror-client.pem
          keyFile: /etc/ssl/private/mirror-client-key.pem

caFile verifies the registry’s certificate; certFile and keyFile are the client certificate the registry authenticates the host with, and go together. Setting insecureSkipVerify: true turns certificate verification off for that registry – it makes the connection trivially interceptable, so prefer distributing the CA and verifying against it.

Distributing that CA to every host beforehand is often the annoying part, so ca takes the PEM-encoded certificate inline instead:

        tls:
          ca: |
            -----BEGIN CERTIFICATE-----
            MIIDdzCCAl+gAwIBAgIEbGVhZjANBgkqhkiG9w0BAQsFADBaMQswCQYDVQQGEwJV
            ...
            -----END CERTIFICATE-----

Cargoship writes it to /etc/cargoship/tls/<host>.crt on each host – <host> being the same host the configs entry is keyed by, with anything outside A-Za-z0-9._- replaced by an underscore – and sets caFile to that path for you. The certificate travels with the cluster configuration, so a rotated CA reaches the nodes the same way a changed mirror does: apply sees the file drift, then drains, rewrites, and restarts each node in turn.

Set ca or caFile, not both. apply rejects an entry that sets both, and one whose ca is not a PEM certificate, naming the registry. A certificate is public, so encrypting one buys nothing, but a ca given as an Ansible Vault value is accepted and decrypted like any other – a document vaulted as a whole should not have to be picked apart. The certificate is checked once it is decrypted, which is the first point at which there is a certificate to look at.

Cargoship owns /etc/cargoship/tls outright: every file in it was written for a registry entry. Drop the ca from an entry, or drop the entry itself, and the next apply removes the certificate that was written for it along with the reference to it, rather than leaving it on every node for however long the cluster lives.

Keeping the Nodes in Step

apply compares what it would write against what is already on each node, and syncs only the nodes that differ. Both halves of a file count: contents, and the mode it is written with. A registries.yaml that someone has since widened to 0644 is rewritten the same as one with the wrong mirror in it, since the mode is what keeps the credentials in it off limits.

Syncing a node means draining it, rewriting the files, restarting the engine, and uncordoning it once it is ready again – one node at a time. The log line before each drain names the files that drifted and why, so a cluster-wide rewrite is legible while it happens.

That matters on upgrade. Cargoship 0.21 changed how registries.yaml is written: keys under mirrors and configs are quoted, an endpoint given without a scheme is completed to https://, a user and pass pair is encoded into a single auth credential, and the file is written 0640 instead of 0600. None of that changes what the engine does, but all of it changes the file, so the first apply after upgrading rolls through every node in the cluster once. Plan for it the way you would plan for any rolling restart.

Encrypting the Credential

Use cargoship vault-encrypt to produce the encrypted value. It reads the plaintext from an argument, from stdin, or – if stdin is a terminal – prompts for it with hidden input so the secret is never echoed or left in shell history:

cargoship vault-encrypt --vault-password-file ./vault-pass.txt
Value to encrypt:
$ANSIBLE_VAULT;1.1;AES256
62306432326630316632646366363136303161316635343463306637643137646336363634363338
...

Paste the resulting block into the inventory file:

spec:
  config:
    registries:
      - name: mirror.example.com
        auth:
          user: myuser
          pass: |
            $ANSIBLE_VAULT;1.1;AES256
            62306432326630316632646366363136303161316635343463306637643137646336363634363338
            ...

Applying with the Vault Password

cargoship apply needs the same vault password to decrypt the credential at run time, supplied the same way as encryption – via --vault-password-file, or the CARGOSHIP_VAULT_PASSWORD environment variable if the flag is omitted:

cargoship apply --vault-password-file ./vault-pass.txt cluster.tar.zst

If a registry has a vault-encrypted credential and neither the flag nor the environment variable resolves a password, apply fails with an error naming the registry and the field – auth.user, auth.pass, auth.token, or tls.ca – rather than silently treating the ciphertext as a literal username or password. So does a password that does not match the document, or a tls.ca that decrypts to something that is not a certificate. All of it is checked as soon as the password is resolved, before the first host is connected to, so a wrong password costs you an error message rather than a half-configured cluster.

Removing a Host from the Cluster

This guide explains what happens when you delete a host from your Cargoship config, why an apply stops rather than reconciling the removal, and how to actually remove the machine.

What an apply does with a removed host

Nothing, and that is deliberate. Every phase after the fact-gathering ones reads .spec.hosts and acts on what it finds there, so a host you delete from the config becomes invisible to all of them. The machine keeps running the engine and stays joined to the cluster while the apply that was supposed to remove it reports success.

An apply catches this instead of walking past it. Right after it gathers facts, and before it changes anything, it lists the nodes joined to the cluster and compares them to the hosts in the config. If the cluster holds a node no host accounts for, the apply stops:

the cluster holds nodes the config does not: add the host back to the config,
run `cargoship install reset` against it, or pass --allow-unmanaged-nodes to
apply anyway: worker3 (worker)

Each node is named with its role, because a leftover controller is the more dangerous case. The check is read-only, so --dry-run runs it too, which is where you want to find out about a removal you did not intend.

A node is matched to a host by any identifier they share: the node’s name or any address it reports, against the host’s hostname, private address, or connection address. That is deliberately generous, since a false positive would stop an apply on a working cluster – it means a node whose name you overrode with node-name in the engine config still matches its host through its address. If the cluster cannot be reached at all, the check warns and the apply continues, because failing to reach it is not evidence that a host was removed. The node list is read with kubectl on a controller over the existing SSH connection, so the check works on a cluster whose firewall admits nothing but SSH from outside.

Why apply refuses instead of reconciling

Removing a node properly is two jobs, and an apply can only do one of them.

Draining a node and deleting its Node object needs the node’s name, which the API server will happily give us. Uninstalling the engine – stopping the service, removing the packages, deleting the data directory and certificates – needs an SSH connection to the machine, and the address, user and key for that lived in the hosts entry you just deleted. An apply has no memory of previous runs, so it has no way to reach a machine the config no longer describes.

Doing only the first half would be worse than doing nothing, because it looks like the removal worked. The machine keeps its certificates and keeps trying to rejoin, and if it was a controller it stays an etcd member: the cluster looks smaller while quorum is still counted against a member nobody can reach.

So an apply reports the gap and leaves the cluster alone.

Removing a host in OpenTofu

In OpenTofu, mark the host as state = "absent" in your cargoship_cluster resource:

resource "cargoship_cluster" "prod" {
  # ...

  hosts = {
    controller1 = {
      address  = "10.0.0.11"
      role     = "controller"
      key_path = "~/.ssh/id_ed25519"
      profile  = "control"
    }

    # worker3 is marked for removal:
    worker3 = {
      address  = "10.0.0.31"
      role     = "worker"
      key_path = "~/.ssh/id_ed25519"
      state    = "absent"
    }
  }
}

One tofu apply does the whole removal:

1. The node is drained and deleted from the cluster, through a controller that is staying. The run refuses rather than guessing if every running controller is itself marked absent – removing all of them is a teardown, and tofu destroy is what does that.
2. Cargoship connects to 10.0.0.31 over SSH, stops the engine and uninstalls it.
3. Every other host is left alone, and the apply then converges them as usual.
4. The host’s removed attribute becomes true.

Leave the entry where it is. removed is what tells later applies the work is done, so they neither repeat the teardown nor try to reach a machine that may since have been decommissioned. Delete the entry whenever it suits; nothing depends on it going, and deleting it changes nothing on any host.

If the removal fails, the apply stops there and says so. The entry stays in state with removed still false, which is deliberate: the machine is still running and still joined, and that entry holds the only address and key path that can reach it. Fix the cause and apply again. The rest of the convergence does not run, because converging on top of a half-removed cluster would report success over a node that is still in it.

What a destroy does with the markers

Nothing, beyond reading them. tofu destroy tears down everything the cluster still holds: a host marked absent whose removal failed is included, because the machine is still running and still joined, and one whose removal finished is left out, because reaching for a decommissioned machine would fail. The markers are not something to clean up before destroying.

If the machines are OpenTofu resources too and are being destroyed in the same run, consider retain_on_destroy = true – draining and uninstalling a node that is about to be deleted is minutes spent on a result nobody sees. See the provider’s Terragrunt guide.

Removing the machine by hand (CLI)

With the CLI, use targeted reset with --target-hosts:

$ cargoship reset --config ./cargoship-config.yaml --distro rke2 --target-hosts worker3 --confirm

Cargoship automatically selects a surviving running controller as the leader to delete worker3 from the cluster, then uninstalls the engine only on worker3, leaving your surviving controllers and workers untouched. After the targeted reset finishes, delete the host block from cargoship-config.yaml.

Removing a controller is the same command with more rules attached, and a run that targets two of them is refused rather than left to etcd. See Removing a controller.

Removing a controller

A worker leaves the cluster by being drained, deleted and uninstalled. A controller does that and also gives up an etcd member, so the order matters and the run is more constrained.

Cargoship stops the engine on the target before deleting its node. That is what makes the deletion stick: k3s and RKE2 remove the etcd member when the Node object is deleted, but only once the engine behind it has stopped, and an engine that is still running re-registers the node seconds later. The one exception is a removal that leaves a single controller, where the member being removed has to still be up to form the majority of two that commits its own removal – there the engine stays running through the deletion and is uninstalled immediately after.

One controller per run. A run that keeps the cluster and targets two running controllers is refused. Each removal is a raft reconfiguration that needs a majority of the membership it starts from; the second one in a run would start from three members with one already stopped, and taking the next one down leaves one of two, which hangs with the cluster unavailable rather than failing cleanly. Removing them in separate runs is safe, because the cluster is whole again at the start of each.

Removing the first controller

This section is about k3s and rke2. On upstream there is nothing to do: kubeadm is given controlPlaneEndpoint: <load_balancer> at init and every host – controllers included – joins through apiServerEndpoint: <load_balancer>, so no host holds the first controller’s name. The removed controller lingers in the API server’s certSANs until the next apply re-renders them, which changes nothing.

On k3s and RKE2 there is nothing special about the first controller at runtime either – it is the first in the host list, re-elected on every run, and it holds no state the others do not. Three things point at it by name, and only one of them needs attention:

So the step that makes it safe is re-rendering config.yaml on the controllers that stayed, which cargoship apply does: it re-elects the first controller from the remaining hosts and writes the new server: to every one of them. The engines are not restarted for it, which is the point – the file is correct again before anything reads it.

In OpenTofu this is already one operation. tofu apply removes the host and then converges what is left, in that order, in the same run.

With the CLI, the targeted reset and the apply are two commands, and the apply is not optional:

$ cargoship reset --config ./cargoship-config.yaml --distro rke2 --target-hosts controller1 --confirm
$ cargoship apply ./package.tar.zst --config ./cargoship-config.yaml --confirm

Between them the surviving controllers hold a join address that no longer resolves to a machine. They keep serving, and a reboot in that window is what turns it into an outage.

Two things Cargoship does not do for you:

• The load balancer. load_balancer is a name you own – a VIP, a DNS record, an HAProxy backend list. If it still routes to the controller you removed, a share of every API call fails. Update it in whatever manages it.
• A quorum check against live etcd. The refusals above count controllers from the configuration and from whether their engine answers, not from etcd’s own view of the membership. Removing a controller from a cluster that is already one member down is a removal from a membership that cannot commit it, and nothing here will say so. Confirm the cluster is healthy first.

When the extra nodes are deliberate

A cluster can hold nodes Cargoship never joined, and refusing on those would block every apply on a working setup. Pass --allow-unmanaged-nodes to downgrade the refusal to a warning:

$ cargoship apply ./package.tar.zst --config ./cargoship-config.yaml --allow-unmanaged-nodes --confirm

It is also available as distro.allow_unmanaged_nodes in the Cargoship config file, and as DISTRO_DISTRO_ALLOW_UNMANAGED_NODES in the environment. Cargoship still leaves those nodes alone either way; the flag only chooses whether their presence is an error or a log line.

Inventory Configuration Guide

This guide explains how to author a cluster inventory file for bootstrapping or upgrading clusters with Cargoship.

Basic Structure

A basic inventory file defines the cluster’s metadata, global configuration, profiles, and individual target hosts. Start with the following template:

---
# yaml-language-server: $schema=https://raw.githubusercontent.com/colonel-byte/cargoship/refs/heads/main/schema/cluster-v1alpha1-schema.json
kind: Cluster
metadata:
  name: bubbles

The .metadata.name field sets the cluster name. Cargoship uses this to configure the context name in the resulting kubeconfig (e.g., bubbles).

Editor Support

The yaml-language-server comment on the first line is what makes an editor complete and check the file as you write it. The URL above reads the schema from GitHub’s default branch, which is convenient and wrong in two situations: an air-gapped machine cannot fetch it at all, and yaml-language-server says nothing when a fetch fails, so the file silently stops being checked; and a machine that can fetch it is checking against unreleased main rather than the release it is running.

cargoship schema writes the schema out of the binary, so it is the schema that build validates against and it needs no network:

cargoship schema inventory -o ./cluster-v1alpha1-schema.json

Then point the inventory at the local copy:

---
# yaml-language-server: $schema=./cluster-v1alpha1-schema.json
kind: Cluster
metadata:
  name: bubbles

Package Values

The .spec.config.values section overrides the values the distro package was built with. It is the one part of an inventory whose vocabulary belongs to the package rather than to cargoship, so the schema above leaves it untyped – and a hosted schema never could do better:

spec:
  config:
    values:
      addons:
        disabled:
          - rke2-ingress-nginx

Pass --package to compose the package’s own values schema into the inventory schema, and the block completes and checks like the rest of the file:

cargoship schema inventory --package ./package.tar.zst -o ./inventory.schema.json

--package takes anything cargoship apply takes – a tarball, an oci:// or https:// reference – or a package source directory, so it works before the package is built. The composed schema describes the overrides on their own, while cargoship validates them merged with the values the package ships: it catches an unknown key, a wrong type, or a name outside an enum, and does not reproduce install-time validation. See the package values guide for what a package may expose and how the merge works.

Checking an Inventory

An editor is not the only place this check belongs. Cargoship unmarshals an inventory without strict key checking, so a misspelled key is dropped rather than reported: a file that says loadbalancr: parses cleanly and installs a cluster with no load balancer address. cargoship validate runs the same schema over a file with no editor and no network:

cargoship validate ./inventory.yaml

It reports every problem rather than the first, so one pass is enough to fix a file:

inventory.yaml does not match the inventory schema:
  spec.config: Additional property loadbalancr is not allowed
  spec.config: loadbalancer is required
  spec.hosts.0.role: must be one of the following: "controller", "worker"

The schema is chosen from the document’s own kind, so a directory of inventories and package definitions can be checked in one run. A cargoship config file declares no kind and has to be named:

cargoship validate ./inventories/*.yaml
cargoship validate --kind config ./cargoship-config.yaml

--package works here too, and checks .spec.config.values against the package’s own schema with the same caveat as above:

cargoship validate ./inventory.yaml --package ./package.tar.zst

This is a check you run, not one cargoship runs for you. apply does not validate the inventory against the schema before installing; it reads the file the way it always has. Put cargoship validate in CI, or in front of an install, where a typo is cheap to fix.

Global Configuration

The .spec.config section configures cluster-wide settings, such as load balancer endpoints:

spec:
  config:
    loadbalancer: bubbles-kc.test.com

The loadbalancer address is required. Cargoship adds this to the TLS Subject Alternative Names (SANs) for the Kubernetes API server. This can be a Round-Robin DNS record pointing to your control-plane nodes, or an external load balancer like an AWS NLB.

Node Profiles

The optional .spec.config.profiles section defines reusable groups of node configurations (e.g., control, infra, or worker). Profiles simplify management by applying standard node labels, taints, or host firewall rules across matching hosts.

spec:
  config:
    profiles:
      control:
        host:
          ports:
            - port: 6443
              protocol: tcp
          firewall:
            rules:
              - name: allow-metrics
                action: allow
                source: 10.0.0.0/8
                port: "9100"
                protocol: tcp
        engine:
          labels:
            adrp.xyz/purpose-control: "true"
          taints:
            - CriticalOnly=True:NoExecute

Target Hosts

The .spec.hosts array is the main body of the inventory. It defines each host node, its connection details, role, and profile:

spec:
  hosts:
    - hostname: distro-kc01
      ssh:
        address: 10.1.2.3
        user: root
        port: 22
        keyPath: ~/.ssh/id_ed25519
      profile: control
      role: controller

Host Firewall

The optional .host.firewall section, on a host or on a profile, declares firewall rules cargoship applies to the node. Cargoship detects whether the node runs firewalld, ufw, or nftables directly, and renders the same rules onto any of them. A host’s own rules union with its profile’s, so the host below gets allow-metrics from the control profile as well as its own allow-backup. See the firewall guide for the rule model and the per-backend details.

spec:
  hosts:
    - hostname: distro-kc01
      role: controller
      profile: control
      host:
        firewall:
          rules:
            - name: allow-backup
              action: allow
              source: 10.0.9.4
              port: "2049"
              protocol: tcp

Signing Packages

This guide explains how Cargoship signs and verifies packages. It covers key pair generation, the three points where you can sign, and verification.

A Cosign key pair is the only signing method. Keyless (Fulcio/OIDC) signing and verification, and cloud KMS key references, were removed: all of them need to reach a cloud endpoint, and the management node Cargoship runs from is air-gapped. If you need keyless back, say so on issue #848.

What Gets Signed

A Cargoship package is a .tar.zst archive. It contains a distro.yaml manifest, a checksums.txt file, and the image and file layers.

Cargoship signs distro.yaml only. The signing step sets build.signed: true in the manifest. It then signs the manifest bytes with Cosign and writes the signature beside the manifest as distro.bundle.sig, a Sigstore bundle.

One signature covers the whole package. distro.yaml records metadata.aggregateChecksum, the checksum of checksums.txt. checksums.txt lists a checksum for every layer in the package. Signing does not modify the checksums.

Signing is optional. Unsigned packages build, publish, pull, and apply normally. Verification then has nothing to check.

Generating a Cosign Key Pair

Cargoship does not generate keys. It uses keys in Cosign’s format. Use the cosign CLI:

cosign generate-key-pair

The command prompts for a password. It writes two files into the current directory:

• cosign.key – the encrypted private key. Keep this file secret. Treat it like any other signing credential.
• cosign.pub – the public key. Give this file to everyone who verifies your packages.

To skip the prompt in CI, set the password in the environment first:

COSIGN_PASSWORD='...' cosign generate-key-pair

Restrict the private key file to the signing user:

chmod 600 cosign.key

Keeping the Key Off Disk

--signing-key accepts a local file path, or env://NAME to read the PEM out of an environment variable. The environment form keeps the private key off the build host’s filesystem, which is what a CI pipeline wants.

export COSIGN_PRIVATE_KEY="$(cat cosign.key)"
export COSIGN_PASSWORD=...
cargoship sign ./my-package.tar.zst --signing-key env://COSIGN_PRIVATE_KEY

--key takes the same two forms when verifying, so a public key can come from env://COSIGN_PUBLIC_KEY as well as from a file.

Cloud KMS references – awskms://, gcpkms://, azurekms://, hashivault://, openbao:// – are not supported. Each resolves a key by reaching a cloud endpoint, which an air-gapped management node cannot do. Passing one fails naming the scheme rather than reporting a missing file.

Signing a Package

You can sign a package at three points. Each point accepts the same --signing-key and --signing-key-pass flags.

At Create Time

cargoship create ./distro-defs --signing-key ./cosign.key

Cargoship prompts for the key password when you omit --signing-key-pass. Use --confirm to skip the prompt in a non-interactive environment. The password must then come from --signing-key-pass, the config file, or the environment.

cargoship create ./distro-defs --signing-key ./cosign.key --signing-key-pass "$COSIGN_PASSWORD" --confirm

At Publish Time

publish signs an unsigned package as it pushes to a registry. It also re-signs a signed package with a different key.

cargoship publish ./build/cargoship-rancher-rke2-amd64-1.0.0.tar.zst oci://ghcr.io/my-org \
  --signing-key ./cosign.key --confirm

Use this form for a two-stage pipeline. One job builds the package. A second job holds the key material and signs.

As a Separate Step

cargoship sign signs an existing package without a rebuild. The source is a local tarball or an OCI reference.

cargoship sign cargoship-rancher-rke2-amd64-1.0.0.tar.zst --signing-key ./cosign.key

--output sets the destination of the signed package. Cargoship applies a default when you omit the flag. For a local source, the default is the source directory. For an OCI source, the default is the repository part of the source reference. The output can also be an OCI URL. Cargoship then signs and publishes in one step.

cargoship sign oci://ghcr.io/my-org/my-package:1.0.0 --signing-key ./cosign.key --output ./signed/

cargoship sign ./my-package.tar.zst --signing-key ./cosign.key --output oci://ghcr.io/my-org/signed-packages

Re-signing

Cargoship refuses to sign a package that already has a signature. It reports package is already signed, use --overwrite to re-sign. Use --overwrite to replace the existing signature.

cargoship sign ./my-package.tar.zst --signing-key ./new-cosign.key --overwrite

Add --verify=always --key ./old-cosign.pub to check the existing signature against the old key first. Use this form for key rotation. It proves the package is the one you expect before the new signature replaces the old one.

Verifying a Package

Every command that loads a package accepts --verify: sign, publish, pull, apply, prepare, and engine-config-sync. The flag takes one of three modes.

Key-Based Verification

Pass the public key with --key or -k.

cargoship pull oci://ghcr.io/my-org/my-package:1.0.0 --verify=always --key ./cosign.pub

Verification on the Install Path

apply, prepare, and engine-config-sync verify the package before they touch any host. They accept the same flags as pull, and they read the same config keys.

cargoship apply ./cargoship-distro-amd64.tar.zst --config ./cluster.yaml --confirm \
  --verify=always --key /etc/cargoship/cosign.pub

Set verify: always and public_key in the config file to apply this policy to every install on the host. See Configuration File and Environment Variables.

Verification runs while Cargoship loads the package. A failure stops the command before it configures a node.

Configuration File and Environment Variables

Set signing and verification options in cargoship-config.yaml to avoid repeating them on every command. The distro.verify and distro.public_key keys apply to every command that loads a package, including apply.

distro:
  # verification defaults, applied to any command that loads a package
  verify: always
  public_key: /etc/cargoship/cosign.pub
  publish:
    signing_key: /etc/cargoship/cosign.key
    signing_key_password: hunter2

Every key also reads from the environment. Use the DISTRO_ prefix and the full config path, with each . replaced by _.

export DISTRO_DISTRO_PUBLISH_SIGNING_KEY=./cosign.key
export DISTRO_DISTRO_PUBLISH_SIGNING_KEY_PASSWORD="$COSIGN_PASSWORD"
export DISTRO_DISTRO_PUBLIC_KEY=./cosign.pub

Note the doubled prefix. DISTRO_ is the environment prefix. The second DISTRO is the distro section of the config file.

Command-line flags take precedence over the config file and the environment.

signing_key_password in the config file puts a plaintext secret on disk. Use the environment variable instead, and env:// for the key itself, so neither the key nor its password is written to the build host.

Recommended CI Pattern

Use this pattern for a pipeline that builds and signs with a stored key.

env:
  COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
  COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}

# ...

- run: |
    cargoship create ./distro-defs -o ./build \
      --signing-key env://COSIGN_PRIVATE_KEY \
      --signing-key-pass "$COSIGN_PASSWORD" \
      --confirm

    cargoship publish ./build/cargoship-*.tar.zst oci://ghcr.io/my-org \
      --verify=always --key ./cosign.pub

--verify=always on the publish step matters. The step fails instead of pushing a package whose signature does not validate against the public key you distribute.

Vault Encryption

This guide explains how Cargoship encrypts registry credentials in a cluster configuration with Ansible Vault, and how to read them back out. It covers the four fields Cargoship decrypts, the cargoship vault commands, and the password-rotation workflow.

Ansible Vault is one of two formats Cargoship reads. The other is age, which encrypts to a set of public keys instead of a shared password – see age-encryption. The same commands write both, one configuration can hold both, and vault rekey moves a configuration from one to the other. Everything below describes the Ansible Vault side.

What Cargoship Decrypts

A cluster configuration holds registry credentials in plain sight. Encrypting them lets you commit the file.

Cargoship decrypts exactly four fields per registry, and only these four:

Decryption happens during an apply, when Cargoship writes the engine’s registry configuration. A field that does not carry the $ANSIBLE_VAULT header is passed through untouched, so a configuration can mix encrypted and plaintext values freely.

A CA certificate is public and does not need encrypting. Cargoship accepts an encrypted one anyway, so that a document can be vaulted as a whole without the parts that did not have to be causing a failure.

Encrypting any other field produces a document Cargoship can load but never unwraps: the ciphertext reaches the host verbatim, as if that were the literal value. vault encrypt-path warns when you ask for such a path, but does not refuse - see Encrypting a Value Already in a File.

Supplying the Password

Every vault command, and every command that applies a configuration, resolves the password the same way and stops at the first that is set:

1. --vault-password-file, a path to a file holding the password.
2. The CARGOSHIP_VAULT_PASSWORD environment variable.
3. The ANSIBLE_VAULT_PASSWORD environment variable.

A trailing newline in a password file is stripped, so a file written by echo works as expected.

Cargoship never prompts for the vault password. If none of the three is set, the command fails rather than treating the password as empty.

Restrict the password file to the user that runs Cargoship:

chmod 600 vault-pass.txt

The Commands

cargoship vault encrypt [VALUE]
cargoship vault encrypt-path FILE YAML_PATH [YAML_PATH...]
cargoship vault encrypt-file FILE
cargoship vault decrypt [VALUE]
cargoship vault decrypt-path FILE YAML_PATH [YAML_PATH...]
cargoship vault decrypt-file FILE
cargoship vault rekey FILE

The encrypt and decrypt pair work on a value and print to stdout. The -path pair work on named values inside a configuration file and rewrite the file in place. The -file pair work on every registry credential in a configuration at once, and are what you want most of the time. rekey moves a whole configuration from one vault password to another, or re-salts it under the one it has – see Rotating the Vault Password.

YAML_PATH is a path into the document, not a path on the filesystem: .spec.config.registries[0].auth.pass names a value inside FILE, the way jq or yq would address it. The leading $ that go-yaml uses is optional, so $.spec..., .spec..., and spec... all name the same value. Quote it in your shell – it contains [ and ].

The -path commands take as many of them as you like after FILE. The file is written once, after every value has been rewritten, so a path that is missing or in the wrong state fails the run without leaving the file half-done. Naming the same value twice – including as two different spellings of one path – is an error rather than a second pass over it.

Encrypting a Value

vault encrypt takes the value as an argument, on stdin, or at a hidden prompt when stdin is a terminal:

cargoship vault encrypt my-registry-password --vault-password-file ./vault-pass.txt

printf my-registry-password | cargoship vault encrypt --vault-password-file ./vault-pass.txt

cargoship vault encrypt --vault-password-file ./vault-pass.txt < ./registry-token.txt

Passing a secret as an argument leaves it in your shell history and in the process list. Prefer stdin or the prompt on a shared machine.

The output is a multi-line $ANSIBLE_VAULT block that you then paste into the configuration yourself, at the right indentation. vault encrypt-path does that part for you.

Encrypting a Value Already in a File

vault encrypt-path encrypts the plaintext the file already holds at a YAML path, and writes it back as a block scalar:

cargoship vault encrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./vault-pass.txt

Name several paths to encrypt them in one pass, which is the way to vault values encrypt-file does not cover – anything outside a registry’s credentials, such as an x-tra block of your own:

cargoship vault encrypt-path ./cluster.yaml '.x-tra.test.user' '.x-tra.test.pass' --vault-password-file ./vault-pass.txt

Given this configuration:

    registries:
      - name: harbor # our mirror
        auth:
          user: admin
          pass: hunter2 # rotate me

the command rewrites only that one value:

    registries:
      - name: harbor # our mirror
        auth:
          user: admin
          pass: |- # rotate me
            $ANSIBLE_VAULT;1.1;AES256
            31333438393936323663373461353533373034663339316335386139363535383531643464613539
            6235646237326332663931643964633165323934646363390a353136626562643632326566353765
            3961

Everything else is preserved byte for byte: comments, key order, quoting elsewhere in the document, and the trailing comment on the key’s own line. The file stays yours rather than becoming a re-rendering of itself.

Two flags change what it does:

• --dry-run prints the resulting document to stdout and leaves the file untouched.
• --force encrypts a value that is $ANSIBLE_VAULT already, wrapping it a second time. Without it, an already-encrypted value is an error, so that re-running the command cannot bury the plaintext under a layer nothing unwraps.

If a YAML_PATH is not one of the four fields in What Cargoship Decrypts, the command warns and proceeds:

WRN cargoship does not decrypt this field at apply time, so the value will reach the host as ciphertext

Decrypting a Value

vault decrypt is the inverse of vault encrypt. It takes the ciphertext as an argument or on stdin:

cargoship vault decrypt --vault-password-file ./vault-pass.txt < ./encrypted-token.txt

The plaintext is written to stdout as it is, with a trailing newline added only when it does not already end in one. A multi-line value such as a PEM certificate can therefore be redirected straight into a file:

cargoship vault decrypt --vault-password-file ./vault-pass.txt < ./encrypted-ca.txt > ./ca.pem

Unlike vault encrypt, there is no hidden prompt. Ciphertext is neither secret nor a single line, so a terminal with nothing piped into it is reported as a mistake.

Decrypting a Value Already in a File

vault decrypt-path puts the plaintext back into the document, in place of the ciphertext:

cargoship vault decrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./vault-pass.txt

It takes several paths too, and like encrypt-path writes the file once at the end:

cargoship vault decrypt-path ./cluster.yaml '.x-tra.test.user' '.x-tra.test.pass' --vault-password-file ./vault-pass.txt

Encrypting a value and decrypting it again gives back the file that went in, byte for byte.

The plaintext is written in whichever scalar style holds it faithfully: plain where YAML allows it, a literal block for something multi-line such as a PEM certificate, and a quoted string for anything the other two would change on the way back in – a value with a leading space, a trailing space, a #, or one that would otherwise read back as a number or a boolean.

The command warns that it has just removed the protection the file relied on:

WRN the file now holds this value in plaintext

--dry-run prints the resulting document to stdout and leaves the file untouched, which is the way to check that a value decrypts without writing the plaintext to disk at all:

cargoship vault decrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./vault-pass.txt --dry-run

There is no --force. A value that is not $ANSIBLE_VAULT has nothing to decrypt, and rewriting it would be a no-op that still rewrote the file, so that is an error.

Encrypting a Whole Configuration

Naming each path gets tedious once a configuration has more than one registry, and it is easy to miss one. encrypt-file walks every registry and encrypts the four fields in the table above:

cargoship vault encrypt-file ./cluster.yaml --vault-password-file ./vault-pass.txt

It reports each path it rewrote and a count at the end. Everything else in the document is left exactly as it was, the same way encrypt-path leaves it.

A field that is absent, empty, or encrypted already is skipped rather than treated as an error. Two things follow from that, and both are the point of the command:

• Running it over a configuration that was vaulted by hand, or half-vaulted and then abandoned, finishes the job without disturbing what is already there.
• Running it twice changes nothing the second time, so it is safe in a script or a pre-commit hook.

This is what makes the ordinary credential rotation easy. Paste the new registry password into the file in the clear, leave the vaulted username alone, and run encrypt-file: it picks up the one value you changed and does not re-wrap the rest. Because Ansible Vault salts every encryption, re-wrapping them would change every one of those lines in the diff for no reason.

A credential encrypted with age is skipped too, since this command never moves a value between the two formats. That skip is reported rather than passed over in silence:

WRN left this credential as it was: it is age-encrypted, and encrypt-file does not move a
    credential between formats; run 'cargoship vault rekey' with an age identity and the new
    vault password to move it onto Ansible Vault  file=./cluster.yaml path=$.spec.config.registries[0].auth.pass

--dry-run prints the resulting document to stdout and leaves the file alone; warnings go to stderr, so the document it prints stays clean. --force re-encrypts values that are ciphertext already, wrapping them a second time – which is almost never what you want, since an apply unwraps only one layer.

Decrypting a Whole Configuration

cargoship vault decrypt-file ./cluster.yaml --vault-password-file ./vault-pass.txt

The inverse: every vaulted registry credential in the file becomes plaintext again, and anything that is not encrypted is skipped. An encrypt-file followed by a decrypt-file under the same password gives back the original document byte for byte.

If any value fails to decrypt, the command fails and the file is not touched at all – it does not leave you with half a configuration in the clear.

Shared Credentials (Anchors and Aliases)

A configuration that pulls from two names on the same host usually writes the credential once and points the second registry at it:

    registries:
      - name: docker.io
        auth: &auth
          user: robot
          pass: hunter2
      - name: test.io
        auth: *auth

All of the vault commands follow anchors and aliases. The value lives under the anchor, so that is what gets rewritten, and the alias is left as it is:

      - name: docker.io
        auth: &auth
          user: |-
            $ANSIBLE_VAULT;1.1;AES256
            ...
      - name: test.io
        auth: *auth

Both registries read the same ciphertext at apply time, which is what sharing the value meant in the first place. encrypt-file reports it once – count=2 for the shared user and pass above, not four – because there is one value behind each pair of paths. Naming the aliased registry yourself works too: encrypt-path ... '.spec.config.registries[1].auth.pass' rewrites the anchored value, since that is the value that path resolves to. Naming both registries in one encrypt-path run is the one thing to avoid; the second path is the value the first has already encrypted, so it fails as already encrypted.

An alias whose anchor is missing, or comes later in the file, is an error naming the alias. Nothing in this package reports a value it cannot reach as a value that was not there.

Merge keys work the same way. A registry that merges a shared block reads whatever that block holds, encrypted or not, and the keys it writes beside the merge are its own values, encrypted separately:

      - name: lab.test.local
        auth:
          user: lab-robot
          pass: correct-horse
        tls:
          <<: *internal-tls
          insecureSkipVerify: true

A merge can add keys to a block but never override one the anchor already sets – YAML forbids the same key twice in a mapping, and the configuration fails to load before cargoship sees it – so put in a shared block only what every user of it wants, and write what differs beside the merge.

test/e2e/noncluster/testdata/inventory-anchors.yaml is a complete inventory built this way, kept as a worked example and exercised by the end-to-end suite.

Rotating the Vault Password

cargoship vault rekey ./cluster.yaml --vault-password-file ./old-pass.txt --new-vault-password-file ./new-pass.txt

Every vaulted registry credential in the file moves to the new password in one command. The plaintext is never written to the file: each value is decrypted and encrypted again in memory, so there is no window in which the configuration on disk is readable, and nothing to remember to clean up if the command fails or the terminal goes away mid-rotation. --dry-run prints the result to stdout and leaves the file alone.

--new-vault-password-file is optional. Omit it and every value is re-wrapped under the password the file already carries:

cargoship vault rekey ./cluster.yaml --vault-password-file ./vault-pass.txt

That is a re-salt rather than a rotation, and it is logged as one. Ansible Vault salts each encryption, so every credential comes back as different ciphertext holding the same plaintext under the same password – useful when the ciphertext has been somewhere you would rather it had not been, or when a value was vaulted long enough ago that you want it rewritten, and it never puts the plaintext on disk. Naming a file that holds the old password does the same thing.

Unlike --vault-password-file, --new-vault-password-file has no environment fallback. The environment holds the password the file is vaulted under now, so falling back to it would report a rotation onto a password nobody asked to move to.

A value that is plaintext is skipped, and so is one that is empty or absent – rekeying does not encrypt anything that was not encrypted before. To pick up a newly added credential, run encrypt-file with the new password afterwards.

Rotate the whole file, not one value at a time. An apply decrypts all of a registry’s fields with a single password, so a configuration whose values were vaulted under two different passwords is one that no password can read. rekey refuses to create or perpetuate that state: if any encrypted value in the file cannot be read with the old password, it stops before writing anything and names the path. encrypt-file refuses the same way. But rotating path by path with decrypt-path and encrypt-path will walk you into it, since those commands only ever look at the one value you named.

Ansible Vault salts each encryption, so the ciphertext differs on every run even when the password and the plaintext are unchanged. A rekey produces a diff on every value it touches, and running it twice with the same pair of different passwords is not idempotent – the second run fails, because the file is no longer readable with the old password. A re-salt can be run as often as you like, since the password it reads with is the password it writes back.

Checking Before an Apply

An apply verifies every vaulted value as soon as it has resolved the password – before it connects to any host, and on a sync, before it starts draining nodes. A missing or wrong password fails the command immediately rather than part-way through a cluster change.

To check a configuration by hand without writing plaintext anywhere, use decrypt-file --dry-run and throw the output away. It decrypts every vaulted credential in the file and exits non-zero if any of them fails:

cargoship vault decrypt-file ./cluster.yaml --vault-password-file ./vault-pass.txt --dry-run > /dev/null

Interoperability with ansible-vault

Cargoship writes the Ansible Vault 1.1 AES256 format, so ansible-vault reads what Cargoship writes and Cargoship reads what ansible-vault writes:

cargoship vault encrypt hunter2 --vault-password-file ./vault-pass.txt > ct.txt
ansible-vault decrypt --vault-password-file ./vault-pass.txt --output - < ct.txt

One difference matters. ansible-vault encrypt_string tags its output with !vault:

pass: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  ...

Cargoship writes a plain block scalar with no tag, and its -path and -file commands reject a tagged value rather than strand the tag on a value that no longer matches it. Drop the !vault tag when moving a value across; the ciphertext underneath needs no change.

Notes

• cargoship vault-encrypt is the old spelling of cargoship vault encrypt. It still works and still prints a deprecation notice. Use the vault group instead.
• A failed command never touches the file. The rewrite goes to a temporary file alongside the original and is renamed over it, so an interruption cannot leave a half-written configuration.
• The file’s mode is preserved across a rewrite.

cargoship

cargoship

CLI for cargoship installs

cargoship COMMAND [flags]

Options

  -h, --help                help for cargoship
      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship apply - Apply a config file to bootstrap and upgrade a cluster
• cargoship create - Creates a Cargoship Package from a given directory or the current directory
• cargoship engine-config-sync - Sync engine config (registries, audit, and pod security) to a cluster, draining and restarting the engine service on any node whose config has drifted
• cargoship import - Converts an OCI Image Layout archive into a native Cargoship package
• cargoship inventory - Generates a cluster inventory from another source of truth
• cargoship kube-config - Get the admin kube-config for a control-plane node
• cargoship prepare - Prepares the nodes, including restarting the node if new kernel modules are enabled
• cargoship publish - Publish the Cargoship Package to an OCI registry
• cargoship pull - Pulls a Cargoship package from a remote registry and saves it to the local filesystem
• cargoship redact-receipt - Rewrites a run receipt so it can be attached to an issue
• cargoship reset - Reset a cluster, stopping, uninstalling, and removing all data for an engine
• cargoship schema - Writes out a JSON Schema for one of cargoship’s own file formats
• cargoship sha256sum - Generates a SHA256SUM for the given file
• cargoship sign - Signs an existing Cargoship distro package
• cargoship validate - Checks a cluster inventory, package definition, or config file against its schema
• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age
• cargoship verify - Verifies the signature on a Cargoship distro package
• cargoship version - Shows the version of the running binary

apply

cargoship apply

Apply a config file to bootstrap and upgrade a cluster

Synopsis

Bootstraps a cluster from a package and a cluster configuration, or upgrades one that is already running, by stepping through the apply phases against every host the configuration names. One command does both: the engine version already on each host is what tells an upgrade apart from an install, and a downgrade is refused rather than attempted, before any phase has written to a host. Pass –allow-downgrade when the move backwards is deliberate.

Cargoship opens every SSH connection itself, from the machine it runs on, and nothing is installed on a target host beyond what a phase uploads.

An apply never removes a node. A host deleted from the configuration leaves its node in the cluster and stops the run rather than having the difference reconciled, so that no machine is drained or uninstalled by a configuration edit alone. Pass –allow-unmanaged-nodes when the extra nodes were joined deliberately and cargoship should leave them alone.

This changes every host it is pointed at, so it needs –confirm. Pass –dry-run instead to connect to every host and run the preflight checks for real, reporting what the run would change without changing it.

cargoship apply [Distro Package] [flags]

Examples

# Bootstrap or upgrade a cluster from a package and a config file
$ cargoship apply ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm

# Decrypt vault-encrypted registry credentials with a password file
$ cargoship apply ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm --vault-password-file ./vault-pass.txt

# Upgrade workers 25% at a time instead of all at once
$ cargoship apply ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm --work-concurrency 25%

# Update /etc/hosts, the firewall, and fapolicyd on every node as part of the apply
$ cargoship apply ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm -H -F -f

# Add the node-role label to each node, and leave the local kubeconfig untouched
$ cargoship apply ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm --label-nodes --update-kubeconfig=false

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
      --allow-downgrade                   Continue when a host already runs an engine version newer than the one the package carries. A downgrade is refused by default, because an engine does not support being moved backwards and the data directory it leaves behind was written by the newer version. Set this when the move backwards is deliberate and the hosts are expected to survive it.
      --allow-unmanaged-nodes             Continue when the cluster holds a node that no host in the config accounts for. An apply never removes a node, so by default one left behind by a host deleted from the config stops the run. Set this when the extra nodes were joined deliberately and cargoship should leave them alone.
  -a, --architecture string               Architecture for OCI images and Zarf packages
  -c, --concurrency int                   Maximum number of hosts to configure in parallel, set to 0 for unlimited. (default 30)
      --config string                     Config file used to bootstrap a cluster.
      --confirm                           Proceed with the run. Without it, a command that would change a host reports what it needs and stops.
      --dry-run                           Report what would be done without changing any host. Connects to every host and runs the preflight checks for real, then lists the phases it did not run. Does not need --confirm.
  -F, --firewall                          Whether to update every host node's firewall configuration.
  -h, --help                              help for apply
  -H, --hosts                             Whether to update every host node's /etc/hosts file.
  -k, --key string                        Path to public key file for validating signed packages
      --kubeconfig string                 Path of the kubeconfig file to merge the admin creds for this cluster into. The file is created when it does not exist, and an existing one keeps every other cluster it holds. Defaults to the standard location: KUBECONFIG when set, otherwise ~/.kube/config.
      --label-nodes                       Whether to check and add the node-role.kubernetes.io/PROFILE label on cluster nodes. The phase reads the cluster's admin credentials off a controller itself, so this does not depend on --update-kubeconfig.
      --receipt-path string               Write a structured JSON record of the run to PATH: what ran, against which package, against which fleet, and what changed. The file is written whether the run succeeds or fails, and is created readable only by its owner. PATH may carry the placeholders {command} and {timestamp}, which expand to the command that ran and when it started, so a PATH set once in '.distro.receipt_path' gives every run its own file. It names every host in the cluster configuration, so run 'cargoship redact-receipt' over it before attaching it to a ticket.
      --timeout string                    Set the timeout for how long functions will last. (default "60m")
      --tmpdir string                     Specify the temporary directory to use for intermediate files (default "/tmp")
      --update-kubeconfig                 Whether to write the admin creds for this cluster to a kubeconfig file at all. (default true)
      --values stringArray                Path to a YAML values file overriding the values the package ships with. May be given more than once, with a later file winning over an earlier one, and all of them winning over the values in the cluster config file.
      --vault-password-file string        Path to a file containing the Ansible Vault password used to decrypt vault-encrypted registry credentials. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.
      --verify verifyMode                 Verify the Cargoship package signature. (default if-possible)
  -w, --work-concurrency string           Maximum number of workers that will be installed or updated in parallel, as a fixed count or a percentage (e.g. "25%"), set to 0 for unlimited. (default "0")
      --zarf-cache string                 Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

create

cargoship create

Creates a Cargoship Package from a given directory or the current directory

Synopsis

Builds an offline distro package from a definition directory – a distro.yaml and whatever sits beside it – producing one compressed archive that carries everything a cluster needs: the engine’s packages and binaries, the OCI images, the configuration templates, and the checksums over all of them.

The archive is fat on purpose. One package holds every architecture it targets, and the host’s own architecture selects what gets uploaded at apply time, so a mixed fleet installs from a single file.

Everything the definition declares is fetched while this runs, which is the one step that needs a network. –registry-override and –file-override redirect those fetches to an internal mirror or to files staged on disk ahead of time, which is how a package is built where there is no route to the upstream hosts. A declared shasum is enforced either way.

–signing-key signs the package as it is built. –reproducible pins the recorded build time so that identical inputs produce a byte-identical archive.

cargoship create [Dir] [flags]

Examples

# Build a package from the definition in the current directory
$ cargoship create .

# Build from another directory, writing the package to ./build/
$ cargoship create ./distro-defs -o ./build/

# Pull images through an internal mirror instead of their upstream registry
$ cargoship create ./distro-defs --registry-override docker.io=mirror.example.com

# Download files through an internal mirror instead of their upstream host
$ cargoship create ./distro-defs --file-override https://rpm.rancher.io=https://mirror.example.com/rpm-rancher

# Build from files staged on disk ahead of time, with no network at all
$ cargoship create ./distro-defs --file-override https://rpm.rancher.io=/srv/staged/rpm-rancher

# Sign the package as it is built, without prompting for the key password
$ cargoship create ./distro-defs --signing-key ./private-key.pem --confirm

# Build a byte-identical package on every run
$ cargoship create ./distro-defs --reproducible

Options

  -a, --architecture string         Architecture for OCI images and Zarf packages
  -c, --confirm                     Confirms package publish without prompting. Skips prompt for the signing key password
      --file-override strings       Redirect the file downloads a distro definition declares, as SOURCE=TARGET pairs where SOURCE is a URL prefix and TARGET is either a replacement URL prefix or a local directory of pre-staged files. Repeatable, and comma-separated values are accepted. When several sources match, the longest wins. The declared shasum is still enforced, and a file with no shasum is refused rather than fetched unverified from a mirror.
  -h, --help                        help for create
      --insecure-skip-tls-verify    Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
      --oci-concurrency int         Number of concurrent layer operations when pulling or pushing images or packages to/from OCI registries. (default 6)
  -o, --output string               Specify the output (either a directory or an oci:// URL) for the created Cargoship distro package. (default ".")
      --plain-http                  Allow OCI registry connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
      --registry-override strings   Specify a mapping of domains to override on package create when pulling images (e.g. --registry-override docker.io=dockerio-reg.enterprise.intranet)
      --reproducible                Pin the recorded package build time to a fixed value instead of the current time, so identical inputs produce a byte-identical package.
      --signing-key string          Private key for signing packages. Accepts either a local file path or env://ENV_VAR to read the key from an environment variable. Cloud KMS references are not supported.
      --signing-key-pass string     Password to the private key used for signing packages
      --tag string                  The tag or version to override the package metadata version with.
      --tmpdir string               Specify the temporary directory to use for intermediate files (default "/tmp")
      --zarf-cache string           Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

engine-config-sync

cargoship engine-config-sync

Sync engine config (registries, audit, and pod security) to a cluster, draining and restarting the engine service on any node whose config has drifted

Synopsis

Writes the engine configuration a package and a cluster configuration describe – registry mirrors and credentials, audit policy, and pod security – to every host the configuration names, and restarts the engine only where what is on disk no longer matches. A node whose configuration already agrees is left running untouched.

This exists because those three settings are the ones that change without the engine version changing, and a full apply is a heavier way to deliver them. Where a restart is needed the node is drained first, and the nodes are worked through at the rate –work-concurrency allows, so a cluster stays serving while its configuration moves.

Registry credentials encrypted with Ansible Vault or age are decrypted here, and the keys for every one of them are checked before the first host is connected to.

This changes every host whose configuration has drifted, so it needs –confirm. Pass –dry-run to report which nodes would be restarted without restarting one.

cargoship engine-config-sync [Distro Package] [flags]

Examples

# Sync registry, audit, and pod security config to every node that has drifted
$ cargoship engine-config-sync ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm

# Decrypt vault-encrypted registry credentials with a password file
$ cargoship engine-config-sync ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm --vault-password-file ./vault-pass.txt

# Restart at most 25% of the workers at a time
$ cargoship engine-config-sync ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm --work-concurrency 25%

# Sync without touching the local kubeconfig
$ cargoship engine-config-sync ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm --update-kubeconfig=false

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
      --allow-downgrade                   Continue when a host already runs an engine version newer than the one the package carries. A downgrade is refused by default, because an engine does not support being moved backwards and the data directory it leaves behind was written by the newer version. Set this when the move backwards is deliberate and the hosts are expected to survive it.
  -a, --architecture string               Architecture for OCI images and Zarf packages
  -c, --concurrency int                   Maximum number of hosts to configure in parallel, set to 0 for unlimited. (default 30)
      --config string                     Config file used to bootstrap a cluster.
      --confirm                           Proceed with the run. Without it, a command that would change a host reports what it needs and stops.
      --dry-run                           Report what would be done without changing any host. Connects to every host and runs the preflight checks for real, then lists the phases it did not run. Does not need --confirm.
  -h, --help                              help for engine-config-sync
  -k, --key string                        Path to public key file for validating signed packages
      --kubeconfig string                 Path of the kubeconfig file to merge the admin creds for this cluster into. The file is created when it does not exist, and an existing one keeps every other cluster it holds. Defaults to the standard location: KUBECONFIG when set, otherwise ~/.kube/config.
      --label-nodes                       Whether to check and add the node-role.kubernetes.io/PROFILE label on cluster nodes. The phase reads the cluster's admin credentials off a controller itself, so this does not depend on --update-kubeconfig.
      --receipt-path string               Write a structured JSON record of the run to PATH: what ran, against which package, against which fleet, and what changed. The file is written whether the run succeeds or fails, and is created readable only by its owner. PATH may carry the placeholders {command} and {timestamp}, which expand to the command that ran and when it started, so a PATH set once in '.distro.receipt_path' gives every run its own file. It names every host in the cluster configuration, so run 'cargoship redact-receipt' over it before attaching it to a ticket.
      --timeout string                    Set the timeout for how long functions will last. (default "60m")
      --tmpdir string                     Specify the temporary directory to use for intermediate files (default "/tmp")
      --update-kubeconfig                 Whether to write the admin creds for this cluster to a kubeconfig file at all. (default true)
      --values stringArray                Path to a YAML values file overriding the values the package ships with. May be given more than once, with a later file winning over an earlier one, and all of them winning over the values in the cluster config file.
      --vault-password-file string        Path to a file containing the Ansible Vault password used to decrypt vault-encrypted registry credentials. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.
      --verify verifyMode                 Verify the Cargoship package signature. (default if-possible)
  -w, --work-concurrency string           Maximum number of workers that will be installed or updated in parallel, as a fixed count or a percentage (e.g. "25%"), set to 0 for unlimited. (default "0")
      --zarf-cache string                 Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

import

cargoship import

Converts an OCI Image Layout archive into a native Cargoship package

Synopsis

Converts an OCI Image Layout archive (such as one written by skopeo copy … oci-archive:) or an OCI layout directory into a native Cargoship package archive, extracting all package layers and verifying package integrity.

cargoship import [ARCHIVE] [flags]

Examples

# Import a Skopeo oci-archive into the current directory
$ cargoship import ./my-package.tar

# Import an oci-archive into a specific output directory
$ cargoship import ./my-package.tar --output ./build/

# Import an extracted OCI directory layout
$ cargoship import ./oci-layout-dir -o ./build/

Options

  -a, --architecture string   Architecture for OCI images and Zarf packages
  -h, --help                  help for import
  -k, --key string            Path to public key file for validating signed packages
  -o, --output string         Specify the output (either a directory or an oci:// URL) for the created Cargoship distro package. (default ".")
      --tmpdir string         Specify the temporary directory to use for intermediate files (default "/tmp")
      --verify verifyMode     Verify the Cargoship package signature. (default if-possible)
      --zarf-cache string     Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

inventory

cargoship inventory

Generates a cluster inventory from another source of truth

Synopsis

Generates the cluster inventory cargoship installs from, out of a description of the fleet that already exists somewhere else. These commands install nothing and touch no hosts; they write a file for ‘cargoship validate’ to check and ‘cargoship apply’ to read.

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
  -h, --help                              help for inventory
      --vault-password-file string        Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs
• cargoship inventory from-ansible - Translates an Ansible inventory into a cluster inventory

from-ansible

cargoship inventory from-ansible

Translates an Ansible inventory into a cluster inventory

Synopsis

Translates an inventory Ansible has already resolved into a ZarfCluster document, deriving each host’s role from the Ansible groups it belongs to.

This does not read an Ansible inventory file. Ansible resolves the inventory – group membership, group_vars, host_vars, dynamic inventory plugins, and the precedence rules over all of them – and this reads the resolved result: a JSON document holding ‘groups’, ‘hostvars’, an optional ‘roleGroups’ mapping, and the cluster-wide settings an Ansible inventory has no way to carry. The cargoship Ansible collection produces that document; write it by hand to reproduce a translation outside a playbook run.

By default the Ansible group named ‘controller’ supplies the control-plane nodes and the group named ‘worker’ supplies the rest. Set ‘roleGroups’ to map cargoship’s roles onto the group names the inventory actually uses. A host in none of the mapped groups is left out, so a play’s inventory may carry hosts that are not part of the cluster; a host in groups mapped to two different roles is an error.

Host order is not cosmetic. Controllers are written first, and the first controller in the document becomes the cluster leader.

Each host’s connection details come from its Ansible variables – ansible_host, ansible_user, ansible_port, ansible_ssh_private_key_file – and everything cargoship needs beyond those comes from variables under a ‘cargoship_’ prefix. A ‘cargoship_’ variable cargoship does not read is an error rather than a value ignored, because a misspelled variable and an unset one are indistinguishable at install time.

The generated document is checked against the inventory schema before it is written. The output goes to stdout, or to –output. Ansible does not connect to the fleet: cargoship opens every SSH connection itself, from the node it runs on.

cargoship inventory from-ansible [FILE] [flags]

Examples

# Translate a resolved Ansible inventory, and check the result against the schema
$ cargoship inventory from-ansible ./resolved.json -o ./inventory.yaml
$ cargoship validate ./inventory.yaml

# Read from stdin and write to stdout, so it composes with whatever produced the projection
$ cargoship inventory from-ansible < ./resolved.json | tee ./inventory.yaml

# Translate one projection of a fleet for a second cluster without rewriting it
$ cargoship inventory from-ansible ./resolved.json --name staging --loadbalancer staging-kc.test.com

Options

  -h, --help                  help for from-ansible
      --loadbalancer string   Control-plane address, overriding the one in the input. Cargoship adds it to the API server's TLS subject alternative names.
      --name string           Cluster name, overriding the one in the input. It becomes metadata.name, and the context name in the kubeconfig.
  -o, --output string         Path to write the generated inventory to. Omit it to write to stdout.

Options inherited from parent commands

      --log-file                     Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string            Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string             Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color                     Disable terminal color codes in logging and stdout prints.
      --vault-password-file string   Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

SEE ALSO

• cargoship inventory - Generates a cluster inventory from another source of truth

kube-config

cargoship kube-config

Get the admin kube-config for a control-plane node

Synopsis

Fetches the engine’s admin credentials from the first control-plane node the cluster configuration names and merges them into a kubeconfig file. The file is created when it does not exist, and an existing one keeps every other cluster it already holds.

The server address is rewritten to the control-plane address the configuration declares, rather than the node the credentials came from, so the context keeps working when that node does not. The context is named after the cluster’s metadata.name.

This changes no host – it connects, reads, and writes a file locally – so it needs no –confirm. The file written to is –kubeconfig, which defaults to KUBECONFIG when that is set and to the standard location otherwise.

cargoship kube-config [flags]

Examples

# Fetch the admin kubeconfig from an RKE2 control-plane node
$ cargoship kube-config --config ./cargoship-config.yaml --distro rke2

# Fetch it from a K3s cluster
$ cargoship kube-config --config ./cargoship-config.yaml --distro k3s

# Use the distro set in the resolved cargoship config
$ cargoship kube-config --config ./cargoship-config.yaml

Options

      --config string       Config file used to bootstrap a cluster.
  -D, --distro string       What type of distro we will get the admin config from. Valid options are: 'rke2', 'k3s'.
  -h, --help                help for kube-config
      --kubeconfig string   Path of the kubeconfig file to merge the admin creds for this cluster into. The file is created when it does not exist, and an existing one keeps every other cluster it holds. Defaults to the standard location: KUBECONFIG when set, otherwise ~/.kube/config.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

prepare

cargoship prepare

Prepares the nodes, including restarting the node if new kernel modules are enabled

Synopsis

Brings every host the cluster configuration names up to the prerequisites the package declares, without installing the engine: environment variables and sysctl settings, container-selinux on hosts with SELinux enabled, the fapolicyd rules the distro supplies, and the kernel modules the package asks for. A host that gained a module is rebooted, because the module has to be loaded before an apply can use it.

Running this is optional. An apply runs the same preparation phases itself, and this command exists so that the disruptive half can be done on its own schedule – ahead of a maintenance window rather than inside it.

–hosts and –firewall each opt into rewriting a part of the host that cargoship otherwise leaves alone. The fapolicyd rules are not one of them: they are written wherever a host runs fapolicyd and the package carries rules for it.

This changes every host it is pointed at, so it needs –confirm. Pass –dry-run to report what it would change instead.

cargoship prepare [Distro Package] [flags]

Examples

# Prepare every node in the config for an install
$ cargoship prepare ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm

# Update /etc/hosts, the firewall, and fapolicyd on every node
$ cargoship prepare ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm -H -F -f

# Prepare at most five hosts at a time
$ cargoship prepare ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm --concurrency 5

# Prepare workers 25% at a time
$ cargoship prepare ./build/cargoship-distro-amd64.tar.zst --config ./cargoship-config.yaml --confirm --work-concurrency 25%

Options

  -a, --architecture string   Architecture for OCI images and Zarf packages
  -c, --concurrency int       Maximum number of hosts to configure in parallel, set to 0 for unlimited. (default 30)
      --config string         Config file used to bootstrap a cluster.
      --confirm               Proceed with the run. Without it, a command that would change a host reports what it needs and stops.
      --dry-run               Report what would be done without changing any host. Connects to every host and runs the preflight checks for real, then lists the phases it did not run. Does not need --confirm.
  -F, --firewall              Whether to update every host node's firewall configuration.
  -h, --help                  help for prepare
  -H, --hosts                 Whether to update every host node's /etc/hosts file.
  -k, --key string            Path to public key file for validating signed packages
      --receipt-path string   Write a structured JSON record of the run to PATH: what ran, against which package, against which fleet, and what changed. The file is written whether the run succeeds or fails, and is created readable only by its owner. PATH may carry the placeholders {command} and {timestamp}, which expand to the command that ran and when it started, so a PATH set once in '.distro.receipt_path' gives every run its own file. It names every host in the cluster configuration, so run 'cargoship redact-receipt' over it before attaching it to a ticket.
      --timeout string        Set the timeout for how long functions will last. (default "60m")
      --tmpdir string         Specify the temporary directory to use for intermediate files (default "/tmp")
      --values stringArray    Path to a YAML values file overriding the values the package ships with. May be given more than once, with a later file winning over an earlier one, and all of them winning over the values in the cluster config file.
      --verify verifyMode     Verify the Cargoship package signature. (default if-possible)
      --zarf-cache string     Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

publish

cargoship publish

Publish the Cargoship Package to an OCI registry

Synopsis

Pushes a built package to an OCI registry, where ‘cargoship apply’ and ‘cargoship pull’ can read it by reference instead of by path. The package is uploaded as OCI artifacts, so any registry that stores them will hold it, and –oci-concurrency sets how many layers move at once.

The signature a package already carries is published with it. Passing –signing-key re-signs the package under a different key on the way out, which is how one built and signed in a development environment is re-signed for a production registry.

cargoship publish [Package] [REPOSITORY] [flags]

Examples

# Publish a package to an OCI registry
$ cargoship publish ./build/cargoship-rancher-rke2-amd64-1.0.0.tar.zst oci://ghcr.io/my-org

# Publish and re-sign the package with a different key
$ cargoship publish ./build/cargoship-rancher-rke2-amd64-1.0.0.tar.zst oci://ghcr.io/my-org --signing-key ./private-key.pem --confirm

# Retry failed layer uploads over a slow link
$ cargoship publish ./build/cargoship-rancher-rke2-amd64-1.0.0.tar.zst oci://ghcr.io/my-org --retries 3 --oci-concurrency 3

# Refuse to publish unless the package carries a signature this key validates
$ cargoship publish ./build/cargoship-rancher-rke2-amd64-1.0.0.tar.zst oci://ghcr.io/my-org --verify=always --key ./public-key.pem

Options

  -a, --architecture string        Architecture for OCI images and Zarf packages
  -c, --confirm                    Confirms package publish without prompting. Skips prompt for the signing key password
  -h, --help                       help for publish
      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
  -k, --key string                 Path to public key file for validating signed packages
      --oci-concurrency int        Number of concurrent layer operations when pulling or pushing images or packages to/from OCI registries. (default 6)
      --plain-http                 Allow OCI registry connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
      --retries int                Number of retries to perform for Cargoship's operations, such as package publishes.
      --signing-key string         Private key for signing or re-signing packages with a new key. Accepts either a local file path or env://ENV_VAR to read the key from an environment variable. Cloud KMS references are not supported.
      --signing-key-pass string    Password to the private key used for publishing packages
      --tag string                 The tag to be used in the OCI reference for the package in the registry
      --tmpdir string              Specify the temporary directory to use for intermediate files (default "/tmp")
      --verify verifyMode          Verify the Cargoship package signature. (default if-possible)
      --zarf-cache string          Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

pull

cargoship pull

Pulls a Cargoship package from a remote registry and saves it to the local filesystem

Synopsis

Downloads a package from an OCI registry or an https:// URL and writes it to the local filesystem as a single archive, so that it can be carried to a machine with no route to the registry it came from. An apply reads the same references directly, so pulling first is for staging rather than something an install needs.

–shasum checks the downloaded archive against a checksum you already hold, which is the check to use when the package is to be trusted on the strength of something other than its signature.

cargoship pull [Package] [flags]

Examples

# Pull a package into the current directory
$ cargoship pull oci://ghcr.io/my-org/my-package:1.0.0

# Pull it into ./build/ instead
$ cargoship pull oci://ghcr.io/my-org/my-package:1.0.0 --output ./build/

# Check the downloaded package against a known checksum
$ cargoship pull oci://ghcr.io/my-org/my-package:1.0.0 --shasum 4a4f1f5eb0a1e3f2c9b6d0b2b6a0d3f4c5e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

# Refuse to keep the package unless a signature validates against this key
$ cargoship pull oci://ghcr.io/my-org/my-package:1.0.0 --verify=always --key ./public-key.pem

Options

  -a, --architecture string        Architecture for OCI images and Zarf packages
  -h, --help                       help for pull
      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
  -k, --key string                 Path to public key file for validating signed packages
      --oci-concurrency int        Number of concurrent layer operations when pulling or pushing images or packages to/from OCI registries. (default 6)
  -o, --output string              Specify the output (either a directory or an oci:// URL) for the created Cargoship distro package. (default ".")
      --plain-http                 Allow OCI registry connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
      --shasum string              Shasum of the package to pull.
      --tmpdir string              Specify the temporary directory to use for intermediate files (default "/tmp")
      --verify verifyMode          Verify the Cargoship package signature. (default if-possible)
      --zarf-cache string          Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

redact-receipt

cargoship redact-receipt

Rewrites a run receipt so it can be attached to an issue

Synopsis

Reads the run receipt at RECEIPT and writes a copy with everything that identifies the fleet removed, for attaching to a bug report. Hosts are renumbered host-01, host-02 in the order the receipt lists them, consistently across every phase, so it still reads as a sequence of events on particular machines without naming them. Diff bodies are dropped entirely – an engine configuration diff carries join tokens and registry credentials – leaving the file paths and the reasons they changed, which is what a maintainer triages from. The cluster name, the operator, the management node and the command line go with them. What stays is the phase ledger, the package provenance, the outcome, and the architecture and OS of each host. Redaction is one way: the original is left untouched, because it is the audit record and this is only a copy to send.

cargoship redact-receipt [RECEIPT] [flags]

Examples

# Print a shareable copy of a run receipt
$ cargoship redact-receipt ./apply-20260928-143000.json

# Write one to a file, ready to attach to an issue
$ cargoship redact-receipt ./apply-20260928-143000.json -o ./share.json

Options

  -h, --help            help for redact-receipt
  -o, --output string   Write the redacted receipt to this path instead of standard output. The file is created readable only by its owner.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

reset

cargoship reset

Reset a cluster, stopping, uninstalling, and removing all data for an engine

Synopsis

Removes the engine and the data it wrote from every host the cluster configuration names. Each node is deleted from the cluster, drained first where that is enabled, then the engine’s packages or binaries are uninstalled and the service manager is reloaded.

This is destructive and it backs nothing up. Nothing a workload kept on a host survives it, and no command puts the cluster back: what follows a reset is an apply, which bootstraps a new one.

–distro names the engine to remove. A reset loads no package, so it has nothing else to read the engine’s identity from.

This needs –confirm. Pass –dry-run to report every host it would reset, and what it would do to each, without touching one.

cargoship reset [flags]

Examples

# Reset an RKE2 cluster, uninstalling the engine and removing its data
$ cargoship reset --config ./cargoship-config.yaml --distro rke2 --confirm

# Reset a K3s cluster
$ cargoship reset --config ./cargoship-config.yaml --distro k3s --confirm

# Reset at most five hosts at a time
$ cargoship reset --config ./cargoship-config.yaml --distro rke2 --confirm --concurrency 5

# Reset workers 25% at a time
$ cargoship reset --config ./cargoship-config.yaml --distro rke2 --confirm --work-concurrency 25%

Options

  -c, --concurrency int           Maximum number of hosts to configure in parallel, set to 0 for unlimited. (default 30)
      --config string             Config file used to bootstrap a cluster.
      --confirm                   Proceed with the run. Without it, a command that would change a host reports what it needs and stops.
  -D, --distro string             What type of distro that will be reset. Valid options are: 'rke2', 'k3s'.
      --dry-run                   Report what would be done without changing any host. Connects to every host and runs the preflight checks for real, then lists the phases it did not run. Does not need --confirm.
  -h, --help                      help for reset
      --receipt-path string       Write a structured JSON record of the run to PATH: what ran, against which package, against which fleet, and what changed. The file is written whether the run succeeds or fails, and is created readable only by its owner. PATH may carry the placeholders {command} and {timestamp}, which expand to the command that ran and when it started, so a PATH set once in '.distro.receipt_path' gives every run its own file. It names every host in the cluster configuration, so run 'cargoship redact-receipt' over it before attaching it to a ticket.
      --target-hosts strings      Specific hosts to delete and uninstall, matched by hostname or connection address. Repeatable. Defaults to every host in the cluster configuration.
  -w, --work-concurrency string   Maximum number of workers that will be installed or updated in parallel, as a fixed count or a percentage (e.g. "25%"), set to 0 for unlimited. (default "0")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

schema

cargoship schema

Writes out a JSON Schema for one of cargoship’s own file formats

Synopsis

Writes out the JSON Schema for KIND – ‘inventory’ for a cluster file, ‘package’ for a distro.yaml, ‘config’ for a cargoship config file – so that an editor can complete and check those files without reaching out to GitHub for a hosted copy. The schema comes out of the binary, so it is the schema this build of cargoship validates against, which a hosted one pinned to the default branch is not, and it is available on a network that has never seen the internet. The output goes to stdout, or to –output. Point an editor at a written file with a ‘# yaml-language-server: $schema=PATH’ comment on the first line. With –package, the package’s own values schema is grafted onto spec.config.values, which is the one block of an inventory whose vocabulary belongs to the package rather than to cargoship – so the addon names, chart settings, and everything else that package accepts complete in the editor too. That composed schema describes the overrides on their own, while cargoship validates them merged with the values the package ships; it catches an unknown key, a wrong type, or a name outside an enum, and does not reproduce install-time validation.

cargoship schema KIND [flags]

Examples

# Write the inventory schema next to an inventory file, for an editor to read
$ cargoship schema inventory -o ./cluster-v1alpha1-schema.json

# Then point the inventory at it, as its first line
$ head -1 ./inventory.yaml
# yaml-language-server: $schema=./cluster-v1alpha1-schema.json

# Compose in a package's own values, so spec.config.values completes too
$ cargoship schema inventory --package ./package.tar.zst -o ./inventory.schema.json

# The same, straight from a package source directory, before it is built
$ cargoship schema inventory --package ./example/rke2-cilium-vsphere/v1_37/v1.37.0-rke2r1

# The schema for a distro.yaml, and for a cargoship config file
$ cargoship schema package -o ./distro.schema.json
$ cargoship schema config -o ./cargoship.schema.json

Options

  -a, --architecture string        Architecture for OCI images and Zarf packages
  -h, --help                       help for schema
      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
  -k, --key string                 Path to public key file for validating signed packages
  -o, --output string              Path to write the schema to. Omit it to write to stdout.
      --package string             Graft a package's own values schema onto spec.config.values. Takes anything 'cargoship apply' takes -- a tarball, an oci:// or https:// reference -- or a package source directory or distro.yaml, so it works before the package is built. Only valid for the 'inventory' schema.
      --plain-http                 Allow OCI registry connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
      --tmpdir string              Specify the temporary directory to use for intermediate files (default "/tmp")
      --verify verifyMode          Verify the Cargoship package signature. (default if-possible)
      --zarf-cache string          Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

sha256sum

cargoship sha256sum

Generates a SHA256SUM for the given file

cargoship sha256sum [ FILE | URL ] [flags]

Examples

# Checksum a local file
$ cargoship sha256sum ./build/cargoship-rancher-rke2-amd64-1.0.0.tar.zst

# Checksum a remote file, downloading it first
$ cargoship sha256sum https://example.com/artifact.tar.gz

# Checksum one file inside an archive, for use with a component's files.extractPath
$ cargoship sha256sum ./artifact.tar.gz --extract-path ./bin/tool

# Same thing, using the shorter alias
$ cargoship sum ./build/cargoship-rancher-rke2-amd64-1.0.0.tar.zst

Options

  -e, --extract-path string   The path inside of an archive to use to calculate the sha256sum (i.e. for use with "files.extractPath")
  -h, --help                  help for sha256sum
      --tmpdir string         Specify the temporary directory to use for intermediate files (default "/tmp")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

sign

cargoship sign

Signs an existing Cargoship distro package

Synopsis

Signs an existing Cargoship distro package with a private key. The package can be a local tarball or pulled from an OCI registry. The signature is created by signing the distro.yaml file and does not modify the package checksums.

cargoship sign PACKAGE_SOURCE [flags]

Examples

# Sign an unsigned package
$ cargoship sign cargoship-rancher-rke2-amd64-1.0.0.tar.zst --signing-key ./private-key.pem

# Re-sign with a new key (overwrite existing signature)
$ cargoship sign cargoship-rancher-rke2-amd64-1.0.0.tar.zst --signing-key ./new-key.pem --overwrite

# Sign a package from an OCI registry and output to a local directory
$ cargoship sign oci://ghcr.io/my-org/my-package:1.0.0 --signing-key ./private-key.pem --output ./signed/

# Sign a package and publish directly to an OCI registry
$ cargoship sign cargoship-rancher-rke2-amd64-1.0.0.tar.zst --signing-key ./private-key.pem --output oci://ghcr.io/my-org/signed-packages

# Sign with a key held in an environment variable rather than on disk
$ cargoship sign cargoship-rancher-rke2-amd64-1.0.0.tar.zst --signing-key env://COSIGN_PRIVATE_KEY

Options

  -a, --architecture string        Architecture for OCI images and Zarf packages
      --confirm                    Skip the interactive confirmation prompt before uploading to the Rekor transparency log (equivalent to cosign --yes).
  -h, --help                       help for sign
      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
  -k, --key string                 Public key to verify the existing signature before re-signing (optional)
      --oci-concurrency int        Number of concurrent layer operations when pulling or pushing images or packages to/from OCI registries. (default 6)
  -o, --output string              Output destination for the signed package. Can be a local directory or an OCI registry URL (oci://). Default: same directory as source package for files, current directory for OCI sources
      --overwrite                  Overwrite an existing signature if the package is already signed
      --plain-http                 Allow OCI registry connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
      --retries int                Number of retries to perform for Cargoship's operations, such as package publishes.
      --signing-key string         Private key for signing packages. Accepts either a local file path or env://ENV_VAR to read the key from an environment variable. Cloud KMS references are not supported.
      --signing-key-pass string    Password for encrypted private key
      --tmpdir string              Specify the temporary directory to use for intermediate files (default "/tmp")
      --verify verifyMode          Verify the Cargoship package signature. (default if-possible)
      --zarf-cache string          Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

validate

cargoship validate

Checks a cluster inventory, package definition, or config file against its schema

Synopsis

Checks one or more files against the JSON Schema cargoship generates for that file format, reporting every problem rather than the first. Cargoship parses these files without strict key checking, so a misspelled key is dropped rather than reported; this catches that, along with a wrong type and a value outside an enumerated list. The schema is read from the binary, so no network access is needed.

The schema is chosen from the document’s own ‘kind’ field. A cargoship config file declares no kind and has to be named with –kind.

spec.config.values is untyped in the inventory schema, because its shape belongs to whichever package is being installed. Pass –package to check it as well.

cargoship validate FILE... [flags]

Examples

# Check a cluster inventory against the inventory schema:
$ cargoship validate ./inventory.yaml

# Check every inventory in a directory, reporting all of them in one pass:
$ cargoship validate ./inventories/*.yaml

# Check a cargoship config file, which declares no kind of its own:
$ cargoship validate --kind config ./cargoship-config.yaml

# Check an inventory's spec.config.values against the package it will be installed with:
$ cargoship validate ./inventory.yaml --package ./package.tar.zst

Options

  -a, --architecture string        Architecture for OCI images and Zarf packages
  -h, --help                       help for validate
      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
  -k, --key string                 Path to public key file for validating signed packages
      --kind string                Name the schema to check against instead of reading the document's 'kind' field. Required for a cargoship config file, which declares no kind.
      --package string             Check spec.config.values against a package's own values schema. Takes anything 'cargoship apply' takes -- a tarball, an oci:// or https:// reference -- or a package source directory or distro.yaml, so it works before the package is built. Only valid for the 'inventory' schema.
      --plain-http                 Allow OCI registry connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
      --tmpdir string              Specify the temporary directory to use for intermediate files (default "/tmp")
      --verify verifyMode          Verify the Cargoship package signature. (default if-possible)
      --zarf-cache string          Specify the location of the Zarf cache directory (default "$HOME/.cache/cargoship")

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

vault

cargoship vault

Encrypts and decrypts cluster configuration values with Ansible Vault or age

Synopsis

Groups the commands that read and write encrypted values for a cluster configuration, in either of the two formats cargoship supports: Ansible Vault, keyed by a shared password given via –vault-password-file or the CARGOSHIP_VAULT_PASSWORD environment variable, and age, keyed by public keys given via –age-recipient and read back with –age-identity-file. Cargoship decrypts a registry’s user/pass/token and tls.ca fields at apply time. Which format a value is in is read from the value itself, so one configuration can hold both, and moving between them is ‘cargoship vault rekey’. The group is still called vault because renaming it would break every script that calls it.

Options

  -h, --help   help for vault

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs
• cargoship vault decrypt - Decrypts an Ansible Vault or age value, printing the plaintext
• cargoship vault decrypt-file - Decrypts every registry credential in a config file, in place
• cargoship vault decrypt-path - Decrypts the values a config file holds at one or more YAML paths, in place
• cargoship vault encrypt - Encrypts a value with Ansible Vault or age, for use in a registry’s user/pass/token fields
• cargoship vault encrypt-file - Encrypts every registry credential in a config file, in place
• cargoship vault encrypt-path - Encrypts the values a config file already holds at one or more YAML paths, in place
• cargoship vault keygen - Generates an age key pair, or prints the public key of one you already hold
• cargoship vault rekey - Re-wraps every encrypted registry credential in a config file, optionally under a new key

decrypt-file

cargoship vault decrypt-file

Decrypts every registry credential in a config file, in place

Synopsis

Decrypts every encrypted registry credential FILE holds – each registry’s auth.user, auth.pass, auth.token and tls.ca – and writes the plaintext back to FILE, leaving comments, key order, and the rest of the document untouched. A field that is not encrypted is skipped. This is the inverse of ‘cargoship vault encrypt-file’, and leaves the credentials readable to anyone who can read the file.

cargoship vault decrypt-file FILE [flags]

Examples

# Decrypt every registry credential in a cluster configuration
$ cargoship vault decrypt-file ./cluster.yaml --vault-password-file ./vault-pass.txt

# Check that every encrypted credential decrypts, without writing plaintext to disk
$ cargoship vault decrypt-file ./cluster.yaml --vault-password-file ./vault-pass.txt --dry-run > /dev/null

# Decrypt a configuration encrypted to an age recipient
$ cargoship vault decrypt-file ./cluster.yaml --age-identity-file ./key.txt

# Decrypt one encrypted to an SSH public key, using the private key it pairs with
$ cargoship vault decrypt-file ./cluster.yaml --age-identity-file ~/.ssh/id_ed25519

# Rotate the password a whole configuration is vaulted with
$ cargoship vault decrypt-file ./cluster.yaml --vault-password-file ./old-pass.txt
$ cargoship vault encrypt-file ./cluster.yaml --vault-password-file ./new-pass.txt

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
      --dry-run                           Print the resulting document to stdout instead of writing it back to FILE.
  -h, --help                              help for decrypt-file
      --vault-password-file string        Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age

decrypt-path

cargoship vault decrypt-path

Decrypts the values a config file holds at one or more YAML paths, in place

Synopsis

Decrypts the encrypted values FILE holds at each YAML_PATH and writes the plaintext back to FILE, leaving comments, key order, and the rest of the document untouched. Each YAML_PATH names a value inside FILE rather than a file on disk: it is a YAML path such as ‘.spec.config.registries[0].auth.pass’, and the leading ‘$’ go-yaml uses is optional. Quote it, since it usually contains characters a shell would otherwise expand. Give as many as you like – FILE is written once, after every one of them has decrypted, so a path that is missing or plaintext already leaves FILE as it was. This is the inverse of ‘cargoship vault encrypt-path’, and leaves the values readable to anyone who can read the file.

cargoship vault decrypt-path FILE YAML_PATH [YAML_PATH...] [flags]

Examples

# Put the plaintext password back into a config, in place of the ciphertext
$ cargoship vault decrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./vault-pass.txt

# Decrypt several values in one pass
$ cargoship vault decrypt-path ./cluster.yaml '.x-tra.test.user' '.x-tra.test.pass' --vault-password-file ./vault-pass.txt

# Check that a vaulted value decrypts, without writing the plaintext to disk
$ cargoship vault decrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./vault-pass.txt --dry-run

# Rotate the password a config is vaulted with
$ cargoship vault decrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./old-pass.txt
$ cargoship vault encrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./new-pass.txt

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
      --dry-run                           Print the resulting document to stdout instead of writing it back to FILE.
  -h, --help                              help for decrypt-path
      --vault-password-file string        Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age

decrypt

cargoship vault decrypt

Decrypts an Ansible Vault or age value, printing the plaintext

Synopsis

Decrypts VALUE, a string produced by ‘cargoship vault encrypt’ in either format, and prints the plaintext to stdout. The format is read from the value itself: a $ANSIBLE_VAULT prefix needs the vault password, an —–BEGIN AGE ENCRYPTED FILE—– prefix needs –age-identity-file. If VALUE is omitted, it is read from stdin, which is the easier way to hand over an age value, since one begins with dashes and is read as a flag when given as an argument; after the flags, ‘–’ works too. The plaintext is written as it is, with a trailing newline added only when it does not already end in one, so that a multi-line value can be redirected straight into a file.

cargoship vault decrypt [VALUE] [flags]

Examples

# Decrypt a value copied out of a config file
$ cargoship vault decrypt '$ANSIBLE_VAULT;1.1;AES256
3862...' --vault-password-file ./vault-pass.txt

# Decrypt a value held in a file
$ cargoship vault decrypt --vault-password-file ./vault-pass.txt < ./encrypted-token.txt

# Write a decrypted CA certificate straight out to a PEM file
$ cargoship vault decrypt --vault-password-file ./vault-pass.txt < ./encrypted-ca.txt > ./ca.pem

# Check a value round-trips under the password a config will be applied with
$ cargoship vault encrypt hunter2 --vault-password-file ./vault-pass.txt | cargoship vault decrypt --vault-password-file ./vault-pass.txt

# Decrypt an age value; pipe it in, since an age value begins with dashes and reads as a flag
$ cargoship vault decrypt --age-identity-file ./key.txt < ./encrypted-token.txt

# The same value as an argument, with "--" after the flags to end flag parsing
$ cargoship vault decrypt --age-identity-file ./key.txt -- "$(cat ./encrypted-token.txt)"

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
  -h, --help                              help for decrypt
      --vault-password-file string        Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age

encrypt-file

cargoship vault encrypt-file

Encrypts every registry credential in a config file, in place

Synopsis

Encrypts every registry credential FILE holds that cargoship decrypts at apply time – each registry’s auth.user, auth.pass, auth.token and tls.ca – and writes them back to FILE as block scalars, leaving comments, key order, and the rest of the document untouched. A field that is absent, empty, or encrypted already is skipped, so running this over a partly encrypted configuration finishes the job and running it twice changes nothing the second time. That skip applies to a value in the other format too: this command never moves a credential between Ansible Vault and age, which is what ‘cargoship vault rekey’ is for. Every credential skipped for a reason worth knowing about is reported, so a run that changes nothing says which values it left alone and why.

cargoship vault encrypt-file FILE [flags]

Examples

# Encrypt every registry credential in a cluster configuration
$ cargoship vault encrypt-file ./cluster.yaml --vault-password-file ./vault-pass.txt

# See what the file would become without writing it
$ cargoship vault encrypt-file ./cluster.yaml --vault-password-file ./vault-pass.txt --dry-run

# Vault a configuration before committing it
$ cargoship vault encrypt-file ./cluster.yaml --vault-password-file ./vault-pass.txt && git add ./cluster.yaml

# Encrypt to the age recipients a team keeps in its config file, with no keys on the command line
$ cargoship vault encrypt-file ./cluster.yaml

# Encrypt to the SSH keys a team already distributes, using its authorized_keys file as it is
$ cargoship vault encrypt-file ./cluster.yaml --age-recipients-file ./authorized_keys

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
      --dry-run                           Print the resulting document to stdout instead of writing it back to FILE.
      --force                             Encrypt values that are encrypted already, wrapping them a second time.
  -h, --help                              help for encrypt-file
      --vault-password-file string        Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age

encrypt-path

cargoship vault encrypt-path

Encrypts the values a config file already holds at one or more YAML paths, in place

Synopsis

Encrypts the values FILE holds at each YAML_PATH and writes them back to FILE as block scalars, leaving comments, key order, and the rest of the document untouched. Each YAML_PATH names a value inside FILE rather than a file on disk: it is a YAML path such as ‘.spec.config.registries[0].auth.pass’, and the leading ‘$’ go-yaml uses is optional. Quote it, since it usually contains characters a shell would otherwise expand. Give as many as you like – FILE is written once, after every one of them has encrypted, so a path that is missing or encrypted already leaves FILE as it was rather than partly rewritten. Cargoship decrypts a registry’s user/pass/token and tls.ca fields at apply time, and warns about a path anywhere else, because nothing unwraps a value encrypted elsewhere.

cargoship vault encrypt-path FILE YAML_PATH [YAML_PATH...] [flags]

Examples

# Encrypt the password a config already holds for its first registry
$ cargoship vault encrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --vault-password-file ./vault-pass.txt

# Encrypt several values in one pass; the file is written once, after all of them have encrypted
$ cargoship vault encrypt-path ./cluster.yaml '.x-tra.test.user' '.x-tra.test.pass' --vault-password-file ./vault-pass.txt

# Encrypt a registry's inline CA certificate, however many lines of PEM it runs to
$ cargoship vault encrypt-path ./cluster.yaml '.spec.config.registries[0].tls.ca' --vault-password-file ./vault-pass.txt

# See what the file would become without writing it
$ cargoship vault encrypt-path ./cluster.yaml '.spec.config.registries[0].auth.token' --vault-password-file ./vault-pass.txt --dry-run

# Encrypt to an age recipient instead of a vault password
$ cargoship vault encrypt-path ./cluster.yaml '.spec.config.registries[0].auth.pass' --age-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
      --dry-run                           Print the resulting document to stdout instead of writing it back to FILE.
      --force                             Encrypt the value even though it is encrypted already, wrapping it a second time.
  -h, --help                              help for encrypt-path
      --vault-password-file string        Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age

encrypt

cargoship vault encrypt

Encrypts a value with Ansible Vault or age, for use in a registry’s user/pass/token fields

Synopsis

Encrypts VALUE, producing a string that cargoship decrypts automatically at apply time when placed in a registry’s user/pass/token field. With –age-recipient or –age-recipients-file the output is armored age ciphertext beginning with —–BEGIN AGE ENCRYPTED FILE—–; otherwise it is Ansible Vault ciphertext beginning with $ANSIBLE_VAULT. If VALUE is omitted, it is read from stdin, or prompted for with hidden input when stdin is a terminal.

cargoship vault encrypt [VALUE] [flags]

Examples

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

# Omit the value to be prompted for it, with the input hidden
$ cargoship vault encrypt --vault-password-file ./vault-pass.txt

# Encrypt a value piped in on stdin
$ printf my-registry-password | cargoship vault encrypt --vault-password-file ./vault-pass.txt

# Encrypt the contents of a file
$ cargoship vault encrypt --vault-password-file ./vault-pass.txt < ./registry-token.txt

# Encrypt to age public keys instead, so no shared password has to be handed around
$ cargoship vault encrypt my-registry-password --age-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# Encrypt to every key a team keeps in one file, each of whom can decrypt on their own
$ cargoship vault encrypt my-registry-password --age-recipients-file ./recipients.txt

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
  -h, --help                              help for encrypt
      --vault-password-file string        Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age

keygen

cargoship vault keygen

Generates an age key pair, or prints the public key of one you already hold

Synopsis

Generates an age key pair in the format age-keygen writes, so that the age distribution is not a prerequisite for encrypting a configuration with age, and the file stays readable by ‘age –decrypt’ and anything else that speaks the format. The identity – the private key, AGE-SECRET-KEY-1… – goes to –output, or to stdout when that is omitted; the recipient – the public key, age1… – goes to stderr, so that the file holds the private key alone and the public key can be copied straight into a recipients file. With –public-key it generates nothing and instead prints the public keys held in IDENTITY_FILE, or in stdin when no file is given, which is how a recipient is recovered from a private key you still have. A key pair is not registered anywhere: pass the public key to ‘cargoship vault encrypt’ as –age-recipient, and the file back as –age-identity-file to read those values again.

cargoship vault keygen [IDENTITY_FILE] [flags]

Examples

# Generate a key pair, writing the private key to a file and printing the public key
$ cargoship vault keygen --output ~/.age/cargoship.key

# The same, redirecting instead, which leaves the file mode up to your shell
$ cargoship vault keygen > ~/.age/cargoship.key

# Recover the public key from an identity file you still hold
$ cargoship vault keygen --public-key ~/.age/cargoship.key

# Encrypt a configuration to the key that was just generated, and read it back
$ cargoship vault encrypt-file ./cluster.yaml --age-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
$ cargoship vault decrypt-file ./cluster.yaml --age-identity-file ~/.age/cargoship.key

Options

  -h, --help            help for keygen
  -o, --output string   Path to write the generated identity to, created with mode 0600. An existing file is never overwritten, because anything encrypted to the key it holds would become unreadable. Omit it to write to stdout instead.
  -y, --public-key      Print the public keys held in IDENTITY_FILE instead of generating a key pair. Reads stdin when no file is given. This reads age identity files; the public key of an SSH key is in the ".pub" file beside it.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age

rekey

cargoship vault rekey

Re-wraps every encrypted registry credential in a config file, optionally under a new key

Synopsis

Re-wraps every encrypted registry credential FILE holds – each registry’s auth.user, auth.pass, auth.token and tls.ca – under the key named by –new-vault-password-file or by –age-recipient, leaving comments, key order, and the rest of the document untouched. Naming age recipients while reading with the vault password is how a configuration moves from Ansible Vault to age; naming neither re-wraps the values under the key they already carry, which gives every one of them fresh ciphertext without changing the key. The plaintext is never written to FILE: each value is decrypted and encrypted again in memory, which is what makes this safer than a decrypt-file followed by an encrypt-file, where the file holds the credentials in the clear in between. Every encrypted value has to be readable with the keys given, and the command stops without touching FILE if one is not, because a configuration encrypted under two keys is one no single key can read back.

cargoship vault rekey FILE [flags]

Examples

# Move every encrypted registry credential in a cluster configuration to a new vault password
$ cargoship vault rekey ./cluster.yaml --vault-password-file ./old-pass.txt --new-vault-password-file ./new-pass.txt

# Re-salt every encrypted registry credential, keeping the password the file already uses
$ cargoship vault rekey ./cluster.yaml --vault-password-file ./vault-pass.txt

# Check what a rotation would produce without writing it back
$ cargoship vault rekey ./cluster.yaml --vault-password-file ./old-pass.txt --new-vault-password-file ./new-pass.txt --dry-run

# Move a vaulted configuration onto age, reading with the old password and writing to the recipients
$ cargoship vault rekey ./cluster.yaml --vault-password-file ./vault-pass.txt --age-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# Re-encrypt to a smaller recipient set, which is how access is revoked
$ cargoship vault rekey ./cluster.yaml --age-identity-file ./key.txt --age-recipients-file ./recipients.txt

Options

      --age-identity-file stringArray     Path to an age identity file holding the private keys that decrypt registry credentials, or to an SSH private key such as ~/.ssh/id_ed25519. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.identity_files in the cargoship config file, or as a single path in CARGOSHIP_AGE_IDENTITY_FILE.
      --age-recipient stringArray         A public key to encrypt registry credentials to: either an age recipient such as age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p, or an SSH public key such as 'ssh-ed25519 AAAAC3Nza...'. Repeatable; also settable as age.recipients in the cargoship config file, or space-separated in CARGOSHIP_AGE_RECIPIENTS. Giving any recipient makes cargoship write age ciphertext instead of Ansible Vault.
      --age-recipients-file stringArray   Path to a file holding public keys, one per line, which may mix age recipients and SSH public keys; an authorized_keys file works as it is. A leading ~ is expanded to your home directory wherever the path comes from. Repeatable; also settable as age.recipients_files in the cargoship config file.
      --dry-run                           Print the resulting document to stdout instead of writing it back to FILE.
  -h, --help                              help for rekey
      --new-vault-password-file string    Path to a file containing the Ansible Vault password to move to. Omit it to re-salt every value under the key the file already uses, or pass --age-recipient instead to move the file onto age. Deliberately without an environment fallback: the environment holds the password the file is vaulted under now, so an omitted flag would otherwise look like a rotation that never happened.
      --vault-password-file string        Path to a file containing the Ansible Vault password. Falls back to the CARGOSHIP_VAULT_PASSWORD, then ANSIBLE_VAULT_PASSWORD, environment variable.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship vault - Encrypts and decrypts cluster configuration values with Ansible Vault or age

verify

cargoship verify

Verifies the signature on a Cargoship distro package

Synopsis

Verifies the signature on an existing Cargoship distro package. The package can be a local tarball or pulled from an OCI registry. Pass –key to verify against a cosign public key, which is the only supported signing method. An unsigned package is reported as a failure. The other commands that load packages verify as part of loading, gated on their –verify flag – this command verifies and nothing else.

cargoship verify PACKAGE_SOURCE [flags]

Examples

# Verify a signed package against a public key
$ cargoship verify cargoship-rancher-rke2-amd64-1.0.0.tar.zst --key ./cosign.pub

# Verify a package in an OCI registry
$ cargoship verify oci://ghcr.io/my-org/my-package:1.0.0 --key ./cosign.pub


# Match the signer identity by pattern instead

Options

  -h, --help                       help for verify
      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
  -k, --key string                 Path to public key file for validating signed packages
      --plain-http                 Allow OCI registry connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

version

cargoship version

Shows the version of the running binary

Synopsis

Displays the version of the release that the current binary was built from.

cargoship version [flags]

Examples

# Print the version of the running binary
$ cargoship version

# Print the full build information as YAML
$ cargoship version --output yaml

# Print it as JSON, for piping into jq
$ cargoship version -o json

Options

  -h, --help                  help for version
  -o, --output outputFormat   Output format. Valid options are: yaml, json.

Options inherited from parent commands

      --log-file            Always write a full-verbosity debug log to a file, regardless of --log-level.
  -L, --log-format string   Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'. (default "console")
  -l, --log-level string    Log level when running cargoship. Valid options are: warn, info, debug, trace (default "info")
      --no-color            Disable terminal color codes in logging and stdout prints.

SEE ALSO

• cargoship - CLI for cargoship installs

cluster

Cluster configuration

is the root object of a cluster configuration document.

Rendered from schema/cluster-v1alpha1-schema.json.

AgeEncryption

records the age recipients a document’s credentials were encrypted to.

Config

holds cluster-wide configuration.

Encryption

records how the credentials in a document were encrypted.

Files

defines a file to write to a host.

FirewallConfig

is the backend-neutral firewall configuration for a node.

FirewallPolicyConfig

configures a firewalld policy that opens ports from one zone to another.

FirewallPort

defines a port allowed through the firewalld policy.

FirewallRule

is a single backend-neutral firewall rule.

FirewallZone

is the name of either the ingress or egress zone for a policy.

Host

is a remote connection to a node

HostConfig

defines the configuration for a specific host, including firewall policies and the ports cargoship opens on the node.

HostEngine

defines configuration options for node-level metadata, specifically Kubernetes node labels and taints applied to a cluster host.

HostPort

is a port cargoship opens on the public side of the firewall.

Hosts

is an ordered list of hosts that cargoship manages together.

Metadata

holds identifying information for a cluster.

OpenSSHConfig

OptionArguments

Profiles

holds the host and engine overrides for one profile.

Registries

holds the credentials and pull proxy for one container registry.

RegistryAuth

holds the credentials for a container registry.

RegistryProxy

redirects pulls for a registry to a different URL.

RegistryTLS

holds the TLS connection settings for a container registry.

SSHConfig

Spec

holds the configuration and hosts for a cluster.

WinRMConfig

config

Cargoship configuration file

holds the values for the ., or root, section of the config file

Rendered from schema/config-distro-schema.json.

AgeOptions

holds the values for the .age section of the config file, the age alternative to the Ansible Vault password given by –vault-password-file.

DistroCreateOptions

holds the values for the .distro.create section of the config file

DistroOptions

holds the values for the .distro section of the config file

DistroPublishOptions

holds the values for the .distro.publish section of the config file

FileOverrideMap

maps a source URL prefix to the location cargoship downloads from instead.

RegistryOverrideMap

maps a source registry to the registry cargoship uses instead.

distro

Distro package

is the root object of a distro package configuration document.

Rendered from schema/distro-v1alpha1-schema.json.

Actions

defines the actions cargoship runs during specific phases of building the distro package.

Arches

BinarySelector

selects which files to upload to a host, based on host role and install method.

BuildData

holds information recorded when the package was built.

Config

holds the configuration for the distro engine.

File

defines a file shared by the distro and cluster APIs.

FileSource

records where one file in the package was actually read from, for a file whose declared source a –file-override redirected.

Files

is an ordered list of files.

ImageConfig

holds settings for the images cargoship writes to a host.

Mapping

Metadata

holds identifying information for a distro package.

OS

holds settings applied to a host.

SELinux

holds the custom SELinux policy cargoship applies to hosts running SELinux in enforcing mode.

SELinuxFileContext

holds a single file context mapping cargoship adds with semanage.

SELinuxModule

holds a single CIL policy module cargoship installs with semodule.

SetValue

Shell

Spec

holds the configuration for a distro package.

ValueMapping

projects one value onto one place in the engine configuration.

Values

declares the values a package ships with.

Variable

ZarfComponentAction

ZarfComponentActionDefaults

ZarfComponentActionSet

ZarfComponentActionWait

ZarfComponentActionWaitCluster

ZarfComponentActionWaitNetwork

The colonel_byte.cargoship collection

Cargoship runs inside a playbook as an Ansible collection. The cargoship binary is the module: it is installed as a set of symlinks named cargoship_<action>, and a symlink’s name selects the action. There is no separate module package and nothing to install on the managed nodes.

Ansible supplies the inventory and nothing else. It does not connect to the fleet, gather facts on it, or run a task per host. Every task in this collection runs on one management node outside the cluster – the node the package and images were staged onto – and cargoship opens every SSH connection itself from there. See choice-ansible-module for why the work is split that way.

That boundary is what the collection is for, and it is the whole of what the collection is for. A role that configures fleet hosts directly belongs in the playbook that consumes this collection, not in it.

What is here

Which to reach for

Reach for the cluster role first. It picks the module from cargoship_action, assembles the inventory parameter, and sets run_once, delegate_to, and no_log for you.

Reach for a module directly when you need control the role does not give you. Then you must set run_once: true yourself, or the cluster is converged once per host in the fleet, and delegate_to and no_log: true with it.

Reference pages are generated

Every module_*.md and role_*.md page here is generated from the collection itself – a role’s interface from its meta/argument_specs.yml, a module’s from the DOCUMENTATION and EXAMPLES blocks in its action plugin – by mage generate:document. Edit the collection and regenerate; an edit to a generated page does not survive the next commit.

This page, modules.md, and roles.md are written by hand. See ansible/colonel_byte/cargoship/AGENTS.md for the contract.

The other collection here

Modules

Five modules ship, one per fleet action. Package creation is not among them – it builds an artifact from a definition in a repository, which belongs in a pipeline rather than in a convergence run.

The surfaces differ because the commands do

cargoship prepare reads no encrypted value, so it takes no vault_password_file. cargoship reset installs nothing, so it takes no package and no values. cargoship engine-config-sync does not update the hosts themselves, so it takes none of the three host switches. A parameter offered to the wrong module is an error naming it, rather than a flag quietly dropped.

Each module’s page lists its full parameter set and the flag each parameter renders. A parameter that renders no flag is listed as None: it is either the command’s positional argument, or something consumed before the command line is built.

What every task needs

A parameter left unset is left unset: the module passes no flag for it, so whatever your cargoship configuration file sets still applies. That is why label_nodes: false and omitting label_nodes are different.

Set run_once: true, delegate_to, and no_log: true on every direct module call. The cluster role sets all three for you. Key material is always named by a path and never given by value, because Ansible writes a module’s parameters into a file on disk.

The module guide covers installing the collection, check mode, what changed is worth, and the shape of the result.

apply

cargoship_apply

Install or converge a Kubernetes cluster across the fleet.

Write it as colonel_byte.cargoship.cargoship_apply. It runs on the management node; nothing is installed on the fleet.

Added in colonel_byte.cargoship 0.26.0.

Runs cargoship apply against the fleet described by an Ansible inventory. It is the widest action cargoship has.

The module runs on one management node. Ansible does not connect to the fleet; cargoship opens every SSH connection itself from there.

Parameters

Notes

• Set run_once: true and delegate_to on the task. Cargoship converges the whole fleet in a single run, so a play over the fleet’s own inventory would otherwise converge it once per host.
• Set no_log: true on the task. A binary module has no per-parameter no_log, so the task-level setting is what suppresses the arguments and the result.
• A parameter left unset renders no flag, so whatever the cargoship configuration file sets still applies. That is why label_nodes: false and omitting label_nodes differ.

Example

- name: Install the cluster
  colonel_byte.cargoship.cargoship_apply:
    package: /srv/staging/rke2-1.31.tar.zst
    inventory_path: /srv/staging/generated-inventory.yaml
    inventory:
      cluster:
        name: bubbles
        loadbalancer: bubbles-kc.test.com
    vault_password_file: /srv/staging/vault-pass
    timeout: 45m
  delegate_to: localhost
  run_once: true
  no_log: true

engine_config_sync

cargoship_engine_config_sync

Converge engine configuration across the fleet.

Write it as colonel_byte.cargoship.cargoship_engine_config_sync. It runs on the management node; nothing is installed on the fleet.

Added in colonel_byte.cargoship 0.26.0.

Runs cargoship engine-config-sync against the fleet described by an Ansible inventory. It is the most Ansible-shaped thing cargoship does, and the one action whose phases report whether they changed anything.

It does not update the hosts themselves, so it takes none of the three host switches.

Parameters