A new platform for documentation and tutorials is launching soon.
We are migrating Vault documentation into HashiCorp Developer, our new developer experience.
»Installing the Agent Injector
The Vault Helm chart is the recommended way to install and configure the Agent Injector in Kubernetes.
The Vault Agent Injector requires Vault 1.3.1 or greater.
To install a new instance of Vault and the Vault Agent Injector, first add the Hashicorp helm repository and ensure you have access to the chart:
$ helm repo add hashicorp https://helm.releases.hashicorp.com "hashicorp" has been added to your repositories $ helm search repo hashicorp/vault NAME CHART VERSION APP VERSION DESCRIPTION hashicorp/vault 0.22.0 1.11.3 Official HashiCorp Vault Chart
Then install the chart and enable the injection feature by setting the
injector.enabled value to
helm install vault hashicorp/vault --set="injector.enabled=true"
Upgrades may be performed with
helm upgrade on an existing install. Please
always run Helm with
--dry-run before any install or upgrade to verify
You can see all the available values settings by running
helm inspect values hashicorp/vault or by reading the Vault Helm Configuration
Docs. Commonly used values in the Helm
chart include limiting the namespaces the injector runs in, TLS options and
Admission webhook controllers require TLS to run within Kubernetes. The Injector defaults to supporting TLS 1.2 and above, and supports configuring the minimum supported TLS version and list of enabled cipher suites. These can be set via the following environment variables:
|Minimum supported version of TLS. Defaults to tls12. Accepted values are |
|Comma-separated list of enabled cipher suites for TLS 1.0-1.2. (Cipher suites are not configurable for TLS 1.3.)|
Warning: TLS 1.1 and lower are generally considered insecure.
These may be set in a Helm chart deployment via the injector.extraEnvironmentVars option:
helm install vault hashicorp/vault \ --set="injector.extraEnvironmentVars.AGENT_INJECT_TLS_MIN_VERSION=tls13" \ --set="injector.extraEnvironmentVars.AGENT_INJECT_TLS_CIPHER_SUITES=..."
The Vault Agent Injector also supports two TLS management options:
- Auto TLS generation (default)
- Manual TLS
By default, the Vault Agent Injector will bootstrap TLS by generating a certificate authority and creating a certificate/key to be used by the controller. If using Vault Helm, the chart will automatically create the necessary DNS entries for the controller's service used to verify the certificate.
If desired, users can supply their own TLS certificates, key and certificate authority. The following is required to configure TLS manually:
- Server certificate/key
- Base64 PEM encoded Certificate Authority bundle
For more information on configuring manual TLS, see the Vault Helm cert values.
This option may also be used in conjunction with cert-manager for certificate management.
»Multiple Replicas and TLS
The Vault Agent Injector can be run with multiple replicas if using Manual TLS or cert-manager, and as of v0.7.0 multiple replicas are also supported with Auto TLS. The number of replicas is controlled in the Vault Helm chart by the injector.replicas value.
With Auto TLS and multiple replicas, a leader replica is determined by ownership
of a ConfigMap named
vault-k8s-leader. Another replica can become the leader
once the current leader replica stops running, and the Kubernetes garbage
collector deletes the ConfigMap. The leader replica is in charge of generating
the CA and patching the webhook caBundle in Kubernetes, and also generating and
distributing the certificate and key to the "followers". The followers read the
certificate and key needed for the webhook service listener from a Kubernetes
Secret, which is updated by the leader when a certificate is near expiration.
With Manual TLS and multiple replicas,
can be set to
false since leader determination is not necessary in this case.
By default, the Vault Agent Injector will process all namespaces in Kubernetes except
the system namespaces
kube-public. To limit what namespaces
the injector can work in a namespace selector can be defined to match labels attached
For more information on configuring namespace selection, see the Vault Helm namespaceSelector value.