distro

Distro package

is the root object of a distro package configuration document.

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

Property	Type	Required	Description
`apiVersion`	`string`	no	identifies the API group and version of this configuration document. One of `colonel-byte.dev/v1alpha1`, `zarf.dev/v1alpha1`.
`build`	BuildData	no	holds information recorded when the package was built.
`kind`	`string`	yes	identifies the document type. The value must be Distro, or ZarfDistro on a document written before the move to colonel-byte.dev. One of `Distro`, `ZarfDistro`.
`metadata`	Metadata	yes	holds identifying information for the distro package.
`spec`	Spec	yes	holds the configuration for the distro package.

Actions

defines the actions cargoship runs during specific phases of building the distro package.

Property	Type	Required	Default	Description
`onCreate`	ZarfComponentActionSet	no		lists the actions cargoship runs when it creates the package.

Arches

BinarySelector

selects which files to upload to a host, based on host role and install method.

Property	Type	Required	Description
`arch`	Arches	no	lists the CPU architectures this file applies to. An empty list means every architecture the package targets.
`package`	`string`	no	selects which install method receives this file: rpm, apt, or binary. One of `rpm`, `apt`, `binary`.
`profile`	`string`	no	selects which host role receives this file: worker or controller. One of `worker`, `controller`.
`roles`	array of `string`	no	lists the host roles this file applies to.
`when`	`string`	no	is an optional values path (e.g. “.tools.etcdctl.enabled”) gating whether this file is uploaded.

BuildData

holds information recorded when the package was built.

Property	Type	Required	Description
`architecture`	`string`	no	is the CPU architecture used to build the package. Populated only when the package targets a single architecture. One of `amd64`, `arm64`, `riscv64`.
`architectures`	Arches	no	lists the CPU architectures used to build the package.
`fileOverrides`	map[string]`string`	no	maps each source URL prefix to the mirror or local directory files were downloaded from instead. Like RegistryOverrides, this is the configuration the build was given. For what each override actually did, see FileSources.
`fileSources`	array of FileSource	no	records every file whose source an override redirected: what the definition declared, where the bytes were read from instead, and the checksum they were verified against. It is empty for a build that used no overrides, so a package built without them is unchanged. Entries are in the order the files were staged, which is the order they appear in the definition, so a reproducible build still produces identical output.
`provenanceFiles`	array of `string`	no	lists files in the package that checksums.txt does not cover. These are files added after cargoship generates checksums, for example signature files. The signed distro.yaml authenticates this list.
`registryOverrides`	map[string]`string`	no	maps each original registry to the registry actually used to build the package.
`reproducible`	`boolean`	no	indicates Build.Timestamp was pinned to a fixed value (config.Timestamp) instead of the actual build time, so identical package inputs produce byte-identical output.
`signed`	`boolean`	no	indicates whether the package was signed. A nil value means the signing status was not recorded.
`timestamp`	`string`	no	is the time the package was created.
`version`	`string`	no	records the distro version used to build the package.

Config

holds the configuration for the distro engine.

Property	Type	Required	Description
`engine`	object	no	holds configuration passed through to the distro engine.
`files`	Files	no	lists files that cargoship writes to every host, no matter which install method it uses.
`imageConfig`	ImageConfig	no	holds settings for the images bundled with the package.
`manifests`	array of `string`	no	lists on-host paths – each one the Target of a Files entry – that cargoship kubectl-applies, in order, from the leader once it bootstraps. Delivery is already solved by Files; this is only the marker that says “and apply this one,” e.g. for a CNI a package declares. A distro with no apply mechanism (rke2/k3s use HelmChartConfig instead) ignores it.
`os`	OS	no	holds settings applied to the host operating system.

File

defines a file shared by the distro and cluster APIs.

Property	Type	Required	Description
`data`	`string`	no	holds the inline file content.
`executable`	`boolean`	no	sets executable permissions on the file when true. On a host running fapolicyd, the prepare phase also writes an allow rule for the file’s target path, so a package’s own executables are not denied by policy.
`extractPath`	`string`	no	is the path cargoship extracts from a tarball.
`group`	`string`	no	is the group that owns the file.
`isDirectory`	`boolean`	no	indicates that Target is a directory. Cargoship uses this mainly for image uploads.
`name`	`string`	no	identifies the file entry. It is not the file name on disk.
`perm`	any	no	sets the permissions cargoship applies to the file. It accepts an octal string or an integer, for example “0644” or 644.
`selector`	BinarySelector	no	controls whether cargoship uploads this file to a given node.
`shasum`	`string`	no	verifies the file when cargoship sources the distro package.
`source`	`string`	yes	is the path where cargoship finds the file when it creates the package.
`symlinks`	array of `string`	no	lists the symlinks cargoship creates that point to Target.
`target`	`string`	yes	is the path on the remote host where cargoship writes the file.
`template`	`boolean`	no	renders the file’s contents as a Go template against the package’s values before cargoship uploads it. It defaults to false, because most files are binaries or archives that a template pass would corrupt.
`user`	`string`	no	is the user that owns the file.

