If you're using Azure Kubernetes Service (AKS) you may have already seen this warning:

➜ ~ kubectl get pods
WARNING: the azure auth plugin is deprecated in v1.22+, unavailable in v1.26+; use https://github.com/Azure/kubelogin instead.
To learn more, consult https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins

Or even this one if you're running kubectl v1.26+

➜ ~ kubectl get pods
error: The azure auth plugin has been removed.
Please use the https://github.com/Azure/kubelogin kubectl/client-go credential plugin instead.
See https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins for further details

It's pretty self-explanatory, the azure auth provider was removed after being deprecated for many months, and Azure/kubelogin is the future.

But then you visit https://github.com/Azure/kubelogin expecting an easy to follow guide on how it works and how to switch to kubelogin, but all you see is a wall of text and lots, lots of commands. I don't know about you, but it took me a while to figure out how that works. So I decided to write this post to help you get started. 😊

Back to the basics: What is the Azure Auth Provider?

You can skip this if you want, but it might be good for you to understand how the authentication to AKS works, I'll keep it brief and to the point.

When connecting to AKS for the first time, you most likely executed this command:

az aks get-credentials --resource-group {your-resource-group} --name {your-aks-name}

This command generates a few sections on your ~/.kube/config file, which is used by kubectl to connect to the cluster.

The relevant section looks like this:

users:
  - name: clusterUser_{your-resource-group}_{your-aks-name}
    user:
      auth-provider:
        config:
          apiserver-id: ...
          client-id: ...
          config-mode: '1'
          environment: AzurePublicCloud
          tenant-id: ...
        name: azure

This config is using the aforementioned azure auth provider, which is now deprecated. The logic used by the auth provider is embedded in the kubectl binary, which is why you can authenticate and connect to the cluster without having to install anything else.

Starting from Kubernetes v1.26 (December/2022), this auth provider will be removed from the kubectl binary, so you'll need an alternative method to be able to authenticate to AKS.

If the deprecation wasn't enough reason to switch, can I say that the current developer experience with azure auth provider is very poor as well?

During the authentication phase, you're presented with a UR that gives you a "Device Code", which you then enter into the terminal. This is how the auth provider knows that you're the one trying to connect to the cluster. This process is slow because it's interactive, you need to switch windows, click on buttons and then copy/paste some text.

If you don't like it either, you're in luck, because kubelogin is a thousand times better 🤩.

Downloading kubelogin

The authentication plugins are being moved out of the kubectl binary into separate binaries, maintained by the Cloud providers and distributed independently.

This is why the first step is to download the kubelogin binary. Is this specific to Azure? No, the GCP Auth Provider is also being replaced by the gcloud CLI.

To install kubelogin, follow the official guide and come back here when you're done 😁.

The binary should be on your PATH. You can verify that kubelogin is installed correctly by running which kubelogin on macOS/Linux or where kubelogin on Windows.

Ready to convert?

So here's where things get a bit more complicated and they don't really explain it very well.

To connect to AKS you need a token. The token is generated by the Azure Active Directory (AAD) and is used to make API calls to the Kubernetes API Server. This is what the azure auth provider does for you, it generates the token for you transparently.

There are many (many!) ways to generate a token in Azure and it's beyond the point of this article to cover them all, but you might have heard or used some of them, like:

• Service Principal
• User Principal Principal
• Managed Service Identity
• Azure CLI
• Azure Workload Federated Identity

kubelogin convert-kubeconfig is the command we'll be using next. It'll modify our kubeconfig and replace the existing azure auth provider with a different authentication method.

Which one? It's your choice.

As a developer, if you're connecting to AKS from your machine, you're most likely to use the az Azure CLI. In fact, you probably already have it installed and configured, because that's what the first command on this article uses.

The Azure CLI can be used to generate tokens using the user's identity, which is great for development. Permissions are managed through Azure RBAC so administrators can control what developers can do on the cluster.

If you choose to use Azure CLI, stick with me. But if prefer another option, find the relevant section on official guide.

To convert your kubectl authentication method to Azure CLI, all you need to do is run:

kubelogin convert-kubeconfig -l azurecli

Shouldn't take more than a second to complete. If you inspect your ~/.kube/config again, you'll see that the azure auth provider has been replaced by kubelogin.

users:
  - name: clusterUser_{your-resource-group}_{your-aks-name}
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
          - get-token
          - --login
          - azurecli
          - --server-id
          - 6dae42f8-4368-4678-94ff-3960e28e3630
        command: kubelogin
        env: null
        provideClusterInfo: false

This is using the new client-go credential plugin feature. The kubelogin binary is now responsible for generating the token, which uses the Azure CLI behind the scenes.

You can now use kubectl as usual, it'll connect to the same clusters it has been before, but with a different authentication flow. You might need to run az login once per day, but at least you won't be prompted for a Device Code anymore! 🎉

Conclusion

It might feel a bit too magical when you're asked to simply run a CLI and things just work. But what did it actually do?

I always try to understand what's going on behind the scenes so I troubleshoot it better when something goes wrong. I hope this article helped you understand what convert-kubeconfig does. As you can see, there is no magic, it's all just text files and some code.