Tool Version Manager

Asdf is a tool version manager where all the tools and the versions are defined in a single file (.tool-versions). This single file can be shared across multiple teams to ensure everyone uses same versions of the same tool(s).

Source: asdf introduction page

Reader’s Guide

This technical documentation focus on Software Developers, DevOps, Cloud, SRE, System Engineers and Native Engineers that uses many tools.

• Before Tool Version Manager
• Cons of Legacy Tools-Configurations
• How Asdf works
• Asdf Setups

Before Tool Version Manager

The traditional method for multiple versions for a tool require various configurations which are also specific to tool and dependent on libraries. For an example, Let’s look at python on Mac.

install python with Homebrew

brew install python

python --version

This command will display the active python version

ls -l /usr/local/bin/python*

This command will display all the installed python versions

ln -s -f /usr/local/bin/python3.8.1 /usr/local/bin/python

This symlink command will change the active python version to python3.8.1

This setup is a global wide configuration-That is-this configuration is not project specific. To be project specific will require performing the last two steps again and again as this case may require. And, indeed, this is a punishment 😢

I’m a DevOps Engineer and I constantly work with many tools. From my experience over the years working for different companies and Crypto Fintech, I can tell you how painful this can be.

Imagine multiple clusters of different versions in different environments(Dev, Stage, Prod, QA…). Accessing these clusters where the client tool kubectl requires different version. Another tool to consider is that of terraform version constraints.

Cons of Legacy Tools Configuration

• The burden of constantly switching between one version and another
• It’s time-consuming just to access a tool
• Risk of breaking the system and re-installing from scratch
• Different virtual environments for each tool, such as Pyenv, nvm, rbenv
• Exports of multiple Paths as environmental variables

How Asdf works

Asdf operates similar to nvm and other tool version managers but is not limited to a specific tool. Asdf uses plugins and this approach removes the constraints that a tool manager manages per tool with its own version file and commands. Thus, asdf is a single command for accessing all tools through plugins and manages the versions through .tool-verions file

Once asdf core is set up with your Shell configuration, plugins are installed to manage particular tools. When a tool is installed by a plugin, the executables that are installed have shimsopen in new window created for each of them. When you try and run one of these executables, the shim is run instead, allowing asdf to identify which version of the tool is set in .tool-versions and execute that version.

asdf page

Here is how asdf manages multiple tools I work with asdf list

Asdf Setup

Two method for installing asdf

• Git
• Package manager

Git

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.10.2

Export the path

. $HOME/.asdf/asdf.sh

Check the asdf page for specific installation according to your setup

USAGE

Install the dependencies first before you proceeds. brew install gpg gawk

Let’s install istio

• First, find the plugin

# find the plugin
asdf plugin list all | grep -i istio

• Add the plugin

# add the plugin
asdf plugin add istioctl

• List available versions

# list available versions
asdf list all istioctl

• Install the version

# install version 1.14.3
asdf install istioctl 1.14.3

• List installed istio versions

# list the installed versions
asdf list istioctl

Version File

Asdf uses .tool-versions file to track which version to use when the command is invoked. Let’s see what happens when istio cli tool istioctl is invoked.

istioctl

If the version is not set, asdf complains with this error ☝️

Let set the version 1.15.0

1. Open the .tool-versions file
2. Add the version as the 👇

istioctl 1.15.0

1. Save the file

Try it again, istioctl will display the usage just like this 👇

istioctl

How To Set Version

There are two types of versions and this sublimes the problems of tools versioning.

1. Global Versioning

2. Local Versioning

There are two approaches to set versioning for asdf. The declarative and the imperative approach. If you are DevOps Engineer or Software Developer you probably prefer the declarative approach. Though the imperative way is faster.

Quick check

which version is the current global

asdf current istioclt

istio current version

Global Versioning

Recall the configuration of .tool-versions file as in this block. That was global versioning. It turns out that by default asdf is a global version.

• Declarative Approach is the first approach by creating a .tool-versions file and adding the tool-name, then space, the version-number.

istioctl 1.15.0

• Imperative Approach is the use of cli with the asdf command and the flag global. Here is an example on how to do that 👇.

asdf global istioctl 1.15.0

Let's promote the second version of istio 1.14.3 to global using the imperative approach 👇

asdf global istioctl 1.14.3

The asdf global command updated the tool from 1.15.0 to 1.14.3 in .tool-versions file. You see the imperative approach is faster but the declarative approach is safer.

Local Versioning

Local versioning allows you to set the tool version at project level.

What does that even mean?

You are allowed to set a version according to your working directory. Let’s try the two approaches.

• Declarative Approach for local versioning is similar to the global versioning as previously discussed. The difference is the directory. The Global version uses the .tool-versions file in the $HOME directory while the Local version uses the .tool-versions in the working $PWD directory.

Create a .tool-versions file in your project directory and add the tool, then space, the version number istioctl 1.15.0. See the illustration using the imperative approach.

• Imperative Approach

The istio_confidential is my project directory where I want to use istio 1.15.0

cd istio_confidential

asdf local istioctl 1.15.0

# view the .tool-versions file
cat .tool-versions

A .tool-versions file is created and version 1.15.0 is set for this project.

Next, check the current istioctl version in the project directory (local) and outside the directory (global) 👇

asdf current istioctl

💪 Congratulations !!!

You have installed asdf, added plugins and configure the versions, globally and locally. You have also successfully set two different istio versions on your machine, one for your project and the other globally accessible.

You can install many versions and set different versions for different projects.