FileSource

records where one file in the package was actually read from, for a file whose declared source a –file-override redirected.

Property	Type	Required	Description
`declared`	`string`	yes	is the source the distro definition named.
`override`	`string`	yes	is the Source prefix of the override that matched, which is the one that won when several could have.
`path`	`string`	yes	is where the file was staged inside the package, for example “files/0/k3s”. It identifies the entry even when several files share a declared source.
`resolved`	`string`	yes	is where cargoship read the bytes from instead: a mirror URL, or a path on the build host.
`shasum`	`string`	yes	is the checksum the bytes were verified against. An override is refused for a file that declares none, so this is never empty.

Files

is an ordered list of files.

ImageConfig

holds settings for the images cargoship writes to a host.

Property	Type	Required	Default	Description
`compression`	`string`	no	`none`	sets the compression format for the image tarballs. One of `none`, `gz`, `zstd`.
`images`	array of `string`	no		lists the offline images required by the package.
`path`	`string`	no		is the upload destination for the image tarballs.

Mapping

Metadata

holds identifying information for a distro package.

Property	Type	Required	Default	Description
`aggregateChecksum`	`string`	no		is the checksum of the checksums.txt file, which lists the checksum for every layer in the package.
`annotations`	map[string]`string`	no		holds key-value pairs added to the OCI manifest.
`architecture`	`string`	no	`amd64`	is the CPU architecture this distro package targets. Use Architectures to target more than one. One of `amd64`, `arm64`, `riscv64`.
`architectures`	Arches	no		lists the CPU architectures this distro package targets. It supersedes Architecture, which stays valid for a package targeting a single architecture.
`athors`	`string`	no		sets the OCI annotation for the contact details of the people or organization responsible for the image.
`description`	`string`	no		explains what this distro package does.
`documentation`	`string`	no		sets the OCI annotation for the URL to the image documentation.
`name`	`string`	yes		identifies the distro package.
`source`	`string`	no		sets the OCI annotation for the URL to the image source code.
`uncompressed`	`boolean`	no		disables compression for this package when true.
`url`	`string`	no		sets the OCI annotation for more information about the image.
`vendor`	`string`	no		sets the OCI annotation for the name of the organization or individual that distributes the image.
`version`	`string`	no		is the distro version cargoship installs. We recommend matching it to the Kubernetes version you install.

OS

holds settings applied to a host.

Property	Type	Required	Description
`env`	map[string]`string`	no	maps environment variables cargoship sets on the host.
`fapolicyd`	`string`	no	holds the fapolicyd config file contents cargoship writes to a host.
`files`	Files	no	lists files cargoship uploads to a host.
`kernel`	array of `string`	no	lists the kernel modules cargoship enables on the host.
`selinux`	SELinux	no	holds the custom SELinux policy cargoship applies to a host.
`sysctl`	map[string]`string` or `number`	no	maps sysctl keys to the values cargoship applies to a host.

SELinux

holds the custom SELinux policy cargoship applies to hosts running SELinux in enforcing mode.

Property	Type	Required	Description
`booleans`	map[string]`boolean`	no	maps SELinux boolean names to the values cargoship sets persistently on a host.
`fileContexts`	array of SELinuxFileContext	no	lists the file context mappings cargoship adds on a host.
`modules`	array of SELinuxModule	no	lists the CIL policy modules cargoship installs on a host.

SELinuxFileContext

holds a single file context mapping cargoship adds with semanage.

Property	Type	Required	Default	Description
`fileType`	`string`	no	`all`	restricts the mapping to one kind of filesystem object. One of `all`, `file`, `dir`, `symlink`, `pipe`, `socket`, `block`, `char`.
`path`	`string`	yes		holds the path regular expression the mapping applies to.
`type`	`string`	yes		names the SELinux type the matching paths are labeled with.

