# Upgrade the control plane

Move a cluster's control plane to the next Kubernetes minor by replacing its machines one at a time, with the API answering throughout.

Replace _my-cluster_ with your cluster's name or id.

**Important:**
Kubernetes cannot be downgraded. Check that your manifests use no API removed in the new minor
first.

## Prerequisites

- Permission for `eks:UpdateClusterVersion` on the cluster.
- In the console, also `eks:DescribeCluster` to open the cluster.
- The cluster is `active`, every control-plane machine is ready, no node group is more than three
  minors behind the new minor, and every add-on has a version that supports it.

## Start the upgrade

**Console**
1. Open **Kubernetes**, then open the cluster.
2. On **Overview**, under **Kubernetes _1.37_ is available**, choose **Upgrade to _1.37_**.
3. In the dialog **Upgrade _my-cluster_ to Kubernetes _1.37_?**, choose **Upgrade to _1.37_**.

**CLI**
```sh
dcloud eks clusters upgrade my-cluster --version 1.37
```

**API**
```http
PUT /eks/api/clusters/my-cluster/version
{ "version": "1.37" }
```

**Terraform**
Set `version = "1.37"` on the `dcloud_eks_cluster` and apply.

## Result

The cluster is `updating`. Deutsche Cloud first takes a `pre-upgrade` etcd snapshot and goes on once
it is verified (a control plane built before etcd backups goes on without one). Then it adds a machine at the new minor, waits until it is healthy, removes an old
machine, and repeats until no machine runs the old minor. The overview shows how many machines are
replaced; each step is in **Activity**. Node groups cannot be added while it runs, and keep their
minor until you upgrade them (see [Upgrade a node group](upgrade-a-node-group.md)).

## When the upgrade is held, or to cancel it

If the pre-upgrade snapshot fails, the upgrade holds and says why (`upgrade.held` on the cluster,
and on the overview). Deutsche Cloud tries again every 15 minutes. While it is held you can **Take the
snapshot again now** on the overview, or run
`dcloud eks clusters retry-upgrade my-cluster`: at most once per 5 minutes.

Until the first control-plane machine is replaced (`upgrade.canCancel`), held or not, you can
**Cancel the upgrade** on the overview, or run `dcloud eks clusters cancel-upgrade my-cluster`.
The cluster goes back to `active` on the minor its control plane runs. This is never possible for
Deutsche Cloud's upgrade after the end of support. Both buttons need `eks:UpdateClusterVersion`.

Refusals of these two calls (`409`): "The upgrade is not held", "A pre-upgrade snapshot is being
taken; wait for it", "One pre-upgrade snapshot per 5 minutes; the next in _n_ min", "No
control-plane upgrade is running", "The first control-plane machine was already replaced; the
upgrade can only go on", and for Deutsche Cloud's own upgrade "This is Deutsche Cloud’s upgrade after the
end of support; it cannot be cancelled (…)".

## Refusals

- `400` "Kubernetes cannot be downgraded (…)" or "Upgrade one minor at a time: …".
- `409` "An upgrade to _1.37_ is already running", "The cluster is _creating_; only an active cluster
  can be upgraded", "The cluster already runs _1.37_", "The control plane is not settled (…)",
  "Upgrade node group … first: …", or "Upgrade these add-ons first, to a version that supports
  Kubernetes _1.37_: …".

## Related

- [Version support](version-support.md)
- [Upgrade a node group](upgrade-a-node-group.md)
- `eks.clusters.upgrade` · `dcloud eks clusters upgrade` · `dcloud_eks_cluster`
