Upgrade kubernetes using kubespray


Kubespray comes very handily when you want to upgrade or downgrade your kubernetes cluster to the specific version.

But it can be troublesome if you do not know -

How to upgrade your Kubernetes cluster using Kubespray?

Click below - If you want to learn how to setup Kubernetes cluster using Kubespray

12 Steps for Installing a Production Ready Kubernetes Cluster


Table of Content

  1. How the upgrade works for Kubespray
  2. How to checkout the correct Kubespray repository
  3. Kubespray upgrade cluster to next higher version(Graceful upgrade)
  4. Kubespray upgrade Kubernetes cluster to specific version
  5. How to downgrade your Kubernetes cluster(Unsafe upgrade example)


1. How does the upgrade work for Kubespray?

Kubespray is a little special when it comes to upgrading your Kubernetes cluster.

In kubespray, you can not skip releases(versions) before jumping to the latest release.

Kubespray upgrade kubernetes cluster

Let consider the following example -

Kubespray release version
1 v2.12.0 This is the version you are using
2 v2.13.0
3 v2.14.0
4 v2.15.0 You can not directly jump to this version

Skipping of the version is not allowed - when you are using kubespray to manage your Kubernetes cluster.

You should follow this sequence -

Step 1 - First upgrade your cluster to v2.13.0 because your current kubespray version is v2.12.0

Step 2 - After your cluster is upgraded to v2.13.0, again update it to the next version which is v2.14.0

Step 3 - Now you can finally upgrade to v2.15.0

(Here is the GitHub Thread which you can refer to for more details)



2. How to checkout the correct Kubespray repository

As we have seen in the previous point that you can not skip the version when you want to upgrade your Kubernetes cluster.

How can we check out the correct immediate next version of Kubespray?

You need to follow these steps

2.1 Clone the Kuberspray repo

The first step would be to clone the Kubespray GitHub Repo.

Use the following Git Clone command -

1git clone https://github.com/kubernetes-sigs/kubespray.git

2.2 Check out the next release version of Kubespray

Now after cloning the repo, you need to know your current Kubespray version. (For example purpose I am taking my current kubespray version as v2.12.0)

After that, you need to check the next release version of the Kubespray. (Now my next release version is v2.13.0)

1git checkout tags/v2.13.0

(Note : - Check your current kubespray version and accordingly check out the next release version)



3. Kubespray upgrade cluster to next higher version (Graceful upgrade)

After going through the Step 1 and Step 2 now you need to run the upgrade cluster command so that your kubespray is being upgraded to v2.13.0

3.1 Upgrade kubespray to v2.13.0

Run the following command for the upgrade -

1ansible-playbook -i inventory/mycluster/hosts.yaml -b upgrade-cluster.yml

Once the above ansible playbook command finishes, then check your version of kubernetes

1kubectl get nodes 

Make a note of the Kubernetes version, so that we can do the Kubernetes specific version upgrade later.


3.2 Upgrade kubespray to v2.14.0

Now there is one more release v2.14.0, so first, we need to check out the version v.2.14.0

1git checkout tags/v2.14.0 

Run the following command for the upgrade -

1ansible-playbook -i inventory/mycluster/hosts.yaml -b upgrade-cluster.yml

And once the above command finishes its execution then you should be on kubespray version v2.14.0

3.3 Upgrade kubespray to v2.15.0

Now there is one more release v2.15.0, so first, we need to check out the version v.2.15.0

1git checkout tags/v2.15.0 

Run the following command for the upgrade -

1ansible-playbook -i inventory/mycluster/hosts.yaml -b upgrade-cluster.yml

And once the above command finishes its execution then you should be on kubespray version v2.15.0



4.Kubespray upgrade Kubernetes cluster to the specific version

After completing Step 1, Step 2, and Step 3 now we are having the latest version of Kubespray.

Now we need to check what version of Kubernetes cluster we are running -

1kubectl get nodes 

And here is the result of the above command

1NAME    STATUS   ROLES    AGE     VERSION
2node1   Ready    master   2m39s   v1.17.5
3node2   Ready             2m8s    v1.17.5

As you can see we are running the Kubernetes version v1.17.5.

But if you want to upgrade to a higher version(v1.20.5) of Kubernetes then you can run the following command -

1ansible-playbook cluster.yml -i inventory/sample/hosts.ini -e kube_version=v1.20.5 -e upgrade_cluster_setup=true

The above upgrade command will not fail because you are having the latest version of Kubespray on your system.



5. How to downgrade your Kubernetes cluster (Unsafe upgrade example)

Downgrading to any specific version of Kubernetes is also possible with kubespray.

Before downgrading you should know the version number onto which you want to perform the downgrade.

Let's assume we are on the latest version of Kubernetes .i.e. - v1.20.5 and now we want to downgrade to v1.18.0

Here is the command for downgrade -

1ansible-playbook cluster.yml -i inventory/mycluster/hosts.yml --become --become-user=root -e kube_version=v1.18.0 -e upgrade_cluster_setup=true

Note - There are chances where kubespray downgrade might fail because kubespray can not downgrade Kubernetes cluster further back, in such cases you might get the following error message

1fatal: [node1]: FAILED! => {
2    "assertion": "kube_version is version(kube_version_min_required, '>=')",
3    "changed": false,
4    "evaluated_to": false,
5    "msg": "The current release of Kubespray only support newer version of Kubernetes than v1.18.0 - You are trying to apply v1.16.0"
6}