# Upgrade a node group

Replace a node group's nodes with nodes at the control plane's Kubernetes minor, one extra node at a time, and resume an upgrade a disruption budget paused.

Replace _my-cluster_ with your cluster's name or id, and _workers_ with the node group's name.

## Prerequisites

- Permission for `eks:UpdateNodegroupVersion` on the node group. To change `drainTimeoutMinutes`
  or `forceAfterTimeout`, also `eks:UpdateNodegroupConfig`.
- In the console, also `eks:DescribeCluster` and `eks:ListNodegroups`. The console enables
  **Upgrade to _1.37_** and **Resume upgrade** only with `eks:UpdateNodegroupVersion` on every
  cluster (`eks:*`).
- The cluster is `active` (not while its control plane upgrades) and the control plane already
  runs the new minor: nodes never run a newer minor than the control plane.

## Start the upgrade

**Console**
1. Open **Kubernetes**, open the cluster, then choose **Node groups**.
2. On the node group's row, in the **Kubernetes** column, choose **Upgrade to _1.37_**. The button
   appears once the group's minor is behind the control plane's, and is unavailable ("Wait for the
   control plane") while the cluster is not `active`.
3. In the dialog **Upgrade _workers_ to Kubernetes _1.37_?**, choose **Upgrade to _1.37_**.

**CLI**
```sh
dcloud eks nodegroups upgrade my-cluster workers
```

Without `--version`, the group goes to the control plane's minor.

**API**
```http
PUT /eks/api/clusters/my-cluster/nodegroups/workers/version
{}
```

**Terraform**
Set `version` on the `dcloud_eks_nodegroup` to the cluster's minor and apply.

## Result

The group is `updating`. Deutsche Cloud adds one node at the new minor; once it is Ready, the oldest
node behind is cordoned and drained, and its machine removed. This repeats until no node is behind,
so the group never has fewer Ready nodes than `desiredSize`. The extra node bills as compute while it
runs.

## When a disruption budget holds a node

PodDisruptionBudgets are respected. If a node's drain waits longer than the group's
`drainTimeoutMinutes` (default 60, 5 to 1440), the upgrade **pauses** at that node: the group is
`paused`, the node stays cordoned, and the group's message names what holds it. Let the budget
allow a pod to move, then resume: choose **Resume upgrade** on the row, or run the same
`dcloud eks nodegroups upgrade` again. The node's drain then starts over.

To remove the node after the timeout instead, past its budgets:

```sh
dcloud eks nodegroups update my-cluster workers --drain-timeout-minutes 30 --force-after-timeout
```

This does not resume a group that is already `paused`; resume it as above.

**Note:**
The console's upgrade dialog, and the Activity line that starts an upgrade, say budgets are
respected for up to five minutes. For upgrades the group's `drainTimeoutMinutes` applies; five
minutes applies to scale-downs and repairs.

## Refusals

- `400` "Nodes cannot run a newer minor than the control plane (…)" or "Kubernetes cannot be
  downgraded (…)".
- `404` when the node group does not exist.
- `409` "The control plane is being upgraded; node groups follow once it is done", "The cluster is
  _creating_" (any other status than `active`), "The node group is being deleted", or "_workers_
  already runs _1.37_".

## Related

- [Upgrade the control plane](upgrade-the-control-plane.md)
- `eks.nodegroups.upgrade` · `dcloud eks nodegroups upgrade` · `dcloud_eks_nodegroup`
