kubelogin is the exec plugin that lets kubectl borrow Azure's login instead of holding a long lived token

A credential plugin, not a client

kubelogin is a client-go credential exec plugin implementing Azure authentication. That sentence is dense, so it is worth taking apart.

Kubernetes needs a credential to talk to an API server. There are several ways to supply one: a static token pasted into a kubeconfig, a client certificate, or an exec plugin, which is a command that the client runs and which prints a credential on standard output. client-go supports the exec mechanism, and kubelogin is one such command, purpose built for Azure.

The value of the exec approach is that the credential is obtained at the moment kubectl runs rather than being stored in the kubeconfig. Azure issues short lived tokens, and a plugin that fetches a fresh one each time removes the entire category of problem where a long lived credential in a shared kubeconfig outlives the thing it was issued for. It also means the authentication flow can be the interactive one a developer expects, browser sign-in included, without every developer having to learn where to paste a token.

The other half of the positioning is stated in the README: the plugin provides features that are not available in kubectl. The repository is therefore about closing the gap between what Azure authentication actually requires and what the stock kubectl experience offers.

The audience is narrow and clear: operators and developers working with Azure Kubernetes Service clusters from a workstation or a CI runner. The project is hosted in the Azure GitHub organisation, the licence is MIT, and the language is Go. It is supported on kubectl v1.11 and newer, which is a long way back and tells you the exec plugin protocol itself is stable.

The documentation site owns the commands, deliberately

The README is very short, and the reason is visible in its structure: the installation, quick start and detailed behaviour all live on a separate documentation site, and the README links out to them rather than repeating them.

There is a note that explains why. The official sources for the project are the documentation site at azure.github.io/kubelogin and the GitHub repository, and the Azure Kubernetes Service team does not maintain or endorse any other websites presenting themselves as the official site. That is a short, practical anti-phishing statement, and it is the kind of thing a project that hands out credentials should have.

For a reader, the consequence is that the repository is an index rather than a manual. The install page and the quick start page are where the actual commands live, and the developer's memo equivalent for this project is the developer guide on that same site.

What the repository does contain is enough to understand the shape of the thing. The source is in pkg/ with main.go and version.go at the root, the docs/ directory holds the site sources, hack/ holds build and release helper scripts, and there is a Dockerfile, a Makefile, a CHANGELOG.md, a SECURITY.md, a CODE_OF_CONDUCT.md and a .tool-versions file.

The dependency list is where the behaviour is described, since this is a command that talks to identity providers. There is the current Azure SDK for Go with azcore, azidentity and its cache package, the older autorest and ADAL libraries, the Microsoft Authentication Library for Go and the Microsoft authentication extensions for Go, a JWT library, and cobra and pflag for the command line itself. Alongside them sit the Kubernetes libraries, apimachinery, cli-runtime and client-go, plus klog for logging.

One entry is worth calling out because it is unusual: gopkg.in/dnaeon/go-vcr.v4 is a library for recording and replaying HTTP interactions, which is how the test suite runs against recorded responses instead of live Azure endpoints. For a credential plugin, that is a sensible choice and it also means the tests do not need real Azure credentials to run.

The container image is a scratch image with one binary in it

The Dockerfile is short enough to read in full, and it makes a deliberate choice.

The image is FROM scratch, which means there is no operating system underneath, no shell and no package manager. The only thing in it is a statically built binary copied in from the local build directory, with the architecture selected at build time:

FROM scratch

# Build arguments for multi-architecture support
ARG TARGETARCH=amd64
ARG VERSION=""

# OpenContainers Image Spec labels
LABEL org.opencontainers.image.source="https://github.com/Azure/kubelogin"
LABEL org.opencontainers.image.description="Kubernetes credential plugin for Azure authentication"
LABEL org.opencontainers.image.licenses="MIT"
LABEL org.opencontainers.image.version="${VERSION}"

# Copy the pre-built binary from local build to /usr/local/bin
COPY bin/linux_${TARGETARCH}/kubelogin /usr/local/bin/kubelogin

The comment at the top of the file makes the workflow explicit. This Dockerfile copies a pre-built binary into a minimal scratch image, and the binary should be built before running docker build using make kubelogin.

So the image is not a self contained build, it is a packaging step for a binary your Makefile has already produced, and the path it copies from, bin/linux_amd64/kubelogin, is exactly the layout the Makefile's own path scheme produces. The image is therefore usable as a kubectl exec plugin in an environment where the plugin command has to be a container, and it carries the OpenContainers labels including the MIT licence and the version.

The entrypoint is /usr/local/bin/kubelogin, which is what the exec plugin protocol expects: the client runs the command and reads the credential from its output.

The Makefile is the build contract, and it prints its own options

For a project whose README defers to a website, the Makefile help target does the documenting, and it is unusually complete.

help:
	@echo "Available targets:"
	@echo "  all          - Build the kubelogin binary (default)"
	@echo "  $(TARGET)    - Build the kubelogin binary"
	@echo "  lint         - Run linting checks"
	@echo "  test         - Run tests (includes linting)"
	@echo "  clean        - Remove built binaries"
	@echo "  build-image  - Build Docker image with kubelogin binary"
	@echo "  changelog    - Generate a CHANGELOG.md entry for a new release"

The interesting target is changelog, and the options it documents reveal how releases are produced. VERSION sets the new version number, and SINCE_TAG sets the previous tag to compare from, with the help text noting that without it the previous tag is auto-detected. The token is read from the GITHUB_TOKEN environment variable or from gh auth token automatically.

