Skip to main content
Kubernetes cluster upgrades update the control plane and worker nodes to new versions. The platform provides pre-upgrade validation, impact analysis, and rolling upgrade capabilities to minimize downtime.

​
Key Concepts

Upgrade Check

Pre-flight validation that verifies version availability and node readiness.

Impact Analysis

Assessment of cluster health, affected workloads, and risk level before upgrade.

Rolling Upgrade

Sequential upgrade of nodes with cordon/drain to maintain availability.

Selective Upgrade

Option to upgrade specific nodes instead of the entire cluster.

​
Required Permissions

​
Version Upgrade Rules

Kubernetes enforces strict version upgrade paths: Valid upgrade paths:
  • v1.28.5 → v1.28.10 (patch upgrade)
  • v1.28.5 → v1.29.0 (minor upgrade)
Invalid upgrade paths:
  • v1.28.5 → v1.30.0 (skips 1.29)
  • v1.29.0 → v1.28.5 (downgrade)

​
Upgradeable Components

​
How to Set Target Versions

1

Open Cluster Settings

Navigate to the cluster and open the Settings or Upgrade tab.
2

Configure Target Versions

Set target versions for:
  • Kubernetes version
  • containerd version (optional)
  • CNI plugin version (optional)
  • Metrics server version (optional)
3

Save Configuration

Save the upgrade configuration. This does not start the upgrade.

​
How to Run Upgrade Check

Upgrade check validates prerequisites before upgrade.
1

Open Upgrade Page

Navigate to the cluster upgrade page.
2

Click Upgrade Check

Click Upgrade Check to run pre-flight validation.
3

Review Results

The check verifies:
  • Target version availability in package repositories
  • SSH connectivity to all nodes
  • Node readiness status
Upgrade check must pass before you can proceed with the upgrade.

​
How to View Upgrade Impact

Impact analysis assesses risk and identifies potential issues.
1

Open Upgrade Page

Navigate to the cluster upgrade page.
2

View Impact Analysis

The impact analysis shows:
  • Current vs target version comparison
  • Cluster health status
  • Node readiness details
  • Affected workload count
  • Risk level assessment
  • Recommendations
3

Address Issues

Resolve any errors or warnings before proceeding.

​
Pre-Upgrade Requirements

The upgrade will be blocked if these conditions are not met:

​
Risk Levels

​
How to Upgrade a Cluster

1

Run Upgrade Check

Ensure upgrade check passes with no errors.
2

Review Impact Analysis

Verify risk level is acceptable and review recommendations.
3

Create etcd Backup

Create an etcd backup before starting (strongly recommended).
4

Start Upgrade

Click Upgrade to begin the rolling upgrade.
5

Monitor Progress

Watch the operation progress as nodes are upgraded sequentially.
Upgrade causes temporary disruption as pods are evicted and rescheduled. Plan upgrades during maintenance windows for production clusters.

​
Upgrade Process

The platform follows this sequence:
  1. Master nodes first - Control plane upgraded before workers
  2. For each node:
    • Cordon (mark unschedulable)
    • Drain (evict pods)
    • Upgrade kubeadm, kubelet, kubectl
    • Upgrade containerd (if configured)
    • Uncordon (allow scheduling)
    • Wait for node Ready
The first master node runs kubeadm upgrade apply. Subsequent nodes run kubeadm upgrade node.

​
How to Upgrade Selective Nodes

Upgrade specific nodes instead of the entire cluster.
1

Open Upgrade Page

Navigate to the cluster upgrade page.
2

Select Nodes

Choose specific nodes to upgrade from the node list.
3

Configure Options

Set upgrade options:
  • Batch size - Number of nodes to upgrade in parallel
  • Node order - Masters first, workers first, or as listed
4

Start Selective Upgrade

Click Upgrade Selected to begin.
Selective upgrade is for advanced use cases. Ensure version consistency across the cluster after selective upgrades.

​
Troubleshooting

  • Verify the target version exists in Kubernetes apt repository
  • Check that the version format is correct (e.g., 1.29.0 not v1.29)
  • Ensure nodes have internet access to download packages
  • You cannot skip minor versions - upgrade one minor version at a time
  • Example: From 1.27.x, upgrade to 1.28.x first, then 1.29.x
  • Check kubelet status on the affected node
  • Verify network connectivity to control plane
  • Review node conditions for pressure (memory, disk, PID)
  • Some pods may have PodDisruptionBudgets preventing eviction
  • Pods with local storage may not drain without force
  • Review drain logs for specific pod failures
  • SSH to the node and check kubelet status
  • Verify kubelet and containerd are running
  • Check kubelet logs for certificate or connectivity errors
  • Ensure firewall allows required ports
  • Wait for API server to restart (may take a few minutes)
  • Check API server pod status in kube-system
  • Verify kubeconfig credentials are still valid
  • Check etcd health

​
FAQ

Depends on cluster size. Each node takes several minutes for drain, upgrade, and restart. A 5-node cluster typically completes in 15-30 minutes.
Applications with multiple replicas spread across nodes experience minimal disruption. Single-replica workloads will have brief downtime when their node is drained.
Kubernetes does not support direct rollback. Restore from etcd backup if critical issues occur. Always backup before upgrading.
Not required for every K8s upgrade. Check containerd compatibility matrix for your target K8s version.
CNI plugins are upgraded separately. The platform can upgrade Calico, Flannel, or Cilium alongside Kubernetes.
The cluster may be in a mixed-version state. Resume the upgrade for remaining nodes or manually upgrade via SSH.
Yes, but there will be control plane downtime during the master upgrade. Consider adding masters for high availability before upgrading production clusters.

​
Best Practices

  • Test in non-production first - Upgrade staging clusters before production
  • Create etcd backup - Always backup before upgrading
  • Check release notes - Review Kubernetes changelog for breaking changes
  • Plan maintenance window - Schedule upgrades during low-traffic periods
  • Monitor after upgrade - Verify application health after completion
  • Keep versions current - Don’t fall too far behind; smaller jumps are safer