How to Upgrade Your VKE Cluster
This article explains how to upgrade your Vultr Kubernetes Engine (VKE) cluster to the latest version. VKE follows the upstream Kubernetes project, which typically releases a new minor version every three months. VKE supports the latest three releases, which means around nine months of support for each version. You should perform regular updates to receive the latest security updates and features as part of a healthy, planned lifecycle.
Before You Begin
First, please read the VKE changelog and upstream Kubernetes release notes carefully. Then, after familiarizing yourself with the new changes, back up your essential components, especially any app-level state stored in a database. We only update the internal components of Kubernetes and do not touch your workloads, but, as a best practice, you should always make backups.
If your workloads follow cloud-native best practices, you can expect your cluster upgrade to be complete in a few minutes, without downtime. When upgrading your cluster, you should consider these points to ensure your services remain available during the upgrade.
Use a PodDisruptionBudget
You should configure a
PodDisruptionBudget (PDB), which determines how many instances can be down at the same time for a short period due to a voluntary disruption. Please refer to Specifying a Disruption Budget for your Application in the Kubernetes documentation for more specifics.
Implement Graceful Shutdowns
Your workloads should implement graceful shutdowns. This means that your workloads should be able to shut down and recover from a failure gracefully. This is particularly important for long-running workloads, such as web servers. Please refer to Termination of Pods in the Kubernetes Pod Lifecycle documentation for more specifics, and consider implementing a
PreStop hook for your workloads.
During a VKE upgrade, Nodes are replaced following the standard Kubernetes termination lifecycle:
- Pods are set to the
- If a
preStophook exists, it is executed.
- A SIGTERM signal is sent to the Pod, warning the containers that they will be shut down.
- Kubernetes waits for the default grace period, 30 seconds.
- Any containers that haven't shut down are sent a SIGKILL signal.
- The Pod is removed.
Use Readiness and Liveness Probes
Readiness and liveness probes can be used in parallel to ensure a container will not receive traffic until it is ready. You should consider implementing these probes in your application. See the Kubernetes documentation for more details.
The Upgrade Process
If your application follows best practices, we can upgrade your cluster without downtime or loss of capacity.
First, we replace the control plane with a new control plane running the new version of Kubernetes. During this process,
kubectl commands and other access to the cluster is unavailable, but the workloads are not impacted. We then perform a rolling upgrade of each nodepool. For stability and to ensure no loss of capacity, we create new replacement nodes before draining and removing the old nodes. This process is sometimes called a surge upgrade.
The control plane reschedules the workload for each node, then replaces it with a new node running the new version and reattaches any block storage volumes. New worker nodes will have new IP addresses.
NOTE: You should use Block Storage volumes for persistent data. The local disk storage on worker nodes is transient, and will be lost during the upgrade process.
To begin the upgrade process, log in to the Vultr customer portal with a web browser.
- Navigate to the Kubernetes tab.
- Select the cluster that you want to upgrade from the list. You'll see an alert banner and an Upgrade Available alert next to your current version number if an upgrade is available.
- Select the Manage Upgrades tab.
- Choose an upgrade option and click the Start Upgrade button.
- The cluster status will change to Upgrading.
You can monitor the upgrade progress for individual nodes on the Nodes tab. After the upgrade completes, the cluster status changes to Running.
About VKE Version Numbers
We follow the same Semantic Versioning terminology as Kubernetes, with an added build number suffix. VKE versions are formatted as:
wis the major version
xis the minor version
yis the patch version
+zis the build number
Frequently Asked Questions
Can I upgrade to the latest version in one step, or do I need to upgrade one version at a time?
It depends on which semantic version is being discussed.
- You can upgrade from one minor version to the next minor version but cannot skip a minor version.
- You can upgrade to any available patch version or build number within a minor version.
For example, if you are performing upgrades on a fictional major version 99:
- You can upgrade from 99.20.1+1 to 99.20.8+2, skipping patch versions 2 through 7, because minor version 20 is the same. The build number in this case does not matter.
- You can upgrade from 99.20.3+5 to 99.21.1+2, regardless of patch version and build number, because minor version 21 is only one version newer than version 20.
- However, you cannot upgrade from 99.20.1+1 to 99.23.1+1 because minor version 23 is more than one version newer than version 20. In this case, you must upgrade from minor version 20 to 21, then 22, then 23.
How can I find the VKE version for my cluster?
You can find this information in the Customer Portal on the Overview tab of your cluster's information page.
Vultr also adds a version label to every node in the
vke.vultr.com namespace. You can view the version label by running the following command:
$ kubectl get nodes -L vke.vultr.com/node-pool,vke.vultr.com/version
NAME STATUS ROLES AGE VERSION NODE-POOL VERSION
cluster-one-0197188b1f84 Ready <none> 99m v1.22.8 cluster-one v1.22.8-2
cluster-one-16ca2242c777 Ready <none> 99m v1.22.8 cluster-one v1.22.8-2
cluster-one-930fb1751cdf Ready <none> 99m v1.22.8 cluster-one v1.22.8-2
cluster-one-96c8b07f8a5a Ready <none> 99m v1.22.8 cluster-one v1.22.8-2
cluster-one-c99d50f8ae68 Ready <none> 99m v1.22.8 cluster-one v1.22.8-2
The VKE version shown in this example is
There are two version columns: The first is the Kubernetes version, and the second is the version label set by Vultr, which shows the VKE build number. The normal
+ sign is substituted by a
- sign due to label character limitations.
Where can I find information about Vultr's VKE versions?
You'll find information about each VKE version in our changelog.
Where can I find information about Kubernetes versions?
Kubernetes release history is available on their website.
Should I upgrade my VKE cluster to a newer version?
Yes, you should stay current because upstream Kubernetes only supports the latest three minor versions. Typically, upstream Kubernetes has a new minor version release every three months, which means the latest version has around nine months of support.
Can I monitor the progress?
Yes. You can monitor the progress of your cluster upgrade by visiting the Vultr customer portal or by periodically running the
$ kubectl get nodes -o wide
If you have
watch installed, you may find that a convenient way to monitor the progress of your cluster upgrade. Running
watch continuously monitors the command by running it every few seconds.
$ watch kubectl get nodes -o wide
VKE is a managed product that handles the upgrade tasks for you. However, if you'd like to know more about Kubernetes upgrades and administration in general, see the upstream documentation at kubernetes.io. To learn about Kubernetes at Vultr and VKE, see our documentation library.