vault-helm: the official Helm chart for running Vault on Kubernetes

The chart is a packaging of the product, not a reimplementation of it

The vault-helm repository contains the official HashiCorp Helm chart for installing and configuring Vault on Kubernetes, and the chart supports multiple use cases of Vault on Kubernetes depending on the values provided.

That framing matters. What the chart does is translate a Vault deployment into Kubernetes objects, and the translation is one to one with Vault's own configuration model. There is no separate abstraction layer, so the surface you configure in `values.yaml` is the surface Vault itself has, and a value you set here is a Vault setting rather than a chart-specific invention.

The repository layout is what you would expect for a chart with serious testing behind it. There is a `templates/` directory for the rendered manifests, a `values.yaml` and a `values.openshift.yaml` for a platform-specific override, a `values.schema.json`, a `Chart.yaml`, a `test/` directory, a `Makefile`, a `CHANGELOG.md` and a `CODEOWNERS` file. The `values.schema.json` is a JSON schema for the values file, which means a mistyped key can be rejected at install time rather than silently ignored, and the Makefile shows how it is produced.

The security note at the top of the README is worth repeating as a habit rather than a formality. The project states that it takes Vault's security and its users' trust very seriously, and asks that security issues in Vault Helm be responsibly disclosed to [email protected] rather than filed as a public issue. For a chart that installs a secrets manager, a reported vulnerability in the chart is a vulnerability in a large number of deployments at once.

The chart is MPL-2.0 licensed, the default branch is `main`, and the last push was on 2026-09-29.

Installing it is a repo add and a helm install

The usage section is two commands, and the prerequisites are stated before them.

The requirements are Helm 3.6 or newer and Kubernetes 1.29 or newer, with 1.29 described as the earliest version tested and a note that the chart may work with earlier versions but that this is untested. Helm has to be configured for your cluster already; setting up Kubernetes and Helm is out of scope for the README.

The installation then adds the HashiCorp repository and installs the chart:

$ helm repo add hashicorp https://helm.releases.hashicorp.com
"hashicorp" has been added to your repositories

$ helm install vault hashicorp/vault

That is the entire quick start. Everything else is in the values file, and the documentation points you at it, saying to see the many options supported in `values.yaml`, and noting that these are fully documented on the Vault website along with more detailed installation instructions.

The division of labour between the chart and the product documentation is the thing to note. The chart's own README is short because the configuration surface is large and it lives in two places: the values file for the mechanics of the Kubernetes deployment, and the Vault and Kubernetes documentation for what the settings mean and how Vault behaves once running. If you are evaluating the chart, read the values file to see what can be configured, and read the product documentation to understand what you are configuring.

A schema generated from the values, so typos fail at install time

One Makefile target explains how `values.schema.json` is produced, and it is a small thing that makes a large difference in practice.

values-schema:
	helm schema-gen values.yaml > values.schema.json

The schema is generated from `values.yaml` itself, with the `helm schema-gen` command, and the Makefile comment points at `test/README.md` for the details. So the schema is not hand-maintained and cannot drift from the values: it is derived from them, which means a value that is removed from the file is also removed from the schema.

The practical effect is that a typo in a value key, or a value of the wrong type, is caught by Helm when the chart is rendered or installed, rather than being silently ignored. With a values file this large, silent ignoring is the failure mode that wastes an afternoon: the deployment comes up, Vault starts, and one setting is not applied, and the only symptom is that behaviour differs from what you configured.

This is also why the values file is the document to read first. It is the authoritative list of what the chart can configure, and the schema is the machine-checkable version of that list. A team that keeps its own overlay values file, as most teams do, gets this checking for free as long as the schema is present in the chart.

The test suite runs Bats in Docker, and acceptance tests against a real cluster

The Makefile is where the testing story lives, and it is more thorough than a typical chart.

The unit tests are Bats tests run inside a Docker image built from `test/docker/Test.dockerfile`:

test-image:
	@docker build --rm -t $(TEST_IMAGE) -f $(CURDIR)/test/docker/Test.dockerfile $(CURDIR)

test-unit:
	@docker run --rm -it -v ${PWD}:/helm-test $(TEST_IMAGE) bats -f $(UNIT_TESTS_FILTER) /helm-test/test/unit