SELinuxModule

holds a single CIL policy module cargoship installs with semodule.

Property	Type	Required	Default	Description
`cil`	`string`	yes		holds the Common Intermediate Language policy source semodule installs.
`name`	`string`	yes		identifies the module to semodule, and names the file cargoship writes to the host.
`priority`	`integer`	no	`400.0`	holds the semodule priority the module installs at.

SetValue

Property	Type	Required	Description
`key`	`string`	no
`type`	`string`	no
`value`	any	no	Accepts any value; cargoship does not constrain its shape here.

Shell

Property	Type	Required	Description
`darwin`	`string`	no	(default ‘sh’) Indicates a preference for the shell to use on macOS systems
`linux`	`string`	no	(default ‘sh’) Indicates a preference for the shell to use on Linux systems
`windows`	`string`	no	(default ‘powershell’) Indicates a preference for the shell to use on Windows systems (note that choosing ‘cmd’ will turn off migrations like touch -> New-Item)

Spec

holds the configuration for a distro package.

Property	Type	Required	Description
`actions`	Actions	no	defines the actions cargoship runs while building the package.
`config`	Config	yes	holds the distro engine configuration.
`type`	`string`	yes	selects the distro engine: rke2, k3s, or upstream. One of `rke2`, `k3s`, `upstream`.
`values`	Values	no	holds the default values the package is built with, and the schema they must satisfy.
`version`	`string`	yes	is the version of the distro engine.

ValueMapping

projects one value onto one place in the engine configuration.

Property	Type	Required	Default	Description
`source`	`string`	yes		is the dotted path to read from the resolved values, e.g. .cilium.encryption.enabled
`target`	`string`	yes		is the dotted path to write, relative to spec.config.engine, e.g. .manifest.rke2-cilium.encryption.enabled

Values

declares the values a package ships with.

Property	Type	Required	Description
`files`	array of `string`	no	lists the YAML values files cargoship merges, in order, to build the package’s default values. Each entry is a path relative to the package definition, an absolute path, or a URL. A later file overrides an earlier one, key by key.
`mappings`	array of ValueMapping	no	project values onto the engine configuration, so that one value a cluster sets reaches wherever the distro needs it. Each mapping reads the source path out of the resolved values and writes it to the target path, which is relative to spec.config.engine. A source the values do not define is left alone, so the package’s own engine configuration stands as the default.
`schema`	`string`	no	is the JSON Schema document the merged values must satisfy. Cargoship checks the values against it when it builds the package, and refuses to build when they do not match. The schema must not use $ref.

Variable

Property	Type	Required	Description
`autoIndent`	`boolean`	no
`name`	`string`	yes
`pattern`	`string`	no
`sensitive`	`boolean`	no
`type`	`string`	no	One of `raw`, `file`.

ZarfComponentAction

Property	Type	Required
`cmd`	`string`	no
`description`	`string`	no
`dir`	`string`	no
`env`	array of `string`	no
`maxRetries`	`integer`	no
`maxTotalSeconds`	`integer`	no
`mute`	`boolean`	no
`setValues`	array of SetValue	no
`setVariable`	`string`	no
`setVariables`	array of Variable	no
`shell`	Shell	no
`template`	`boolean`	no
`wait`	ZarfComponentActionWait	no

ZarfComponentActionDefaults

Property	Type	Required
`dir`	`string`	no
`env`	array of `string`	no
`maxRetries`	`integer`	no
`maxTotalSeconds`	`integer`	no
`mute`	`boolean`	no
`shell`	Shell	no

ZarfComponentActionSet

Property	Type	Required
`after`	array of ZarfComponentAction	no
`before`	array of ZarfComponentAction	no
`defaults`	ZarfComponentActionDefaults	no
`onFailure`	array of ZarfComponentAction	no
`onSuccess`	array of ZarfComponentAction	no

ZarfComponentActionWait

Property	Type	Required	Default	Description
`cluster`	ZarfComponentActionWaitCluster	no
`network`	ZarfComponentActionWaitNetwork	no

ZarfComponentActionWaitCluster

Property	Type	Required
`condition`	`string`	no
`kind`	`string`	yes
`name`	`string`	yes
`namespace`	`string`	no

ZarfComponentActionWaitNetwork

Property	Type	Required	Description
`address`	`string`	yes
`code`	`integer`	no
`protocol`	`string`	yes	One of `tcp`, `http`, `https`.

Keyboard shortcuts