config

Cargoship configuration file

holds the values for the ., or root, section of the config file

Rendered from schema/config-distro-schema.json.

Property	Type	Required	Default	Description
`age`	AgeOptions	no		are the age keys used to encrypt and decrypt registry credentials
`architecture`	`string`	no		the CPU architecture to use for OCI operations
`distro`	DistroOptions	no		are various options used by the command
`log_file`	`boolean`	no		enables always writing a full-verbosity debug log to a file, regardless of LogLevel
`log_format`	`string`	no	`console`	how the logs are displayed well running One of `console`, `json`, `dev`.
`log_level`	`string`	no	`info`	the level of logs that will be displayed One of `warn`, `info`, `debug`, `trace`.
`no_color`	`boolean`	no		whether to disable terminal color codes in logging and stdout prints
`timeout`	`string`	no	`20m`	the longest we will run long ran tasks before failing
`tmp_dir`	`string`	no	`/tmp`	the directory where we store stuff before deleting them
`zarf_cache`	`string`	no		is the folder where cargoship caches what it fetches: oras artifacts, and the release assets the example generation targets read

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.

Property	Type	Required	Description
`identity_files`	array of `string`	no	are paths to identity files, each holding either the age private keys that decrypt registry credentials or an SSH private key. A leading ~ is expanded to the home directory of the user running cargoship. Equivalent to repeating –age-identity-file.
`recipients`	array of `string`	no	are the public keys registry credentials are encrypted to, each either an age recipient or an SSH public key. Equivalent to repeating –age-recipient.
`recipients_files`	array of `string`	no	are paths to files holding public keys, one per line, with # comments allowed, mixing age recipients and SSH public keys freely. An authorized_keys file works as it is. A leading ~ is expanded to the home directory of the user running cargoship. Equivalent to repeating –age-recipients-file.

DistroCreateOptions

holds the values for the .distro.create section of the config file

Property	Type	Required	Default	Description
`file_override`	FileOverrideMap	no		maps a source URL prefix to the location cargoship downloads from instead, for example {“https://rpm.rancher.io”: “https://mirror.example.com/rpm-rancher”}. The value may also be a local directory, for builds from pre-staged assets.
`registry_override`	RegistryOverrideMap	no		maps a source registry to the registry cargoship uses instead when pulling images, for example {“docker.io”: “mirror.example.com”}

DistroOptions

holds the values for the .distro section of the config file

Property	Type	Required	Default	Description
`allow_downgrade`	`boolean`	no		whether a run continues when a host already runs an engine version newer than the one the package carries
`allow_unmanaged_nodes`	`boolean`	no		whether an apply continues when the cluster holds a node that no host in the config accounts for
`concurrency`	`integer`	no		how many nodes we will try to interact with at a time, 0 means that all nodes will be done at once
`create`	DistroCreateOptions	no		are options used by the create subcommand
`firewall`	`boolean`	no	`true`	whether we will update the host firewall
`hosts`	`boolean`	no	`true`	whether we will update the etc host file
`kubeconfig`	`string`	no		path of the kubeconfig file the admin creds are merged into, the standard location – KUBECONFIG, else ~/.kube/config – when empty
`label_nodes`	`boolean`	no	`true`	whether we will check and add the node-role.kubernetes.io/<profile> label on nodes
`oci_concurrency`	`integer`	no		is how many concurrent oci artifacts that will be pushed at a time
`output`	`string`	no		the folder that we will create the distro tar balls in
`public_key`	`string`	no		path to public key file for validating signed packages
`publish`	DistroPublishOptions	no		are options used by the publish subcommand
`receipt_path`	`string`	no		is where the lifecycle commands – apply, prepare, reset and engine-config-sync – write the structured JSON record of a run, empty for no receipt. Equivalent to –receipt-path, and templated the same way: {command} expands to the command that ran and {timestamp} to when it started, so one configured value gives every run its own file rather than overwriting the last.
`retry`	`integer`	no		how many times an operation is retried before the run fails, including a package push to an OCI registry – it is what –retries defaults to on publish and sign
`type`	`string`	no		of distro we are interacting with One of `rke2`, `k3s`.
`update_kubeconfig`	`boolean`	no	`true`	whether we will update a kubeconfig file with the admin creds for the cluster
`verify`	`string`	no		the Cargoship package signature One of `never`, `if-possible`, `always`.
`worker_concurrency`	`string` or `integer`	no		number of worker nodes that will be upgraded at once, as a fixed count (“5”) or a percentage of the batch (“25%”)

DistroPublishOptions

holds the values for the .distro.publish section of the config file

Property	Type	Required	Default	Description
`signing_key`	`string`	no		is the private key used to sign, or re-sign, the package: a local file path, or env://ENV_VAR to read the key from an environment variable. Cloud KMS references are not supported – they cannot be reached from an air-gapped management node.
`signing_key_password`	`string`	no		the password for the private key used for signing Sensitive. Treat this value as a secret: it is a credential rather than a path to one.

FileOverrideMap

maps a source URL prefix to the location cargoship downloads from instead.

Property	Type	Required
`https://download.docker.com`	`string`	no
`https://get.k3s.io`	`string`	no
`https://github.com`	`string`	no
`https://pkgs.k8s.io`	`string`	no
`https://rpm.rancher.io`	`string`	no

RegistryOverrideMap

maps a source registry to the registry cargoship uses instead.

Property	Type	Required
`docker.io`	`string`	no
`gcr.io`	`string`	no
`ghcr.io`	`string`	no
`public.ecr.aws`	`string`	no
`quay.io`	`string`	no
`registry.k8s.io`	`string`	no