Upgrade Worker Node OS Using a New Node Group

Upgrade the operating system of Kubernetes worker nodes in Private Cloud Director by replacing node groups with an updated OS image.

Use this procedure to upgrade the operating system (OS) of worker nodes in a Private Cloud Director(PCD) Kubernetes cluster. Instead of updating nodes in place, PCD replaces the existing node group with a new one running the updated OS image. This approach supports controlled rollouts and provides a straightforward rollback path.

This procedure applies to any supported OS image change, for example, Ubuntu 22.04 to Ubuntu 24.04.

To upgrade the Kubernetes version instead of the OS, see Upgrade Clusters.

Prerequisites

Before you begin:

• The cluster health status must be Healthy.

• The control plane must be Ready.

• You must have permission to manage node groups for the cluster.

• The target OS image must be available in the Available Images list. To build and upload an OS image, see Operating System Image Management.

Step 1: Verify cluster health

1. Navigate to Kubernetes > Clusters.

2. Select the target cluster and go to the Capacity and Health tab.

3. Confirm that Overall Health is Healthy and Control Plane is Ready.

4. Verify that existing node groups and worker nodes are visible.

Step 2: Add a new node group

1. On the Node Groups, select Add Node Group.

2. On the Add Node Group, configure the following:

   • Select the Virtualized Cluster.

   • Select the SSH Key.

   • Under Available Images, select the updated OS image, for example, ubuntu-2404-kube-v1.32.3.

   • Select the appropriate Virtual Machine Flavor. If required, enable Show GPU flavors only.

3. Select Add Node Group.

PCD begins provisioning the new worker nodes.

Include both the OS version and Kubernetes version in your image names, for example, ubuntu-2404-kube-v1.32.3. This makes it easier to identify the image in use.

Step 3: Manage capacity during migration

If your cluster has sufficient spare capacity, create the new node group with the same number of replicas as the existing node group. Once workloads have migrated and the cluster is stable, delete the old node group.

If your cluster has limited spare capacity, introduce the new node group gradually:

1. Start the new node group with a small number of nodes, for example, one.

2. Monitor node readiness and workload scheduling.

3. Reduce the size of the existing node group as new nodes become ready.

For details on scaling node groups, see Scale Clusters.

Step 4: Verify new nodes

After the new node group provisions:

1. Confirm the node group status shows Running.

2. In the Worker Nodes list, verify that each new node shows:

   • Kubernetes Node Status: Ready

   • Machine Status: Running

   • The expected Kubernetes version

   • The expected OS image, for example, ubuntu-2404-kube-v1.32.3

You can also verify the OS image version from the worker node VM details page.

Step 5: Complete the migration

PCD automatically schedules workloads on the new nodes as they become available. You do not need to manually drain or migrate pods.

Once all workloads are running on the new nodes and the cluster health is stable:

1. In the Node Groups table, locate the old node group.

2. Select the Actions and then select Delete.

3. Confirm the deletion.

To verify workload status before deleting the old node group, go to the Capacity and Health tab and confirm that all pods are running on the new nodes.

Rollback

If you encounter issues during migration, you can roll back using the old node group. PCD retains the old node group until you delete it.

To roll back:

1. Stop scaling down the old node group.

2. Scale the old node group back up if needed.

3. Investigate and resolve issues on the new nodes.

4. Resume migration once the cluster is stable.

Next steps

After completing the OS upgrade, you can further manage your cluster using the following resources:

• Upgrade Clusters: Upgrade the Kubernetes version of your cluster.

• Scale Clusters: Adjust the number of worker nodes in a node group.