--- title: "How to Manage Kubernetes Secrets with HashiCorp Vault" description: "Deploy HashiCorp Vault on Kubernetes with Helm, enable Kubernetes auth and inject secrets into pods with the Vault Agent Injector, with no secrets in manifests." category: "Kubernetes Advanced" language: en source: https://cubepath.com/docs/kubernetes-advanced/kubernetes-secrets-management-with-vault updated: 2026-09-25 --- # How to Manage Kubernetes Secrets with HashiCorp Vault Kubernetes Secrets are only base64-encoded, anyone with `get secrets` in a namespace can read them, and they usually end up copied into manifests or CI variables. HashiCorp Vault keeps secrets in one encrypted store, controls access with policies, logs every read, and can hand secrets to pods at runtime. In this tutorial you will deploy Vault on Kubernetes with its official Helm chart, initialize and unseal it, store a secret, let pods authenticate with their ServiceAccount, and inject the secret into an application with the Vault Agent Injector. ## Prerequisites To follow this tutorial you need: - A Kubernetes cluster (1.30 or newer) with a default StorageClass for persistent volumes. Run `kubectl get storageclass` and check that one is marked `(default)`. - `kubectl` with cluster-admin access and Helm 3 or 4 installed, for example on an Ubuntu 24.04 workstation or a CubePath VPS. - About 512 MB of free memory in the cluster for Vault and the injector. This tutorial deploys a single Vault server, which is the right way to learn the workflow. The last section lists what to change for production. ## Step 1 - Installing Vault with Helm Add the HashiCorp Helm repository: ```bash helm repo add hashicorp https://helm.releases.hashicorp.com helm repo update ``` ```output "hashicorp" has been added to your repositories ...Successfully got an update from the "hashicorp" chart repository Update Complete. ⎈Happy Helming!⎈ ``` Install the chart into a `vault` namespace. By default it deploys one Vault server with a persistent volume, plus the Agent Injector, a mutating webhook that adds a Vault Agent sidecar to annotated pods: ```bash helm install vault hashicorp/vault \ --namespace vault --create-namespace ``` Check the pods: ```bash kubectl get pods -n vault ``` ```output NAME READY STATUS RESTARTS AGE vault-0 0/1 Running 0 45s vault-agent-injector-7d8c6f9b5d-4xk2m 1/1 Running 0 45s ``` `vault-0` shows `0/1` on purpose: its readiness probe only passes once Vault is initialized and unsealed. Confirm that with `vault status`: ```bash kubectl exec -n vault vault-0 -- vault status ``` ```output Key Value --- ----- Seal Type shamir Initialized false Sealed true ... ``` The command exits with a non-zero code while Vault is sealed, so kubectl also prints `command terminated with exit code 2`. That is expected. ## Step 2 - Initializing and unsealing Vault Initialization creates the encryption keys and a root token. Vault splits the key that unlocks its storage into several **unseal key** shares; a threshold of them is required every time Vault starts. Initialize with 5 shares and a threshold of 3: ```bash kubectl exec -n vault vault-0 -- vault operator init -key-shares=5 -key-threshold=3 ``` ```output Unseal Key 1: 1a2b3c... Unseal Key 2: 4d5e6f... Unseal Key 3: 7g8h9i... Unseal Key 4: jklmno... Unseal Key 5: pqrstu... Initial Root Token: hvs.XXXXXXXXXXXXXXXXXXXXXXXX ... ``` > Important: This is the only time Vault shows these values. Store the unseal keys and root token in a password manager right away, ideally with each key held by a different person. Anyone with three keys and access to the storage can decrypt all your secrets. Do not save them in plain files on the server. Unseal Vault by running the following command three times, pasting a different unseal key each time. The key is read from a hidden prompt so it does not end up in your shell history: ```bash kubectl exec -it -n vault vault-0 -- vault operator unseal ``` ```output Unseal Key (will be hidden): Key Value --- ----- Sealed true Unseal Progress 1/3 ... ``` After the third key, `Sealed` changes to `false` and the pod becomes ready: ```bash kubectl get pods -n vault vault-0 ``` ```output NAME READY STATUS RESTARTS AGE vault-0 1/1 Running 0 4m ``` Vault seals itself again whenever the pod restarts, so you will repeat this step after node reboots or upgrades, unless you configure auto-unseal (see the production section). ## Step 3 - Storing a secret in the KV engine The rest of the Vault configuration is done with the `vault` CLI inside the pod, which already has `VAULT_ADDR` set. Open a shell there: ```bash kubectl exec -it -n vault vault-0 -- /bin/sh ``` Log in with the root token. The prompt hides what you type: ```bash vault login ``` ```output Token (will be hidden): Success! You are now authenticated. ... ``` Enable the key/value secrets engine, version 2 (which keeps a version history of each secret), at the path `secret/`: ```bash vault secrets enable -path=secret kv-v2 ``` ```output Success! Enabled the kv-v2 secrets engine at: secret/ ``` Store database credentials for an application called `webapp`. Replace the values with your own: ```bash vault kv put secret/webapp/config username="webapp_user" password="your_strong_password" ``` Read it back to confirm: ```bash vault kv get secret/webapp/config ``` ```output ====== Secret Path ====== secret/data/webapp/config ... ====== Data ====== Key Value --- ----- password your_strong_password username webapp_user ``` Note the path shown: KV version 2 stores data under `secret/data/...`. Policies and injector annotations must use that full path. ## Step 4 - Enabling Kubernetes authentication Pods should not carry Vault tokens. With the Kubernetes auth method, a pod presents its ServiceAccount token, Vault asks the Kubernetes API to validate it, and returns a Vault token with the policies mapped to that ServiceAccount. The Helm chart already gives Vault's ServiceAccount the `system:auth-delegator` role it needs to validate tokens. Still in the `vault-0` shell, enable and configure the method. When Vault runs inside the cluster, it only needs the API server address; it reads the CA certificate and its own token from the pod automatically: ```bash vault auth enable kubernetes vault write auth/kubernetes/config \ kubernetes_host="https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT" ``` ```output Success! Enabled kubernetes auth method at: kubernetes/ Success! Data written to: auth/kubernetes/config ``` Create a policy that allows reading only this one secret: ```bash vault policy write webapp - < -c vault-agent-init -n demo`. `permission denied` on the secret path usually means the policy path is missing `/data/` for KV version 2. `service account name not authorized` means the role's ServiceAccount or namespace does not match the pod. - **`vault-0` stays `0/1` after a restart**: Vault is sealed again. Unseal it with three keys as in Step 2. - **`connection refused` from `vault` commands**: you are running the CLI outside the pod without `VAULT_ADDR`. Use `kubectl exec` as in this tutorial, or `kubectl port-forward -n vault svc/vault 8200:8200` and `export VAULT_ADDR=http://127.0.0.1:8200`. ## Cleaning up Remove the demo application and, if you do not want to keep Vault, uninstall it and delete its data volume: ```bash kubectl delete namespace demo helm uninstall vault -n vault kubectl delete namespace vault ``` Deleting the `vault` namespace removes its PersistentVolumeClaim and, with it, every secret stored in this Vault instance. ## Conclusion You deployed Vault on Kubernetes with Helm, initialized and unsealed it, stored a secret in the KV engine, let pods authenticate with their ServiceAccount through the Kubernetes auth method, and delivered the secret to an application as a file without placing it in any manifest. Next, move toward the production layout above, explore dynamic secrets with the database secrets engine so each pod gets short-lived credentials, or use the Vault CSI provider if you prefer mounting secrets as CSI volumes instead of sidecars.