Skip to content

Scaling Clusters

Scale your tenant cluster's control plane and workers. Scaling is driven through the Cluster CR's topology — patch the topology and CAPI cascades the change.

Scale workers

# Patch the topology MachineDeployment replicas (canonical)
kubectl patch cluster my-cluster -n <tenant-namespace> --type=json \
  -p '[{"op":"replace","path":"/spec/topology/workers/machineDeployments/0/replicas","value":5}]'

# Verify
kubectl get machinedeployment -n <tenant-namespace>
kubectl get machines -n <tenant-namespace>

The change cascades to the auto-created MachineDeployment; CAPK provisions or removes worker VMs to match.

Direct kubectl scale machinedeployment works but reverts

kubectl scale machinedeployment <name> -n <tenant-namespace> --replicas=5 will change replicas, but CAPI re-reconciles from the topology and reverts the change unless you also patch Cluster.spec.topology.workers.machineDeployments[].replicas.

Scale the control plane

Control-plane replica count on the under cluster is set via the KamajiControlPlane.spec.replicas field. The kubevirt-kubeadm ClusterClass on the under cluster does not currently expose this as a topology variable, so changing it requires either:

  • platform-admin extension of the ClusterClass with a replicas variable, or
  • direct patching of the auto-created KamajiControlPlane (CACPK reconciles, so patches should hold if the topology doesn't re-template).

t.b.d. — A canonical scale path for control-plane replicas is t.b.d. in this section.

Auto-scaling workers

Per-tenant Cluster Autoscaler can watch a tenant cluster and scale the MachineDeployment between configured min/max bounds. Annotate the MachineDeployment that the autoscaler should manage:

# On the auto-created MachineDeployment
apiVersion: cluster.x-k8s.io/v1beta2
kind: MachineDeployment
metadata:
  name: my-cluster-md-0-<hash>
  namespace: <tenant-namespace>
  annotations:
    cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size: "1"
    cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size: "10"

The kubevirt-kubeadm ClusterClass may not auto-set these annotations — your platform admin either pre-templates them or you patch the MachineDeployment after first creation.

Monitor

# Worker rollout
kubectl get machines -n <tenant-namespace> -w
kubectl describe machine <machine-name> -n <tenant-namespace>

# Control plane state
kubectl get kamajicontrolplane my-cluster -n <tenant-namespace>
kubectl get tenantcontrolplane my-cluster -n <tenant-namespace>

Best practices

Control plane:

  • Use 1 replica for dev, 2-3 for production (the live primary's reference shape is 2 replicas per Kamaji control plane).

Workers:

  • Size workers by your workload's resource requirements (one MachineDeployment per worker shape).
  • Enable autoscaling for dynamic workloads.
  • Set sensible min/max bounds to prevent runaway scaling.
  • Monitor real resource utilization on the tenant cluster before adjusting.