kubelogin is not installed which is required to connect to aad enabled cluster

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

➜ ~ kubectl get pods
error: exec: executable kubelogin not found It looks like you are trying to use a client-go credential plugin that is not installed.
To learn more about this feature, consult the documentation available at: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins
kubelogin is not installed which is required to connect to AAD enabled cluster.

The error is pretty self-explanatory, you must use Azure/kubelogin to connect to AAD-enabled AKS clusters.

The official docs doesn't really explain how it all works. So I decided to write this post to help you understand how Azure/kubelogin works behind the scenes. Let's get started!

In the past, the kubectl binary had built-in support for authenticating with Azure Active Directory (AAD) using the azure auth provider. This was deprecated in Kubernetes 1.22, and removed in Kubernetes 1.26.

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.

To install kubelogin, use one of the commands from the official guide and come back here when you're done 😁. It works with all platforms, including Windows, macOS (brew!) and Linux.

IMPORTANT: The binary MUST be on your PATH. You can verify that kubelogin is installed correctly by running which kubelogin on macOS/Linux, or where kubelogin on Windows. If they are not, you'll get an error like this:

executable kubelogin not found

So here's where things get a bit more complicated and the official guide doesn't really explain it very well.

To connect to AKS you need a token. If the AKS cluster is AAD enabled, the token must be generated by the Azure Active Directory (AAD) before it can be used to authenticate with the Kubernetes API.

There are 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 configure your kubeconfig to use Azure kubelogin as the token provider using one of the methods above.

Which one? It's your choice.

If you're connecting to AKS from your machine, you're most likely to use the Azure CLI (known as az). In fact, you probably already have it installed and configured as it's the most common way to authenticate with Azure.

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.

To convert your kubectl authentication method to use 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 file, you'll see that it was changed to use 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

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

From now one, you can use kubectl as usual and it'll seamlessly use kubelogin and the Azure CLI to get new tokens. You might need to run az login at least once per day.

It might feel a bit too magical when you're asked to simply run a CLI and things just work. I always try to understand what's going on behind the scenes so that I can 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.

By the way, Aptakube works with AKS and kubelogin too! You should give it a try. 😊