cozystack/packages/apps/kubernetes-nodes

Kubernetes Worker Node Pool

kubernetes-nodes manages a single worker node pool for a managed Kubernetes cluster. It is the worker half of the Kubernetes-app split (see cozystack/community#8): the control plane lives in the kubernetes chart, and each pool is a separate kubernetes-nodes release attached to a parent cluster by name.

A KubernetesNodes CR named <cluster>-<pool> (e.g. myk8s-md0) provisions a MachineDeployment + KubevirtMachineTemplate + MachineHealthCheck wired to the parent cluster kubernetes-<cluster> in the same namespace, plus a talos-reconcile Job that produces the pool's TalosConfigTemplate.

Parameters

Linkage

Name	Description	Type	Value
cluster	Name of the parent Kubernetes cluster (the Kubernetes CR) in the same namespace this node pool attaches to. Required. The pool's CAPI objects are wired to the parent cluster kubernetes-<cluster>; the KubernetesNodes CR must be named <cluster>-<pool>. The pool name (the part after <cluster>-) must not collide with a nodeGroup still managed by the parent kubernetes chart (e.g. the default md0), or the render fails on ownership conflict.	string	""

Common Parameters

Name	Description	Type	Value
storageClass	StorageClass for the worker node system disk. When empty, the cluster default applies. Worker VMs live-migrate, so their disks need ReadWriteMany — the RWX access mode is supplied by the chosen StorageClass's CDI StorageProfile — and linstor-csi rejects RWX volumes that are not on a DRBD-backed StorageClass, so prefer a replicated/DRBD class.	string	replicated

Pool Sizing

Name	Description	Type	Value
minReplicas	Minimum number of replicas in this pool. Used as the cluster-autoscaler floor.	int	0
maxReplicas	Maximum number of replicas in this pool. Used as the cluster-autoscaler ceiling.	int	10
instanceType	Virtual machine instance type.	string	u1.medium
diskSize	System disk size for the worker VM. Carries the Talos OS image (factory.talos.dev raw artifact streamed in by CDI), kubelet state, containerd image cache, and any local-path PVCs.	quantity	20Gi
roles	List of node roles. Each role r labels nodes with node-role.kubernetes.io/<r>. Use [ingress-nginx] for a pool that hosts the tenant ingress-nginx controller.	[]string	[]
resources	Explicit CPU and memory for each worker node, as an alternative to instanceType sizing. Optional: when omitted, the node is sized by instanceType. When both cpu and memory are set, they take precedence and instanceType is ignored (the instancetype is omitted from the VM, since KubeVirt cannot override an instancetype's CPU/memory). Set both cpu and memory together or neither; setting only one is rejected at render time.	object	{}
resources.cpu	CPU available.	quantity	""
resources.memory	Memory (RAM) available.	quantity	""
gpus	List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM).	[]object	[]
gpus[i].name	Name of GPU, such as "nvidia.com/AD102GL_L40S".	string	""
kubelet	Kubelet resource reservations for this pool.	object	{}
kubelet.systemReservedMemory	Memory reserved for host OS. Auto-computed from instanceType if empty.	string	""
kubelet.kubeReservedMemory	Memory reserved for kubelet and container runtime. Auto-computed from instanceType if empty.	string	""
kubelet.systemReservedCpu	CPU reserved for host OS. Auto-computed from instanceType if empty.	string	""
kubelet.kubeReservedCpu	CPU reserved for kubelet and container runtime. Auto-computed from instanceType if empty.	string	""
kubelet.evictionHardMemory	Hard eviction threshold for memory (absolute like 200Mi or percentage like 7%).	string	7%
kubelet.evictionSoftMemory	Soft eviction threshold for memory (absolute like 1Gi or percentage like 10%).	string	10%
logSerialConsole	Stream each worker VM's guest serial console into a guest-console-log container beside virt-launcher, readable with kubectl logs. The only view of a worker that stalls during boot before Talos apid answers, when neither a Node nor a certificate request exists to diagnose from. Two costs the field name does not show. Changing the value rolls the pool, because it is part of the worker VM template whose name is a hash of its content -- including the stuck VM whose console was wanted, so it buys visibility into the next boot rather than the current one. And it overrides the platform's cluster-wide disableSerialConsoleLog, set because that container has been seen holding virt-launcher in PodInitializing (kubevirt/kubevirt#15989), which would take the pool down rather than explain it -- so check that virt-launcher Pods reach Running after enabling it.	bool	false
maxUnhealthy	Maximum number of unhealthy nodes tolerated in this pool before remediation is paused. The MachineHealthCheck admission webhook accepts either a bare integer ("0", "1", ...) or a percentage ("0%", "50%"); bare numeric strings are rejected, so the safer default is a percentage. Drop to "0%" once the pool is stable.	string	50%
nodeStartupTimeout	Maximum time a Machine is allowed to spend reaching the Ready condition before it is remediated. Raise for slow first boots (Talos image fetch from factory.talos.dev or a busy storage class on the kubevirt-csi PVC populator).	string	10m

Kubernetes Version

Name	Description	Type	Value
version	Kubernetes major.minor version the pool joins. Must match the parent cluster's version and satisfy the Talos<->Kubernetes support matrix against talos.version.	string	v1.35

Talos Worker Image

Name	Description	Type	Value
talos	Talos worker image configuration. Keep in sync with the parent cluster's talos.	object	{}
talos.version	Talos release used for worker OS image and installer. Must satisfy the chart's Talos<->Kubernetes support matrix against the chosen version.	string	v1.13.6
talos.schematicID	Talos image-factory schematic ID. Defaults to the cozystack-tested vanilla schematic. Operators using custom schematics (system extensions, kernel args) override here.	string	ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515
talos.imageFactoryURL	Base URL of the Talos Image Factory that serves the worker OS disk image (the openstack-amd64.raw.xz raw artifact streamed in by CDI over HTTP). Defaults to the public factory. Point at a self-hosted Image Factory, a caching mirror, or an internal HTTP file server for air-gapped, rate-limited, or flaky-egress environments. No trailing slash.	string	https://factory.talos.dev
talos.installerRepository	OCI repository prefix for the Talos installer image used by the in-guest talos-reconcile upgrade Job. Resolved as <installerRepository>/<schematicID>:<version>. Defaults to the public factory's installer path. Override for air-gapped or mirrored registries. No trailing slash.	string	factory.talos.dev/installer
talos.registryMirrors	Talos machine.registries.mirrors passthrough for worker nodes: a map of upstream registry host to { endpoints: [ ... ] }. Empty by default, so workers pull container images (the Talos kubelet image included) directly from the upstream registry. Point a host such as ghcr.io at an in-cluster pull-through mirror for air-gapped, rate-limited, or flaky-egress environments so a worker's boot does not depend on live public egress. Talos still falls back to the upstream registry unless a host also sets skipFallback: true, so a mirror alone does not enforce air-gap. Keep in sync with the parent kubernetes chart.	object	{}

Images

Name	Description	Type	Value
images	Optional image overrides for air-gapped or rate-limited registries.	object	{}
images.kubectl	Image used by the talos-reconcile Job (kubectl). Empty falls back to images/kubectl.tag.	string	""