Cluster configuration
is the root object of a cluster configuration document.
Rendered from schema/cluster-v1alpha1-schema.json.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
apiVersion | string | no | identifies the API group and version of this configuration document. One of colonel-byte.dev/v1alpha1, zarf.dev/v1alpha1. | |
kind | string | yes | identifies the document type. The value must be Cluster, or ZarfCluster on a document written before the move to colonel-byte.dev. One of Cluster, ZarfCluster. | |
metadata | Metadata | yes | holds identifying information for the cluster. | |
spec | Spec | yes | holds the configuration and hosts for the cluster. |
AgeEncryption
records the age recipients a document’s credentials were encrypted to.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
lastModified | string | no | is when cargoship last rewrote the credentials in this document, in RFC 3339. | |
recipients | array of string | no | lists the age public keys cargoship encrypted to, in the order they were given. An SSH key keeps its authorized_keys comment, since that is the part that says whose key it is. |
Config
holds cluster-wide configuration.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
loadbalancer | string | yes | is the hostname clients use to reach the cluster control plane. | |
profiles | map[string]Profiles | no | maps a profile name to host and engine overrides that a host can select. | |
registries | array of Registries | no | lists the container registries the cluster uses. | |
values | object | no | overrides the values the distro package was built with. It is the same nested structure the package ships, addressed by the same dotted paths, and it must still satisfy the package’s values schema. Keys the package does not define are kept, so a cluster can carry values a later package version reads. |
Encryption
records how the credentials in a document were encrypted.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
age | AgeEncryption | no | records the age recipients this document’s credentials were encrypted to. Nothing verifies this list and nothing can: an age header carries no recipient identifier, so editing it changes what the file claims and not a byte of what it holds. |
Files
defines a file to write to a host.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
data | string | no | holds inline content for the file, as an alternative to Source. | |
dst | string | no | is the path on the host where cargoship writes the file. | |
dstDir | string | no | is the directory on the host where cargoship writes the file. | |
group | string | no | identifies the file group on the host. | |
name | string | yes | identifies the file in the cluster configuration. | |
perm | string | no | sets the file mode cargoship applies on the host. | |
src | string | no | is the local path or URL cargoship reads the file from. | |
user | string | no | identifies the file owner on the host. |
FirewallConfig
is the backend-neutral firewall configuration for a node.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
rules | array of FirewallRule | no | lists the firewall rules cargoship applies to the node. |
FirewallPolicyConfig
configures a firewalld policy that opens ports from one zone to another.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
egress | FirewallZone | yes | is the zone the policy allows traffic to. | |
ingress | FirewallZone | yes | is the zone the policy allows traffic from. | |
ports | array of FirewallPort | no | lists the ports this policy allows. | |
target | string | yes | is the action taken on traffic that matches the policy. One of CONTINUE, ACCEPT, REJECT, DROP. |
FirewallPort
defines a port allowed through the firewalld policy.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
port | string or integer | yes | is the port number, or port range, cargoship opens. | |
protocol | string | yes | is the type of allowed traffic. One of tcp, udp, sctp, dccp. |
FirewallRule
is a single backend-neutral firewall rule.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
action | string | yes | is what cargoship does with traffic that matches the rule. One of allow, deny, reject. | |
destination | string | no | is the address or CIDR the traffic goes to. | |
direction | string | no | in | selects which traffic the rule matches. It defaults to in. One of in, out, forward. |
egress | string | no | names where forward traffic leaves. It is a zone on firewalld hosts and an interface on ufw hosts. It applies to forward rules only. | |
ingress | string | no | names where forward traffic enters. It is a zone on firewalld hosts and an interface on ufw hosts. It applies to forward rules only. | |
name | string | no | identifies the rule. Cargoship uses it to name the artifacts it writes on the node, so it must be unique within a host. Cargoship generates one when it is empty. | |
port | string or integer | no | is the port number, or inclusive port range, the rule matches. | |
protocol | string | no | is the type of traffic the rule matches. One of tcp, udp, sctp, dccp. | |
source | string | no | is the address or CIDR the traffic comes from. |
FirewallZone
is the name of either the ingress or egress zone for a policy.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | yes | identifies the firewalld zone. |
Host
is a remote connection to a node
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
engine | HostEngine | no | holds the node label and taint overrides for this node. | |
environment | map[string]string | no | maps environment variables cargoship sets on the host. | |
files | array of Files | no | lists files cargoship uploads to the host. | |
host | HostConfig | no | holds the host-level configuration overrides for this node. | |
hostname | string | no | overrides the discovered name of the node. | |
localhost | boolean | no | ||
openSSH | OpenSSHConfig | no | ||
privateAddress | string | no | overrides the discovered private address of the node. | |
privateInterface | string | no | overrides the discovered private interface of the node. | |
profile | string | no | selects a profile by name from the cluster config’s Profiles map. | |
role | string | yes | sets the node role when cargoship adds this host to the cluster. It must be controller or worker. One of controller, worker. | |
ssh | SSHConfig | no | ||
winRM | WinRMConfig | no |
HostConfig
defines the configuration for a specific host, including firewall policies and the ports cargoship opens on the node.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
firewall | FirewallConfig | no | holds the backend-neutral firewall rules cargoship renders onto whichever firewall the node runs, firewalld, ufw, or nftables. | |
policy | map[string]FirewallPolicyConfig | no | maps a policy name to a firewalld policy that allows traffic from one interface to another. It is firewalld-only; prefer forward rules under firewall.rules for new configuration. | |
ports | array of HostPort | no | lists the ports and protocols cargoship opens on the node. |
HostEngine
defines configuration options for node-level metadata, specifically Kubernetes node labels and taints applied to a cluster host.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
labels | map[string]string | no | maps Kubernetes node label keys to their values. | |
taints | array of string | no | lists the Kubernetes node taints cargoship applies to the node. |
HostPort
is a port cargoship opens on the public side of the firewall.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
port | string or integer | yes | is the port number, or port range, cargoship opens. | |
protocol | string | yes | is the type of allowed traffic. One of tcp, udp. |
Hosts
is an ordered list of hosts that cargoship manages together.
Metadata
holds identifying information for a cluster.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
encryption | Encryption | no | records how the credentials in this document were encrypted. Cargoship writes it and never reads it back as key material, because an age header names no recipient: this records what was done, not a fact anything can check against the ciphertext beside it. | |
name | string | yes | sets the cluster name. If you allow cargoship to update the kubeconfig, cargoship uses this name there. |
OpenSSHConfig
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
address | string | yes | Address of the remote host | |
configPath | string | no | Path to SSH config file | |
disableMultiplexing | boolean | no | false | Disable SSH connection multiplexing |
keyPath | string | no | Path to SSH private key | |
options | OptionArguments | no | Additional SSH options as ssh_config key-value pairs | |
port | integer | no | Optional SSH port | |
user | string | no | Optional SSH user |
OptionArguments
Profiles
holds the host and engine overrides for one profile.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
concurrency | string or integer | no | limits how many hosts using this profile cargoship processes at once, e.g. draining, upgrading, initializing, or uninstalling. It accepts a fixed count (“1”) or a percentage of the hosts sharing this profile (“25%”). Empty falls back to the phase’s default concurrency. | |
engine | HostEngine | no | holds the node label and taint overrides applied to a host that selects this profile. | |
host | HostConfig | no | holds the configuration overrides applied to a host that selects this profile. |
Registries
holds the credentials and pull proxy for one container registry.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
auth | RegistryAuth | no | holds the credentials for the registry. | |
name | string | yes | identifies the registry. With a proxy it is the registry pulls are redirected away from; without one it is the registry the credentials authenticate to. | |
proxy | RegistryProxy | no | holds the pull redirect settings for the registry. Omit it to configure credentials or TLS for the registry without redirecting pulls away from it. | |
tls | RegistryTLS | no | configures TLS verification and certificates for the registry endpoint. |
RegistryAuth
holds the credentials for a container registry.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
pass | string | no | is the login secret for the remote registry. Sensitive. Treat this value as a secret: it is a credential rather than a path to one. | |
token | string | no | authenticates to the remote registry instead of a username and password. Sensitive. Treat this value as a secret: it is a credential rather than a path to one. | |
user | string | no | is the login name for the remote registry. Sensitive. Treat this value as a secret: it is a credential rather than a path to one. |
RegistryProxy
redirects pulls for a registry to a different URL.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
rewrite | map[string]string | no | maps a regex pattern to a replacement, transforming the image name (not the tag) before it is pulled from this mirror. See https://docs.rke2.io/install/private_registry#rewrites | |
url | string | yes | is the registry address the engine pulls from instead of the original registry. |
RegistryTLS
holds the TLS connection settings for a container registry.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
ca | string | no | is the PEM-encoded CA certificate used to verify the registry certificate. Cargoship writes it to a file on each host and points the engine at that path, so the certificate travels with the cluster configuration instead of having to be distributed separately. Use CAFile instead when the certificate is already on the hosts. It may also be given as an Ansible Vault-encrypted string, which cargoship decrypts at apply time. | |
caFile | string | no | is the path on the host to the CA bundle used to verify the registry certificate. | |
certFile | string | no | is the path on the host to the client certificate used to authenticate to the registry. | |
insecureSkipVerify | boolean | no | disables TLS certificate verification. | |
keyFile | string | no | is the path on the host to the client private key used to authenticate to the registry. |
SSHConfig
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
address | string | yes | Address of the remote host (IP or hostname) | |
bastion | SSHConfig | no | Optional bastion host | |
ignoreSshConfig | boolean | no | Do not read ~/.ssh/config or the system ssh_config for this host | |
keyPath | string | no | Path to SSH private key | |
options | OptionArguments | no | Additional SSH options as ssh_config key-value pairs | |
port | integer | no | 22.0 | SSH port (default 22) |
user | string | no | root | User to log in as |
Spec
holds the configuration and hosts for a cluster.
WinRMConfig
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
address | string | yes | Address of the remote host | |
bastion | SSHConfig | no | Optional SSH bastion | |
caCertPath | string | no | Path to CA certificate | |
certPath | string | no | Path to client certificate | |
insecure | boolean | no | false | Accept invalid TLS certificates |
keyPath | string | no | Path to client key | |
password | string | no | Password for WinRM authentication | |
port | integer | no | WinRM port (default 5985; 5986 when useHTTPS is true) | |
tlsServerName | string | no | TLS server name override | |
useHttps | boolean | no | false | Use HTTPS for WinRM |
useNtlm | boolean | no | false | Use NTLM authentication |
user | string | no | Administrator | User to authenticate as |