# Upgrade Worker Node OS Using a New Node Group

Use this procedure to upgrade the operating system (OS) of worker nodes in a <code class="expression">space.vars.product\_name</code>(<code class="expression">space.vars.product\_acronym</code>) Kubernetes cluster. Instead of updating nodes in place, <code class="expression">space.vars.product\_acronym</code> 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.

{% hint style="info" %}
To upgrade the Kubernetes version instead of the OS, see [https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2026.1/pcd-kubernetes-clusters/upgrade-kubernetes-clusters.md](https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2026.1/pcd-kubernetes-clusters/upgrade-kubernetes-clusters.md "mention").
{% endhint %}

### 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](/private-cloud-director/2026.1/kubernetes-clusters/kubernetes-operating-system-image-management.md).

### 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**.

<code class="expression">space.vars.product\_acronym</code> begins provisioning the new worker nodes.

{% hint style="info" %}
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.
{% endhint %}

### 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 [https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2026.1/pcd-kubernetes-clusters/scale-kubernetes-clusters.md](https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2026.1/pcd-kubernetes-clusters/scale-kubernetes-clusters.md "mention").

### 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`

{% hint style="info" %}
You can also verify the OS image version from the worker node VM details page.
{% endhint %}

### Step 5: Complete the migration

<code class="expression">space.vars.product\_acronym</code> 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.

{% hint style="info" %}
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.
{% endhint %}

### Rollback

If you encounter issues during migration, you can roll back using the old node group. <code class="expression">space.vars.product\_acronym</code> 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:

* [https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2026.1/pcd-kubernetes-clusters/upgrade-kubernetes-clusters.md](https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2026.1/pcd-kubernetes-clusters/upgrade-kubernetes-clusters.md "mention"): Upgrade the Kubernetes version of your cluster.
* [https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2026.1/pcd-kubernetes-clusters/scale-kubernetes-clusters.md](https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2026.1/pcd-kubernetes-clusters/scale-kubernetes-clusters.md "mention"): Adjust the number of worker nodes in a node group.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/2026.1/kubernetes-clusters/kubernetes-operating-system-image-management/upgrade-worker-node-os-using-a-new-node-group.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.