The filter is configurable through `UNIT_TESTS_FILTER`, defaulting to `.*`, and a single test file can be selected by path, the example given in the Makefile comment being `acceptance/server-ha-enterprise-dr.bats`. The `test` target chains the image build and then `test-bats`, which is `test-unit` followed by `test-acceptance`.

The acceptance tests are the part that matters for a chart. By default they run against a GKE cluster, with the project and credentials passed into the container as environment variables, and the `KUBECONFIG` pointing at a config generated inside the container. There is a `test-provision` target that provisions the GKE cluster using terraform, and a `test-destroy` target that tears it down, so the whole lifecycle is scripted.

There is also a local path. Setting `LOCAL_ACCEPTANCE_TESTS=true` runs the acceptance tests locally in a kind cluster, and the Makefile sets the cluster name to `vault-helm` and the kind Kubernetes version to `v1.32.3`. That matters for a contributor, because the default acceptance run needs cloud credentials and a project, while the local path means the same tests can be run on a laptop.

The environment variables the acceptance run expects are also telling: `GOOGLE_CREDENTIALS`, `CLOUDSDK_CORE_PROJECT`, `KUBECONFIG` and `VAULT_LICENSE_CI`. The last one means at least part of the acceptance suite runs against a Vault build with a licence, which is the enterprise behaviour path.

Multiple deployment shapes live in one values file

The chart is described as supporting multiple use cases of Vault on Kubernetes depending on the values provided, and the way that works in practice is that the values file is the switchboard.

At one end is the dev server, a mode in which Vault runs in memory with a root token, which is what you point a local test at. At the other end are the production shapes: a server with persistent storage, TLS enabled, a seal mechanism, and standby nodes behind a service or an ingress that becomes the active node. The same file expresses all of them, and a deployment is a choice of values rather than a choice of chart.

The `values.openshift.yaml` file beside the main one is the platform-specific override for OpenShift, which is a hint about the shape of the values structure. There is a base file and a per-platform overlay, so a platform's conventions are expressed as a diff against the defaults rather than as a separate maintained file.

The `CODEOWNERS` file is the other detail worth mentioning. For a chart that HashiCorp ships from a repository named after itself, having code owners declared is a signal about how changes get reviewed, and it is the mechanism that makes the responsible disclosure note meaningful in practice, since a change to the templates or to the values has a named owner who sees it.

The release history is regular. v0.33.0 on 2026-06-08, v0.34.0 on 2026-07-02 and v0.34.1 on 2026-08-13, with a `CHANGELOG.md` recording what changed in each.

Where vault-helm is the wrong tool

The first case is a team that wants Vault to manage the cluster rather than live on it. This chart runs Vault inside Kubernetes, with its storage, its sealing and its TLS. If your requirement is Kubernetes secrets managed by an external Vault with the cluster as a client, the chart is the wrong direction, because the deployment topology is the opposite of what you need.

The second case is a cluster where you cannot run the chart's own dependency stack. The chart assumes Helm 3.6 and Kubernetes 1.29 or newer, and a Vault deployment on Kubernetes needs a storage backend, a service and usually an ingress, which in a locked-down cluster means asking the platform team for three things. A team without that relationship will spend more time on the prerequisites than on Vault.

The third case is expecting the chart to configure Vault for you. It renders the Kubernetes objects and passes values through, so anything that is a Vault server setting rather than a deployment setting still has to be applied to Vault itself, through the Vault CLI or the API, once the server is running. The chart gets Vault up; it does not decide your policies, your auth methods or your seal configuration.

A practical caution on upgrades. Because the values file is large and the versions move often, a chart upgrade that also changes defaults can change the behaviour of an existing deployment without changing any of your values. Reading the `CHANGELOG.md` between the version you are on and the version you are moving to, and diffing the rendered manifests, is the practice this chart's own test suite assumes you can do.

Editorial conclusion

The chart fits a team already running Vault elsewhere who wants the same configuration expressed as Kubernetes objects, because the values file is a faithful mirror of the Vault configuration surface rather than a simplified wrapper. It does not fit a team that wants Vault to manage the cluster rather than run on it. Before you pin a version, read `values.yaml` against the `values.schema.json` beside it, because the schema is generated from the values and is the only place a typo in your values file is caught before it reaches a cluster.

Frequently asked questions

Official sources

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