Virtual Event
Join us for the next HashiConf Digital October 12-15, 2020 Register for Free


Vault Installation to Minikube via Helm

Running Vault on Kubernetes is generally the same as running it anywhere else. Kubernetes, as a container orchestration engine, eases some of the operational burdens and Helm charts provide the benefit of a refined interface when it comes to deploying Vault in a variety of different modes.

In this guide, you will setup Vault and its dependencies with a Helm chart. Then integrate a web application that uses the Kubernetes service account token to authenticate with Vault and retrieve a secret.


This guide requires the Kubernetes command-line interface (CLI) and the Helm CLI installed, Minikube, the Vault and Consul Helm charts, the sample web application, and additional configuration to bring it all together.

Online tutorial: An interactive tutorial is also available if you do not wish to install the following resources. Click the Show Tutorial button to launch the tutorial.

This guide was last tested 20 Jun 2020 on a macOS 10.15.5 using this configuration.

Docker version.

$ docker version
Client: Docker Engine - Community
  Version:          19.03.8
  ## ...

Minikube version.

$ minikube version
minikube version: v1.11.0
commit: 57e2f55f47effe9ce396cea42a1e0eb4f611ebbd

Helm version.

$ helm version
version.BuildInfo{Version:"v3.2.1", GitCommit:"fe51cd1e31e6a202cba7dead9552a6d418ded79a", GitTreeState:"clean", GoVersion:"go1.13.10"}

These are recommended software versions and the output displayed may vary depending on your environment and the software versions you use.

First, follow the directions to install Minikube, including VirtualBox or similar.

Next, install kubectl CLI and helm CLI.

Install kubectl with Homebrew.

$ brew install kubernetes-cli

Install helm with Homebrew.

$ brew install helm

Next, retrieve the web application and additional configuration by cloning the hashicorp/vault-guides repository from GitHub.

$ git clone

This repository contains supporting content for all of the Vault learn guides. The content specific to this guide can be found within a sub-directory.

Go into the vault-guides/operations/provision-vault/kubernetes/minikube/getting-started directory.

$ cd vault-guides/operations/provision-vault/kubernetes/minikube/getting-started

»Start Minikube

Minikube is a CLI tool that provisions and manages the lifecycle of single-node Kubernetes clusters running inside Virtual Machines (VM) on your local system.

Start a Kubernetes cluster.

$ minikube start
😄  minikube v1.11.0 on Darwin 10.15.5
✨  Automatically selected the hyperkit driver
👍  Starting control plane node minikube in cluster minikube
🔥  Creating hyperkit VM (CPUs=2, Memory=4000MB, Disk=20000MB) ...
🐳  Preparing Kubernetes v1.18.3 on Docker 19.03.8 ...
🔎  Verifying Kubernetes components...
🌟  Enabled addons: default-storageclass, storage-provisioner
🏄  Done! kubectl is now configured to use "minikube"

The initialization process takes several minutes as it retrieves any necessary dependencies and executes various container images.

Verify the status of the Minikube cluster.

$ minikube status
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured

The host, kubelet, and apiserver report that they are running. The kubectl, a CLI for running commands against Kubernetes cluster, is also configured to communicate with this recently started cluster.

Minikube provides a visual representation of the status in a web-based dashboard. This interface displays the cluster activity in a visual interface that can be used to explore the issues affecting it.

In another terminal, launch the minikube dashboard.

$ minikube dashboard

The operating system's default browser opens and displays the dashboard.

Minikube Dashboard

»Install the Consul Helm chart

Consul is a service mesh solution that launches with a key-value store. Vault requires a storage backend like Consul to manage its configuration and secrets when it is run in high-availability.

The recommended way to run Consul on Kubernetes is via the Helm chart. Helm is a package manager that installs and configures all the necessary components to run Consul in several different modes. A Helm chart includes templates that enable conditional and parameterized execution. These parameters can be set through command-line arguments or defined in YAML.

Consul's Helm chart by default starts more services than required to act as Vault's storage backend.

Display the parameters in helm-consul-values.yml.

$ cat helm-consul-values.yml
  datacenter: vault-kubernetes-guide

  enabled: true

  replicas: 1
  bootstrapExpect: 1
    maxUnavailable: 0

Add the HashiCorp Helm repository.

$ helm repo add hashicorp
"hashicorp" has been added to your repositories

