Working with Istio control plane revisions

How can you manage multiple versions of Istio on your workstation and on your cluster and smoothly handle Istio control plane revisions?

As a developer, it is always pain to have multiple versions of a tool and keep playing with your path to use the needed version, so you need a strategy for Istio control plane revisions. When developing service mesh applications with Istio, you may start with one version of Istio and then slowly as your application grows you might want to move to another newer version. In these scenarios the problem goes beyond just the right version of the Istio management tool istioctl on the OS system path.

Getting started on Istio control plane revisions

Let’s tackle the problem part by part. To start, let us see how to prepare your developer workstation to have multiple Istio distributions and then seamlessly shift between them.

As with any other tool, to use the right version of istioctl against the Kubernetes cluster, requires you to alter the OS system path to point to right distribution. Is there an easier way to do that than manually altering the path manually every time?

There are may ways to tweak the system OS path, but today let’s explore a tool called asdf-vm. It is a great tool for the following simple reasons:

  • You can use your $HOME to install all the libraries/tools
  • You can manage lots of tools such as node.js, Java, and Python
  • It is super easy to install
  • It works across platforms like macOS or Linux

Follow the asdf-vm official docs instructions to have it installed. Once you have it installed successfully then it’s simple to have multiple versions of Istio.

To manage and use multiple versions Istio with asdf-vm we need to first add the Istio plugin to asdf-vm:

asdf plugin-add istio

Then install the version(s) as required:

# to install latest version, this should download and install Istio 1.10.2, latest at the time of writing this 
asdf install istio latest
# say I want to install 1.8.6 
asdf install istio 1.8.6

How to automate Istio control plane revisions

We now have the needed version(s) installed, now how do you make your shell or project automatically pick the right version?

The tools version can be added globally, which is the default when no specific version is available. We can also add a tool version at use the project level which takes precedence over the global one.

asdf-vm uses a file called .tool-versions to manage the tools and its version. The global one is at $HOME/.tool-versions and the project specific one is stored at $PROJECT_HOME/.tools-versions. We will see how to get the .tool-versions added to your project later.

Now we know where asdf-vm stores version info, let us now get to crux of the story on how to add and use multiple versions of Istio.

To add a global Istio version, you can run:

# say we want to use the latest version
asdf global istio latest
# now do istioctl to verify, should return 1.10.2 or later 
istioctl version --short --remote=false

To add a project specific version, navigate to the project which you will use with Istio, then run:

# let us pin the project to Istio 1.8.6 
asdf local istio 1.8.6
# now do istioctl to verify, should return 1.8.6 or later 
istioctl version --short --remote=false

As you observed earlier, though we have global Istio set to 1.10.2 when we use .tool-versions at a project level, your system automatically picks the version from $PROJECT_HOME/.tool-versions. If you don’t have any versions of Istio locally, then from the $PROJECT_HOME you can run asdf install to have the Istio from $PROJECT_HOME/.tool-versions installed.

Tip: To get the install directory ISTIO_HOME, just run:

export ISTIO_HOME=$(asdf where Istio)

A practical example

OK! We had enough theory, let get into a practical example though its simple hello world and see how to to leverage our setup.

Voilà! Now you can seamlessly manage and use multiple versions of Isito either globally or at project level. By checking in the $PROJECT_HOME/.tool-versions to your source code repository, you can make sure that your application users have the right version of Istio while installing and testing their applications.

If you find any issues with the asdf-istio plugin please feel free to open an issue at:

If you want to use glooctl, the add and use the asdf-glooctl plugin at

Let us know if this was a helpful guide to managing Istio control plane revisions, or ask us any questions on Slack. Or read more about Gloo Mesh.