DigitalOcean Kubernetes (DOKS) auto-upgrade is a feature that automatically updates your cluster’s control plane to the latest stable Kubernetes version.
Let’s see it in action. Imagine you have a DOKS cluster running version 1.27.1-do.0. You want to upgrade to 1.28.2-do.0.
First, you’d navigate to your cluster in the DigitalOcean control panel. Under the "Overview" tab, you’d see a section for "Kubernetes version." If an upgrade is available, it will show a prompt like "Upgrade available: v1.28.2-do.0". You’d click the "Upgrade" button.
DigitalOcean then handles the control plane upgrade. This involves updating the Kubernetes API server, etcd, controller-manager, and scheduler. Your worker nodes are not automatically upgraded by this process; that’s a separate, manual step you’ll need to perform.
The primary benefit of auto-upgrade is maintaining security and accessing new features without manual intervention for the control plane. Kubernetes releases often include security patches, bug fixes, and performance improvements. By enabling auto-upgrade, you ensure your control plane is running a supported and secure version.
The mental model is that your DOKS cluster has two main components: the control plane and the worker nodes. Auto-upgrade only touches the control plane. The control plane is the "brain" of your cluster, managing the state of all your applications and resources. The worker nodes are where your actual application pods run.
To configure auto-upgrade, you can either do it via the DigitalOcean control panel as described above, or programmatically using the doctl command-line tool or the DigitalOcean API.
Using doctl, you would first list your clusters:
doctl kubernetes cluster list
This will output something like:
ID Name Region Slug Version Status Urgency
12345abc my-doks nyc1 abcdefg 1.27.1-do.0 running regular
Then, to enable auto-upgrade for a specific cluster (let’s say with ID 12345abc), you’d use:
doctl kubernetes cluster update 12345abc --auto-upgrade=true
To verify it’s enabled, you can check the cluster details again:
doctl kubernetes cluster get 12345abc
The output should now include "auto_upgrade": true.
The "Urgency" field in the doctl kubernetes cluster list output is important. It dictates how quickly DigitalOcean will automatically upgrade your control plane if auto-upgrade is enabled. regular means they will upgrade to the latest stable patch version within a few weeks of its release. stable means they will upgrade to the latest stable minor version, which might involve more significant changes and is typically delayed to ensure stability. none means auto-upgrade is disabled.
When DigitalOcean performs an auto-upgrade, they essentially spin up a new control plane with the target version and then migrate the cluster state to it. This is a rolling upgrade process for the control plane components, designed to minimize downtime. However, it’s crucial to remember that your worker nodes remain on their current versions. You must manually upgrade your worker nodes to match the control plane version to avoid compatibility issues. This is typically done by creating new node pools with the desired Kubernetes version and then draining/deleting the old node pools.
Most people understand that auto-upgrade updates the control plane. What they often miss is that the worker nodes are not included in this automatic process. If your control plane is on 1.28.2-do.0 and your worker nodes are still on 1.27.1-do.0, you’ll start experiencing API compatibility errors, where the kubelets on your worker nodes can’t communicate effectively with the newer control plane. This is because the API server’s version is newer than the kubelet’s version, and the kubelet might not understand newer API fields or features.
The next concept you’ll need to grapple with is managing worker node upgrades after the control plane has been auto-upgraded.