Install the latest version of the Consul Helm chart with parameters helm-consul-values.yml applied.

$ helm install consul hashicorp/consul --values helm-consul-values.yml
NAME:   consul
## ...

The installation of the Helm chart displays the name, namespace, status, and resources created. The server and client pods are deployed in the default namespace because no namespace was specified or configured as the default.

Get all the pods within the default namespace.

$ kubectl get pods
NAME                     READY   STATUS    RESTARTS   AGE
consul-consul-6jcfj      1/1     Running   0          2m54s
consul-consul-server-0   1/1     Running   0          2m54s

The Consul client and server pods are displayed here prefixed with consul.

Wait until the server and client pods report that they are Running and ready (1/1).

Minikube dashboard showing Consul pods

For more information refer to the Installing Consul to Minikube via Helm guide

»Install the Vault Helm chart

The recommended way to run Vault on Kubernetes is via the Helm chart. This installs and configures all the necessary components to run Vault in several different modes.

Vault's Helm chart by default launches with a file storage backend. To utilize the Consul cluster as a storage backend requires Vault to be run in high-availability mode.

Display the parameters in helm-vault-values.yml.

$ cat helm-vault-values.yml
  affinity: ""
    enabled: true

Install the latest version of the Vault Helm chart with parameters helm-vault-values.yml applied.

$ helm install vault hashicorp/vault --values helm-vault-values.yml
NAME: vault
## ...

The Vault pods and Vault Agent Injector pod are deployed in the default namespace.

Get all the pods within the default namespace.

$ kubectl get pods
NAME                                    READY   STATUS    RESTARTS   AGE
consul-consul-server-0                  1/1     Running   0          5m36s
consul-consul-sxpbj                     1/1     Running   0          5m36s
vault-0                                 0/1     Running   0          35s
vault-1                                 0/1     Running   0          34s
vault-2                                 0/1     Running   0          33s
vault-agent-injector-5945fb98b5-wpgx2   1/1     Running   0          36s

The vault-0, vault-1, vault-2, and vault-agent-injector pods are deployed. The Vault servers report that they are Running but they are not ready (0/1). That is because Vault in each pod is executes a status check defined in a readinessProbe.

Retrieve the status of Vault on the vault-0 pod.

$ kubectl exec vault-0 -- vault status
Key                Value
---                -----
Seal Type          shamir
Initialized        false
Sealed             true
Total Shares       0
Threshold          0
Unseal Progress    0/0
Unseal Nonce       n/a
Version            n/a
HA Enabled         false
command terminated with exit code 2

The status command reports that Vault is not initialized and that it is sealed.

Minikube dashboard showing sealed Vault pod

The web interface reports the same results.

»Initialize and unseal Vault

Vault starts uninitialized and in the sealed state. Prior to initialization the storage backend, Consul, is not prepared to receive data.

Initialize Vault with one key share and one key threshold.

$ kubectl exec vault-0 -- vault operator init -key-shares=1 -key-threshold=1 -format=json > cluster-keys.json

The operator init command generates a master key that it disassembles into key shares -key-shares=1 and then sets the number of key shares required to unseal Vault -key-threshold=1. These key shares are written to the output as unseal keys in JSON format -format=json. Here the output is redirected to a file named cluster-keys.json.

Display the unseal key found in cluster-keys.json.

$ cat cluster-keys.json | jq -r ".unseal_keys_b64[]"

Create a variable named VAULT_UNSEAL_KEY to capture the Vault unseal key.

$ VAULT_UNSEAL_KEY=$(cat cluster-keys.json | jq -r ".unseal_keys_b64[]")

After initialization, Vault is configured to know where and how to access the storage, but does not know how to decrypt any of it. Unsealing is the process of constructing the master key necessary to read the decryption key to decrypt the data, allowing access to the Vault.

Unseal Vault running on the vault-0 pod.

$ kubectl exec vault-0 -- vault operator unseal $VAULT_UNSEAL_KEY
Key                    Value
---                    -----
Seal Type              shamir
Initialized            true
Sealed                 false
Total Shares           1
Threshold              1
Version                1.4.2
Cluster Name           vault-cluster-40bde7f6
Cluster ID             7e0355e2-ee66-4d9e-f4eb-42ef453b857d
HA Enabled             true
HA Cluster             n/a
HA Mode                standby
Active Node Address    <none>

