Skip to content

Upgrading Clusters

Upgrade your tenant cluster's Kubernetes version. Upgrades are driven through the Cluster CR's topology — change spec.topology.version and CAPI cascades the change to the Kamaji control plane and the worker MachineDeployments.

Prerequisites

  • Check available target versions with your platform admin.
  • Review the upgrade path (Kubernetes supports +/- 1 minor; e.g. 1.34 → 1.35).
  • Schedule a maintenance window.
  • Back up tenant cluster state before upgrading (see Backup & Restore).

Upgrade Kubernetes version

# Bump the version on the Cluster topology
kubectl patch cluster my-cluster -n <tenant-namespace> --type merge \
  -p '{"spec":{"topology":{"version":"v1.35.0"}}}'

CAPI rolls the change through:

  • The KamajiControlPlane re-templates with the new version (Kamaji performs a blue/green rollout of the api-server / controller-manager / scheduler pods).
  • The MachineDeployment rolls workers one at a time with the new version's kubelet image.

Monitor the upgrade

# Top-level Cluster status
kubectl get cluster my-cluster -n <tenant-namespace>

# Kamaji control plane
kubectl get kamajicontrolplane my-cluster -n <tenant-namespace>
kubectl get tenantcontrolplane my-cluster -n <tenant-namespace>

# Worker rollout
kubectl get machinedeployment -n <tenant-namespace>
kubectl get machines -n <tenant-namespace> -w

Verify upgrade

# Topology version on the Cluster
kubectl get cluster my-cluster -n <tenant-namespace> -o jsonpath='{.spec.topology.version}'

# Node versions on the tenant cluster
kubectl --kubeconfig=my-cluster.kubeconfig get nodes
kubectl --kubeconfig=my-cluster.kubeconfig get pods -n kube-system

Troubleshooting

# Cluster + control-plane events
kubectl describe cluster my-cluster -n <tenant-namespace>
kubectl describe kamajicontrolplane my-cluster -n <tenant-namespace>

# Worker rollout state
kubectl describe machinedeployment -n <tenant-namespace>
kubectl get events -n <tenant-namespace> --sort-by='.lastTimestamp'

If an upgrade fails, contact your platform administrator. Rollback is via patching spec.topology.version back to the previous value.