cluster

type ZarfCluster struct {
	// APIVersion identifies the API group and version of this configuration document.
	APIVersion string `json:"apiVersion,omitempty" jsonschema:"enum=zarf.dev/v1alpha1"`
	// Kind identifies the document type. The value must be ZarfCluster.
	Kind v1alpha1.ZarfDistroKind `json:"kind" jsonschema:"enum=ZarfCluster"`
	// Metadata holds identifying information for the cluster.
	Metadata ZarfClusterMetadata `json:"metadata"`
	// Spec holds the configuration and hosts for the cluster.
	Spec ZarfClusterSpec `json:"spec"`
	// RuntimeMetadata stores data gathered while the phases run.
	RuntimeMetadata ZarfRuntimeMeta `json:"-"`
}

type ZarfClusterConfig struct {
	// LoadBalancer is the hostname clients use to reach the cluster control plane.
	LoadBalancer string `json:"loadbalancer" jsonschema:"format=hostname"`
	// Registries lists the container registries the cluster uses.
	Registries []ZarfClusterRegistries `json:"registries,omitempty"`
	// Profiles maps a profile name to host and engine overrides that a host can select.
	Profiles map[string]ZarfClusterProfiles `json:"profiles,omitempty"`
}

type ZarfClusterFiles struct {
	// Name identifies the file in the cluster configuration.
	Name string `json:"name"`
	// Source is the local path or URL cargoship reads the file from.
	Source string `json:"src,omitempty"`
	// Destination is the path on the host where cargoship writes the file.
	Destination string `json:"dst,omitempty"`
	// DestinationDirectory is the directory on the host where cargoship writes the file.
	DestinationDirectory string `json:"dstDir,omitempty"`
	// Permission sets the file mode cargoship applies on the host.
	Permission string `json:"perm,omitempty"`
	// User identifies the file owner on the host.
	User string `json:"user,omitempty" jsonschema:"example=root"`
	// Group identifies the file group on the host.
	Group string `json:"group,omitempty" jsonschema:"example=root"`
	// Data holds inline content for the file, as an alternative to Source.
	Data string `json:"data,omitempty"`
}

type ZarfClusterMetadata struct {
	// Name sets the cluster name. If you allow cargoship to update the kubeconfig, cargoship uses this name there.
	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
}

type ZarfClusterProfiles struct {
	// Host holds the configuration overrides applied to a host that selects this profile.
	Host ZarfHostConfig `json:"host,omitempty"`
	// Engine holds the node label and taint overrides applied to a host that selects this profile.
	Engine ZarfHostEngine `json:"engine,omitempty"`
	// Concurrency 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.
	Concurrency string `` /* 136-byte string literal not displayed */
}

type ZarfClusterRegistrieName string

type ZarfClusterRegistries struct {
	// Name 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.
	Name ZarfClusterRegistrieName `json:"name"`
	// Authentication holds the credentials for the registry.
	Authentication ZarfClusterRegistryAuth `json:"auth,omitempty"`
	// Proxy holds the pull redirect settings for the registry. Omit it to configure credentials
	// or TLS for the registry without redirecting pulls away from it.
	Proxy *ZarfClusterRegistryProxy `json:"proxy,omitempty"`
	// TLS configures TLS verification and certificates for the registry endpoint.
	TLS *ZarfClusterRegistryTLS `json:"tls,omitempty"`
}

type ZarfClusterRegistryAuth struct {
	// Username is the login name for the remote registry.
	Username string `json:"user,omitempty" jsonschema:"example=myuser,example=$ANSIBLE_VAULT;1.1;AES256..."`
	// Password is the login secret for the remote registry.
	Password string `json:"pass,omitempty" jsonschema:"example=hunter2,example=$ANSIBLE_VAULT;1.1;AES256..."`
	// Token authenticates to the remote registry instead of a username and password.
	Token string `json:"token,omitempty" jsonschema:"example=abc123,example=$ANSIBLE_VAULT;1.1;AES256..."`
}

type ZarfClusterRegistryProxy struct {
	// URL is the registry address the engine pulls from instead of the original registry.
	URL string `json:"url"`
	// Rewrite 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
	Rewrite map[string]string `json:"rewrite,omitempty"`
}