The operator unseal command reports that Vault is initialized and unsealed.

Unseal Vault running on the vault-1 pod.

$ kubectl exec vault-1 -- vault operator unseal $VAULT_UNSEAL_KEY
## ...

Unseal Vault running on the vault-2 pod.

$ kubectl exec vault-2 -- vault operator unseal $VAULT_UNSEAL_KEY
## ...

Verify all the Vault pods are running and ready.

$ kubectl get pods
NAME                                    READY   STATUS    RESTARTS   AGE
consul-consul-server-0                  1/1     Running   0          10m
consul-consul-sxpbj                     1/1     Running   0          10m
vault-0                                 1/1     Running   0          5m49s
vault-1                                 1/1     Running   0          5m48s
vault-2                                 1/1     Running   0          5m47s
vault-agent-injector-5945fb98b5-vzbqv   1/1     Running   0          5m50s

The vault-0, vault-1, and vault-2 pods report that they are Running but they are ready (1/1).

»Set a secret in Vault

The web application that you deploy in the Launch a web application section, expects Vault to store a username and password at the path secret/webapp/config. To create this secret requires you to login with the root token, enable the key-value secret engine, and store a secret username and password at that defined path.

Vault generated an initial root token when it was initialized.

Display the root token found in cluster-keys.json.

$ cat cluster-keys.json | jq -r ".root_token"

First, start an interactive shell session on the vault-0 pod.

$ kubectl exec -it vault-0 -- /bin/sh
/ $

Your system prompt is replaced with a new prompt / $.

Vault is now ready for you to login with the initial root token.

Vault requires clients to authenticate first before it allows any further actions. An unsealed Vault starts with the Token Auth Method enabled and generates an initial root token.

Login with the root token when prompted.

$ vault login
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                s.g3dGqNy5IYrj8E4EU8mSPeL2
token_accessor       JVsMJHVu6rTWbPLlYmWQTq1R
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

Enable kv-v2 secrets at the path secret.

$ vault secrets enable -path=secret kv-v2
Success! Enabled the kv-v2 secrets engine at: secret/

Create a secret at path secret/webapp/config with a username and password.

$ vault kv put secret/webapp/config username="static-user" password="static-password"
Key              Value
---              -----
created_time     2020-03-24T19:13:06.72377543Z
deletion_time    n/a
destroyed        false
version          1

Verify that the secret is defined at the path secret/webapp/config.

$ vault kv get secret/webapp/config
====== Metadata ======
Key              Value
---              -----
created_time     2020-03-24T19:13:06.72377543Z
deletion_time    n/a
destroyed        false
version          1

====== Data ======
Key         Value
---         -----
password    static-password
username    static-user

You successfully created the secret for the web application.

Lastly, exit the vault-0 pod.

$ exit

»Configure Kubernetes authentication

The initial root token is a privileged user that can perform any operation at any path. The web application only requires the ability to read secrets defined at a single path. This application should authenticate and be granted a token with limited access.

Vault provides a Kubernetes authentication method that enables clients to authenticate with a Kubernetes Service Account Token.

First, start an interactive shell session on the vault-0 pod.

$ kubectl exec -it vault-0 -- /bin/sh
/ $

Your system prompt is replaced with a new prompt / $.

Enable the Kubernetes authentication method.

$ vault auth enable kubernetes
Success! Enabled kubernetes auth method at: kubernetes/

Vault accepts this service token from any client within the Kubernetes cluster. During authentication, Vault verifies that the service account token is valid by querying a configured Kubernetes endpoint.

Configure the Kubernetes authentication method to use the service account token, the location of the Kubernetes host, and its certificate.

$ vault write auth/kubernetes/config \
        token_reviewer_jwt="$(cat /var/run/secrets/" \
        kubernetes_host="https://$KUBERNETES_PORT_443_TCP_ADDR:443" \
Success! Data written to: auth/kubernetes/config

The token_reviewer_jwt and kubernetes_ca_cert are mounted to the container by Kubernetes when it is created. The environment variable KUBERNETES_PORT_443_TCP_ADDR is defined and references the internal network address of the Kubernetes host.

For a client to access the secret data defined, at secret/webapp/config, requires that the read capability be granted for the path secret/data/webapp/config. This is an example of a policy. A policy defines a set of capabilities.

