New to KubeVault? Please start here.

Mount Key/Value Secrets into Kubernetes pod using CSI Driver

Before you Begin

At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using Minikube.

To keep things isolated, this tutorial uses a separate namespace called demo throughout this tutorial.

$ kubectl create ns demo
namespace "demo" created

Note: YAML files used in this tutorial stored in docs/examples/csi-driver/kv folder in github repository KubeVault/docs

Configure Vault

The following steps are required to retrieve secrets from Key/Value secrets engine using Vault server into a Kubernetes pod.

  • Vault server: used to provision and manager Key/Value secrets
  • Appbinding: required to connect CSI driver with Vault server
  • Role: using this role CSI driver can access credentials from Vault server

There are two ways to configure Vault server. You can use either use Vault Operator or use vault cli to manually configure a Vault server.

Using Vault Operator

Follow this tutorial to manage Key/Value secrets with Vault operator. After successful configuration you should have following resources present in your cluster.

  • AppBinding: An appbinding with name vault-app in demo namespace
Using Vault CLI

You can use Vault cli to manually configure an existing Vault server. The Vault server may be running inside a Kubernetes cluster or running outside a Kubernetes cluster. If you don’t have a Vault server, you can deploy one by running the following command:

$ kubectl apply -f
service/vault created
statefulset.apps/vault created

To use secret from KV engine, you have to do following things.

  1. Enable KV Engine: To enable KV secret engine run the following command.

    $ vault secrets enable -version=1 kv
    Success! Enabled the kv secrets engine at: kv/
  2. Create Engine Policy: To read secret from engine, we need to create a policy with read capability. Create a policy.hcl file and write the following content:

    # capability of get secret
    path "kv/*" {
        capabilities = ["read"]

    Write this policy into vault naming test-policy with following command:

    $ vault policy write test-policy policy.hcl
    Success! Uploaded policy: test-policy
  3. Write Secret on Vault: Create a secret on vault by running:

    $ vault kv put kv/my-secret my-value=s3cr3t
    Success! Data written to: kv/my-secret

Configure Cluster

  1. Create Service Account: Create service.yaml file with following content:

      kind: ClusterRoleBinding
        name: role-tokenreview-binding
        namespace: demo
        kind: ClusterRole
        name: system:auth-delegator
      - kind: ServiceAccount
        name: kv-vault
        namespace: demo
      apiVersion: v1
      kind: ServiceAccount
        name: kv-vault
        namespace: demo

    After that, run kubectl apply -f service.yaml to create a service account.

  2. Enable Kubernetes Auth: To enable Kubernetes auth backend, we need to extract the token reviewer JWT, Kubernetes CA certificate and Kubernetes host information.

    export VAULT_SA_NAME=$(kubectl get sa kv-vault -n demo -o jsonpath="{.secrets[*]['name']}")
    export SA_JWT_TOKEN=$(kubectl get secret $VAULT_SA_NAME -n demo -o jsonpath="{.data.token}" | base64 --decode; echo)
    export SA_CA_CRT=$(kubectl get secret $VAULT_SA_NAME -n demo -o jsonpath="{.data['ca\.crt']}" | base64 --decode; echo)
    export K8S_HOST=<host-ip>
    export K8s_PORT=6443

    Now, we can enable the Kubernetes authentication backend and create a Vault named role that is attached to this service account. Run:

    $ vault auth enable kubernetes
    Success! Enabled Kubernetes auth method at: kubernetes/
    $ vault write auth/kubernetes/config \
        token_reviewer_jwt="$SA_JWT_TOKEN" \
        kubernetes_host="https://$K8S_HOST:$K8s_PORT" \
    Success! Data written to: auth/kubernetes/config
    $ vault write auth/kubernetes/role/kvrole \
        bound_service_account_names=kv-vault \
        bound_service_account_namespaces=demo \
        policies=test-policy \
    Success! Data written to: auth/kubernetes/role/kvrole

    Here, kvrole is the name of the role.

  3. Create AppBinding: To connect CSI driver with Vault, we need to create an AppBinding. First we need to make sure, if AppBinding CRD is installed in your cluster by running:

    $ kubectl get crd -l app=catalog
    NAME                                          CREATED AT           2018-12-12T06:09:34Z

    If you don’t see that CRD, you can register it via the following command:

    kubectl apply -f

    If AppBinding CRD is installed, Create AppBinding with the following data:

    kind: AppBinding
      name: vault-app
      namespace: demo
      url: # Replace this with Vault URL
      apiVersion: ""
      kind: "VaultServerConfiguration"
      usePodServiceAccountForCSIDriver: true
      authPath: "kubernetes"
      policyControllerRole: kvrole # we created this in previous step

Mount secrets into a Kubernetes pod

After configuring Vault server, now we have vault-app AppBinding in demo namespace.

So, we can create StorageClass now.

Create StorageClass: Create storage-class.yaml file with following content, then run kubectl apply -f storage-class.yaml

kind: StorageClass
  name: vault-kv-storage
  namespace: demo
annotations: "false"
  ref: demo/vault-app # namespace/AppBinding, we created this in previous step
  engine: KV # vault engine name
  secret: my-secret # secret name on vault which you want get access
  path: kv # specify the secret engine path, default is kv

Test & Verify

  1. Create PVC: Create a PersistantVolumeClaim with following data. This makes sure a volume will be created and provisioned on your behalf.

    apiVersion: v1
    kind: PersistentVolumeClaim
      name: csi-pvc
      namespace: demo
      - ReadWriteOnce
          storage: 1Gi
      storageClassName: vault-kv-storage
      volumeMode: DirectoryOrCreate
  2. Create Pod: Now we can create a Pod which refers to this volume. When the Pod is created, the volume will be attached, formatted and mounted to the specific container.

    apiVersion: v1
    kind: Pod
      name: mypod
      namespace: demo
      - name: mypod
        image: busybox
          - sleep
          - "3600"
        - name: my-vault-volume
          mountPath: "/etc/foo"
          readOnly: true
      serviceAccountName: kv-vault
        - name: my-vault-volume
            claimName: csi-pvc

    Check if the Pod is running successfully, by running:

    kubectl describe pods/my-pod
  3. Verify Secret: If the Pod is running successfully, then check inside the app container by running

    $ kubectl exec -ti mypod /bin/sh
    / # ls /etc/foo
    / # cat /etc/foo/my-value

    So, we can see that the secret my-secret is mounted into the pod, where the secret key is mounted as file and value is the content of that file.

Cleaning up

To cleanup the Kubernetes resources created by this tutorial, run:

$ kubectl delete ns demo
namespace "demo" deleted