type ZarfClusterRegistryTLS struct {
	// CA 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.
	CA string `json:"ca,omitempty"`
	// CAFile is the path on the host to the CA bundle used to verify the registry certificate.
	CAFile string `json:"caFile,omitempty"`
	// CertFile is the path on the host to the client certificate used to authenticate to the registry.
	CertFile string `json:"certFile,omitempty"`
	// KeyFile is the path on the host to the client private key used to authenticate to the registry.
	KeyFile string `json:"keyFile,omitempty"`
	// InsecureSkipVerify disables TLS certificate verification.
	InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`
}

type ZarfClusterSpec struct {
	// Config holds the cluster-wide configuration.
	Config ZarfClusterConfig `json:"config"`
	// Hosts lists the hosts that make up the cluster.
	Hosts ZarfHosts `json:"hosts" jsonschema:"minItems=1"`
}

type ZarfFirewallConfig struct {
	// Rules lists the firewall rules cargoship applies to the node.
	Rules []ZarfFirewallRule `json:"rules,omitempty"`
}

type ZarfFirewallPolicyConfig struct {
	// XMLName sets the element name cargoship uses when it marshals this policy to firewalld XML.
	XMLName xml.Name `xml:"policy" json:"-"`
	// Short is a human-readable description of the policy.
	Short string `xml:"short,omitempty" json:"-"`
	// Target is the action taken on traffic that matches the policy.
	Target string `xml:"target,attr,omitempty" json:"target" jsonschema:"enum=CONTINUE,enum=ACCEPT,enum=REJECT,enum=DROP"`
	// Ingress is the zone the policy allows traffic from.
	Ingress ZarfFirewallZone `xml:"ingress-zone"`
	// Egress is the zone the policy allows traffic to.
	Egress ZarfFirewallZone `xml:"egress-zone"`
	// Ports lists the ports this policy allows.
	Ports []ZarfFirewallPort `xml:"port,omitempty" json:"ports,omitempty"`
}

type ZarfFirewallPort struct {
	// Protocol is the type of allowed traffic.
	Protocol string `xml:"protocol,attr" json:"protocol" jsonschema:"enum=tcp,enum=udp,enum=sctp,enum=dccp"`
	// Port is the port number, or port range, cargoship opens.
	Port string `xml:"port,attr" json:"port" jsonschema:"oneof_type=string;integer"`
}

type ZarfFirewallRule struct {
	// Name 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.
	Name string `json:"name,omitempty" jsonschema:"example=allow-metrics"`
	// Action is what cargoship does with traffic that matches the rule.
	Action string `json:"action" jsonschema:"required,enum=allow,enum=deny,enum=reject"`
	// Direction selects which traffic the rule matches. It defaults to in.
	Direction string `json:"direction,omitempty" jsonschema:"enum=in,enum=out,enum=forward,default=in"`
	// Source is the address or CIDR the traffic comes from.
	Source string `json:"source,omitempty" jsonschema:"example=10.0.0.0/8"`
	// Destination is the address or CIDR the traffic goes to.
	Destination string `json:"destination,omitempty" jsonschema:"example=10.42.0.0/16"`
	// Ingress names where forward traffic enters. It is a zone on firewalld hosts and an
	// interface on ufw hosts. It applies to forward rules only.
	Ingress string `json:"ingress,omitempty" jsonschema:"example=public"`
	// Egress names where forward traffic leaves. It is a zone on firewalld hosts and an
	// interface on ufw hosts. It applies to forward rules only.
	Egress string `json:"egress,omitempty" jsonschema:"example=trusted"`
	// Port is the port number, or inclusive port range, the rule matches.
	Port string `json:"port,omitempty" jsonschema:"oneof_type=string;integer,example=6443,example=30000-32767"`
	// Protocol is the type of traffic the rule matches.
	Protocol string `json:"protocol,omitempty" jsonschema:"enum=tcp,enum=udp,enum=sctp,enum=dccp"`
}

type ZarfFirewallZone struct {
	// Name identifies the firewalld zone.
	Name string `xml:"name,attr" jsonschema:"example=trusted,example=public"`
}

type ZarfHost struct {
	// Connection embeds rig's connection type. It gives ZarfHost multi-protocol connectivity to a remote host.
	rig.Connection `json:",inline"`
	// Environment maps environment variables cargoship sets on the host.
	Environment map[string]string `json:"environment,omitempty"`
	// Files lists files cargoship uploads to the host.
	Files []ZarfClusterFiles `json:"files,omitempty"`
	// Hostname overrides the discovered name of the node.
	Hostname string `json:"hostname,omitempty"`
	// PrivateAddress overrides the discovered private address of the node.
	PrivateAddress string `json:"privateAddress,omitempty"`
	// PrivateInterface overrides the discovered private interface of the node.
	PrivateInterface string `json:"privateInterface,omitempty"`
	// Profile selects a profile by name from the cluster config's Profiles map.
	Profile string `json:"profile,omitempty"`
	// Role sets the node role when cargoship adds this host to the cluster. It must be controller or worker.
	Role string `json:"role" jsonschema:"required,enum=controller,enum=worker"`
	// Host holds the host-level configuration overrides for this node.
	Host ZarfHostConfig `json:"host,omitempty"`
	// Engine holds the node label and taint overrides for this node.
	Engine ZarfHostEngine `json:"engine,omitempty"`
	// Configurer is the per-host operations implementation cargoship uses to manage this host.
	Configurer os.Configurer `json:"-"`
	// Metadata holds values cargoship discovers about this host at runtime.
	Metadata ZarfHostMetadata `json:"-"`
}

type ZarfHostConfig struct {
	// Firewall holds the backend-neutral firewall rules cargoship renders onto whichever
	// firewall the node runs, firewalld, ufw, or nftables.
	Firewall ZarfFirewallConfig `json:"firewall,omitempty"`
	// Policy 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.
	Policy map[string]ZarfFirewallPolicyConfig `json:"policy,omitempty"`
	// Ports lists the ports and protocols cargoship opens on the node.
	Ports []ZarfHostPort `json:"ports,omitempty" xml:"port"`
}

type ZarfHostEngine struct {
	// NodeLabels maps Kubernetes node label keys to their values.
	NodeLabels map[string]string `json:"labels,omitempty"`
	// NodeTaints lists the Kubernetes node taints cargoship applies to the node.
	NodeTaints []string `json:"taints,omitempty"`
}

type ZarfHostGroup struct {
	// Profile is the profile name shared by Hosts. Empty for hosts that selected no profile.
	Profile string
	// Hosts are the hosts that selected Profile, in their original relative order.
	Hosts ZarfHosts
}

type ZarfHostMetadata struct {
	// Arch is the CPU architecture detected on the host.
	Arch string
	// BinaryTempFile lists temporary paths on the host cargoship uses to stage the engine binary during install.
	BinaryTempFile []string
	// DistroVersion is the version of the distro engine detected on the host.
	DistroVersion string
	// EngineUploaded indicates whether cargoship has already uploaded the distro engine binary to the host.
	EngineUploaded bool
	// ExistingConfig is the engine configuration currently present on the host.
	ExistingConfig string
	// Hostname is the hostname the host reports.
	Hostname string
	// Install is the function cargoship calls to install the distro engine on the host.
	Install func(context.Context, *ZarfHost) error
	// Installed indicates whether a distro engine is already installed on the host.
	Installed bool
	// IsLeader indicates whether this host is the cluster's control-plane leader.
	IsLeader bool
	// MachineID identifies the node to the distro engine.
	MachineID string
	// ModulesAdded indicates whether cargoship added a new kernel module to the host.
	ModulesAdded bool
	// NeedsUpgrade indicates whether the host needs the distro engine upgraded.
	NeedsUpgrade bool
	// NewConfig is the engine configuration cargoship will write to the host.
	NewConfig string
	// Ready indicates whether the distro service is up and running.
	Ready bool
	// UploadedFiles lists "category\tpath" entries cargoship uploaded to this host during the
	// current run. It is used to detect files a previous version left behind that the current
	// upload no longer produces, e.g. an engine binary renamed by a version bump.
	UploadedFiles []string
}

type ZarfHostPort struct {
	// Protocol is the type of allowed traffic.
	Protocol string `json:"protocol" xml:"protocol,attr" jsonschema:"enum=tcp,enum=udp"`
	// Port is the port number, or port range, cargoship opens.
	Port string `json:"port" xml:"port,attr" jsonschema:"oneof_type=string;integer"`
}

type ZarfHosts []*ZarfHost

type ZarfRuntimeMeta struct {
	// ControllerTLS lists the names and addresses on the controller TLS certificate.
	ControllerTLS []string
	// ControllerToken authorizes a worker node to join the cluster as a controller.
	ControllerToken string
	// AgentToken authorizes a worker node to join the cluster as an agent.
	AgentToken string
	// LoadBalancer is the hostname clients use to reach the cluster control plane.
	LoadBalancer string
	// Leader is the controller host that stores the cluster join tokens.
	Leader *ZarfHost
	// Registries lists the container registries the cluster uses.
	Registries []ZarfClusterRegistries
}