vault-k8s: the Agent Injector sidecar webhook, versioned apart from Vault

One binary, one feature, and a separate version line

The project documentation is unusually blunt about scope. The vault-k8s binary includes first-class integrations between Vault and Kubernetes, and currently the only integration in this repository is the Vault Agent Sidecar Injector, called agent-inject. More integrations will be found here in the future, which is a statement of intent rather than a description of what exists. That single-feature scope shapes every evaluation question, because you are not buying a Kubernetes platform for Vault, you are buying the admission webhook that does one job. The versioning decision is the other thing to understand early. This project is versioned separately from Vault, and the README gives the reason: by versioning separately, the team can iterate on Kubernetes integrations more quickly and release new versions without forcing Vault users to do a full Vault upgrade. For an operator that is a meaningful operational property, since a Vault core upgrade and a webhook change carry very different risk.

Agent Inject works by rewriting annotated pods

The mechanism is a mutation webhook controller. When a pod is created that matches specific annotation criteria, the injector adds Vault Agent containers to it. The Kubernetes API server calls the webhook on admission, the webhook decides whether the pod qualifies, and if it does, it patches the pod spec so the Agent container is present at scheduling time rather than something a sidecar manager has to inject afterwards. The source layout confirms the shape of the implementation, with an agent-inject directory holding the controller, a subcommand directory for the CLI surface, a leader directory for leader election, helper and test directories, and a deploy directory with a kustomization.yaml at the root for Kubernetes-side deployment manifests. The agent-inject feature requires Vault 1.3.1 or later. The dependency list in go.mod is the fingerprint of the implementation: controller-runtime and client-go for talking to the API server, evanphx/json-patch for producing the patch that mutates the pod, the operator-framework operator-lib for controller plumbing, and the Vault SDK at v0.26.0 for the client side.

Three distribution forms, and the Helm chart is the recommendation

The installation section lists three ways to get the binary, and the first is the one HashiCorp wants you to use. The recommended installation method is the official Vault Helm chart, and the documentation says it will automatically configure the Vault and Kubernetes integration to run within an existing Kubernetes cluster. That matters because the injector is a webhook with a TLS certificate, a service, and a mutating webhook configuration registered against the API server, and none of that is something you want to assemble by hand. The second form is a Docker image, hashicorp/vault-k8s on Docker Hub, which the documentation says can be used to manually run vault-k8s within a scheduled environment. The third is raw binaries from the HashiCorp releases directory, which can be used to run vault-k8s directly or to build custom packages. If you are not using the Helm chart, the third form is where you own the wiring, and the README does not document what that wiring consists of, so the injector documentation on the Vault site is the reference you need.

The Makefile shows how the pieces are tested and pinned

The build file gives a clearer picture of the release process than the README does. The image is assembled as docker.io/hashicorp/vault-k8s with a version defaulting to 0.0.0-dev, and the Go binary is stamped with the version through ldflags pointing at the version package. Two variables matter for anyone reproducing a build. VAULT_VERSION defaults to 2.0.4 and is the Vault version the integration is tested against, and VAULT_HELM_CHART_VERSION defaults to 0.32.0, which is the chart the test suite installs. There is also a conditional: when the Vault major version is 1 and the minor version is below 15, the test run switches to a values file without TLS, named test/vault/dev-no-tls.values.yaml, instead of the default test/vault/dev.values.yaml. Enterprise test runs are gated behind ENT_TESTS, and when enabled they point both the server image and the injector agent image at the enterprise registry with an enterprise licence secret. The Helm invocation itself sets the injector image tag from the built VERSION, which is how the chart ends up running the binary you just compiled rather than a published one. The default arguments are:

VAULT_HELM_DEFAULT_ARGS ?= --repo https://helm.releases.hashicorp.com --version=$(VAULT_HELM_CHART_VERSION) \
	--wait --timeout=5m \
	--values=$(HELM_VALUES_FILE) \
	--set 'injector.image.tag=$(VERSION)'

The --wait and --timeout=5m flags mean the install blocks until the Vault and injector resources are ready, which is worth knowing before you run it in a pipeline.

A multi-target Dockerfile where the default image cannot be built locally

The Dockerfile has a comment at the top that most projects do not write. It says the file contains multiple targets and that you build one with docker build --target=<name> ., giving dev as the example. It then states that all non-dev targets have a VERSION argument that must be provided via --build-arg=VERSION=<version>, and that the default target is the production Docker image which cannot be built locally, so for local development and testing you build and use the dev image. That is an unusual and useful thing to document. The dev target is based on alpine 3.24.2, creates a vault group and a vault user, adds the dist/vault-k8s binary as /vault-k8s, and sets USER vault with the entrypoint at /vault-k8s, so the dev image runs as a non-root user. The default target carries the release metadata: PRODUCT_VERSION and PRODUCT_REVISION as build arguments, a name label of Vault K8s, a maintainer label pointing at the Vault team, and an org.opencontainers.image.licenses label of MPL-2.0. It also copies the LICENSE file to /licenses/mozilla.txt and to a path under /usr/share/doc, with a comment noting that the copy conforms to HC IPS-002.

What this repository does not contain

Several things a reader might expect are deliberately absent, and the documentation points elsewhere for each of them. The Kubernetes integrations with Vault are documented directly on the Vault website, and the README says it presents a basic overview of each use case while full documentation lives on that site. The controller source, the annotation schema, the agent configuration format, the TLS requirements and the failure behaviour all sit outside this repository. There is also no documentation of configuration keys, no description of the command line subcommands beyond what the directory names imply, and no statement about how the leader election behaves when the webhook has multiple replicas. The supported Vault version is not tracked centrally either. The documentation only notes it per feature, and Agent Inject is marked as requiring Vault 1.3.1 or later, which leaves the question of what a current Vault release does with this binary open. The practical reading is that this is infrastructure code, and infrastructure code is usually paired with a runbook that lives somewhere else.

MPL-2.0, frequent releases, and a security disclosure process

The licence is MPL-2.0, confirmed by the LICENSE file at the root and by the copywrite headers in the source, and the Docker image metadata repeats it as the org.opencontainers.image.licenses label. MPL-2.0 is a file-level copyleft licence, so if you modify the source of the component and distribute it, those modified files stay under the licence, and the Dockerfile comment about copying the LICENSE into the image shows the project treats that obligation seriously. The release cadence is steady: v1.7.4 on 2026-04-30, v1.7.5 on 2026-06-29 and v1.7.6 on 2026-08-07, with the last push on 2026-10-21 and a CHANGELOG.md in the root. The project documentation opens with a security notice that takes a security issue in Vault K8s seriously and asks that it be responsibly disclosed by contacting [email protected]. For a component that sits in the pod creation path of a cluster, having a named disclosure route is a reasonable signal that the maintainers consider it security-relevant code.

Editorial conclusion

Adopt vault-k8s if you run Vault on Kubernetes and want the Agent Injector to place sidecar containers for you, and you want that component to move on its own release cadence instead of being coupled to Vault core. Do not adopt it expecting a broader platform: the README states the only integration in the repository is the Agent Injector, and the Kubernetes integrations are documented on the Vault website rather than here. Before you commit, confirm your Vault version is 1.3.1 or later, since that is the stated requirement for Agent Inject, read the injector documentation on the Vault site, and check the Helm chart version your cluster pins against the vault-k8s release you plan to install.

Frequently asked questions

Official sources

1. hashicorp/vault-k8s on GitHub
2. Issues
3. License: MPL-2.0
4. README
5. Releases