So the release process generates the changelog entry programmatically by diffing between two tags, and the release notes in CHANGELOG.md are not hand written. That is a small but meaningful piece of release hygiene for a project that ships binary artefacts to clusters, because the notes describe exactly the range of commits that went into a given binary.

The rest of the file handles cross compilation. OS, ARCH and GOARM are read from the environment if set and otherwise from go env, the binary is placed under bin/$(OS)_$(ARCH) with a .exe suffix on Windows, and the version string is injected at link time with LDFLAGS := -X main.gitTag=$(GIT_TAG). The include of .bingo/Variables.mk at the top is how tool versions are pinned, which is the bingo tool's job.

The environment variables the help prints are GOOS, GOARCH, GIT_TAG, VERSION and SINCE_TAG, and the default goal is all, which builds the kubelogin binary.

Exec plugin against the alternatives: tokens, certificates and node plugins

There are other ways to authenticate kubectl to a cluster, and the difference matters more here than in most credential discussions.

A static token in the kubeconfig is the simplest and the worst. It does not expire, it does not rotate, and it ends up in files that get copied around, committed by accident, or pasted into a chat. The exec plugin exists precisely to avoid that shape.

A client certificate sits in between. It is a proper credential with an expiry and it can be short lived, but it is still a file you have to distribute and refresh, and the tooling to obtain one on demand is often the painful part.

The exec plugin is the version where the credential is produced by a program at the moment it is needed. That shifts the burden from distribution to execution: instead of handing people a secret, you give them a command and a login.

The trade-off of the exec approach is that the plugin becomes part of the critical path for every kubectl invocation. If it needs an interactive browser login and the developer is on a remote shell, the command blocks. If the identity provider is unreachable, kubectl does not work at all, where a cached token might have carried you through an outage. That is a real operational cost, and it is why the plugin ecosystem grew the token caching options that the azidentity/cache dependency in go.mod belongs to.

The other axis is which identity you authenticate as. kubelogin is Azure specific, and the dependency list shows the weight of that: two Microsoft identity stacks, the current one and the older one, because a credential tool has to interoperate with whatever the tenant and the token endpoint happen to speak. The alternative of a generic plugin is to write the Azure specifics yourself, which is the work this repository already does.

Version 0.2.x, a recent push, and a note about Go support policy

The release history shows an active project on a steady patch cadence. The tags are v0.2.21 from 2026-10-09, v0.2.20 from 2026-09-23 and v0.2.19 from 2026-06-23. The repository is not archived and the last push was on 2026-10-22.

The version number is worth reading carefully. It is 0.2.x, which in semver terms means the public interface is still expected to move, and for a command line tool that is a reasonable place to be. It also means that if you script around kubelogin's flags, you should not assume they are frozen.

The go.mod file carries a policy note in a comment: kubelogin follows the same support policy as Go, which supports the last two major versions. The module declares go 1.26.6 as its Go directive. That is an unusual thing to find in a go.mod comment, and it tells you the project intends to track the Go release cycle rather than to accumulate compatibility shims for old toolchains.

Practically, that means the toolchain you build or run it with matters, and it means the project will move. For a credential plugin that ships as a binary into a fleet, the sensible habit is to pin a released version rather than to build from main.

The repository also carries the pieces a security focused project should have: SECURITY.md for reporting a vulnerability, a CODE_OF_CONDUCT.md, the Microsoft Open Source Code of Conduct, a golangci-lint workflow badge, a build on push workflow, a coverage badge, and a pre-commit configuration. The presence of a pre-commit hook and a bingo managed tool set is the shape of a project that expects contributions from outside Microsoft.

Contributions go through a CLA, and that is a real gate

The contributing section of the README describes a process that is worth understanding before you open a pull request.

The project welcomes contributions and suggestions, and it says that most contributions require you to agree to a Contributor License Agreement, a CLA declaring that you have the right to, and actually do, grant the rights to use your contribution. The details are at the Microsoft CLA site, and when you submit a pull request a CLA bot automatically determines whether you need to provide one and decorates the pull request accordingly, with a status check and a comment. The instruction is to follow the bot's instructions, and the documentation notes you only need to do this once across all repositories using that CLA.

That is the single most important operational fact for an outside contributor. The CLA is not a formality in the usual sense, it is a legal instrument that Microsoft uses to be able to relicense contributions if it needs to, and agreeing to it is a decision rather than a click. A company that has a policy about granting broad relicensing rights needs to check with whoever handles that before an engineer signs.

The rest of the contributing surface is conventional. The code of conduct is the Microsoft Open Source Code of Conduct, with a FAQ and a contact address for questions. The development details, including how to build, run the tests and join the project, are on the documentation site rather than in the repository.

Combined with the note about official sources, the overall posture of the project is worth registering: this is a Microsoft owned tool for authenticating to Microsoft owned infrastructure, published under a permissive licence, with a contribution agreement that gives the vendor latitude, and documentation hosted on a site the project explicitly asks you to trust.

Editorial conclusion

Use kubelogin if you run kubectl against Azure Kubernetes clusters and want the credential to be obtained at the moment kubectl runs, so that short lived tokens rotate on their own and your kubeconfig holds no long lived secret. Do not adopt it as a generic Kubernetes credential, because it is specific to Azure, and expect a binary distribution rather than a library, since the repository is a command, not a package. Before deploying it, read the install and quick start pages on the documentation site, and confirm the version you ship matches the kubectl version in your fleet, since the plugin protocol has changed shape over the life of client-go.

Frequently asked questions

Official sources

1. Azure/kubelogin on GitHub
2. License: MIT
3. Project website
4. README
5. Releases