Write out the policy named webapp that enables the read capability for secrets at path secret/data/webapp/config.

$ vault policy write webapp - <<EOF
path "secret/data/webapp/config" {
  capabilities = ["read"]
Success! Uploaded policy: webapp

To apply this policy requires the authentication engine to define a role. A role binds policies and environment parameters together to create a login for the web application.

Create a Kubernetes authentication role, named webapp, that connects the Kubernetes service account name and webapp policy.

$ vault write auth/kubernetes/role/webapp \
        bound_service_account_names=vault \
        bound_service_account_namespaces=default \
        policies=webapp \
Success! Data written to: auth/kubernetes/role/webapp

The role connects the Kubernetes service account, vault, and namespace, default, with the Vault policy, webapp. The tokens returned after authentication are valid for 24 hours.

Lastly, exit the vault-0 pod.

/ $ exit

»Launch a web application

We've created a web application, published it to DockerHub, and created a Kubernetes deployment that will run the application in your existing cluster. The example web application performs the single function of listening for HTTP requests. During a request it reads the Kubernetes service token, logs into Vault, and then requests the secret.

Display the webapp deployment definition in deployment-01-webapp.yml.

$ cat deployment-01-webapp.yml
apiVersion: apps/v1
kind: Deployment
  name: webapp
    app: webapp
  replicas: 1
      app: webapp
        app: webapp
      serviceAccountName: vault
      - name: app
        image: burtlo/exampleapp-ruby:k8s
        imagePullPolicy: Always
        - name: VAULT_ADDR
          value: "http://vault:8200"
        - name: JWT_PATH
          value: "/var/run/secrets/"
        - name: SERVICE_PORT
          value: "8080"

The web application deployment defines a list of environment variables.

  • JWT_PATH sets the path of the JSON web token (JWT) issued by Kubernetes. This token is used by the web application to authenticate with Vault.
  • VAULT_ADDR sets the address of the Vault service. The Helm chart defined a Kubernetes service named vault that forwards requests to its endpoints (i.e. The pods named vault-0, vault-1, and vault-2).
  • SERVICE_PORT sets the port that the service listens for incoming HTTP requests.

Deploy the webapp in Kubernetes by applying the file deployment-01-webapp.yml.

$ kubectl apply --filename deployment-01-webapp.yml
deployment.apps/webapp created

The webapp runs as a pod within the default namespace.

Get all the pods within the default namespace.

$ kubectl get pods
NAME                                    READY   STATUS    RESTARTS   AGE
consul-consul-6jcfj                     1/1     Running   0          19m
consul-consul-server-0                  1/1     Running   0          19m
vault-0                                 1/1     Running   0          14m
vault-1                                 1/1     Running   0          14m
vault-2                                 1/1     Running   0          14m
vault-agent-injector-5945fb98b5-thczv   1/1     Running   0          14m
webapp-5c76d96c6-r4mcq                  1/1     Running   0          2m43s

The webapp pod is displayed here as the pod prefixed with webapp.

Wait until the webapp pod is running and ready (1/1).

The webapp pod runs an HTTP service that is listening on port 8080.

In another terminal, port forward all requests made to http://localhost:8080 to the webapp pod on port 8080.

$ kubectl port-forward \
    $(kubectl get pod -l app=webapp -o jsonpath="{.items[0]}") \

In the original terminal, perform a curl request at http://localhost:8080.

$ curl http://localhost:8080
{"password"=>"static-secret", "username"=>"static-user"}%

Web application showing username and password secret

The web application running on port 8080 in the webapp pod:

  • authenticates with the Kubernetes service account token
  • receives a Vault token with the read capability at the secret/data/webapp/config path
  • retrieves the secrets from secret/data/webapp/config path
  • displays the secrets as JSON

»Next Steps

You launched Vault in high-availability mode with a Helm chart. Learn more about the Vault Helm chart by reading the documentation or exploring the project source code.

Then you deployed a web application that authenticated and requested a secret directly from Vault. Explore how pods can retrieve secrets through the Vault Injector service via annotations or secrets mounted on ephemeral volumes.

Finally, Consul is more than a storage backend for Vault. Explore running Consul on Minikube via Helm and its integrations with Kubernetes (including multi-cloud, service sync, and other features) in the Consul documentation.