Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A minimal Vault client to manage secrets for Kubernetes pods.

Note: This project is in alpha stage. We are actively working on improving the functionality and incorporating the user feedback. Please see the roadmap. You are welcome to tryout and provide feedback.


Vault by HashiCorp is a tool for managing secrets i.e. sensitive data like passwords and certificates. Vault provides advanced features like dynamic secrets management and leases. Vault also integrates nicely with Kubernetes to allow using Kubernetes Service Accounts for authentictaion and authorization.

Vault can be accessed via an API or a command line tool. However, its typically not desireable, nor practical, to update application code to access Vault.

kube-vault-client is a Golang program, built as a static container, and designed to run in a Kubernetes Pod, to manage the process of fetching secrets from Vault.

Here is what it does:

  1. Uses the pod's service account JWT token and a supplied role to authenticate with Vault using the Kubernetes Authentication method.
  2. Once authenticated, fetches the secrets specified in a supplied path. The secrets are written to a configured file location.

You can read more how Nirmata uses kube-vault-client in this blog post.


kube-vault-client focuses on retrieving secrets from Vault. It is designed to be minimal, which is always great for security, but complete. This allows operational concerns for Vault, to be cleanly separated from the concerns of accessing secrets.

The design of kube-vault-client was heavily inspired by [kube-vault-auth-init] ( However, kube-vault-client does not require a separate AppRole, provides flexible options to map secrets, supports namespaces, and provides detailed status and error reporting for use as an Kuberneres init container.


Running locally

For local testing, you can run the image from docker hub

docker run nirmata/kube-vault-client:2.3.0

Running the image with no parameters will display the usage:

Usage of /kube-vault-client:
        log to standard error as well as files
  -cert string
        public key to use for HTTPS connections
        allow insecure HTTPS connections
  -jwt string
        the token to use for Vault authentication
  -kubeAuthPath string
        the Vault path for Kubernetes auth (e.g. kubernetes/prod) (default "kubernetes")
  -kubeAuthRole string
        the role to use for Vault Kubernetes authentication
  -log_backtrace_at value
        when logging hits line file:N, emit a stack trace
  -log_dir string
        If non-empty, write log files in this directory
        log to standard error instead of files
        (optional) the namespace to use if you have Vault Enterprise (X-Vault-Namespace)
  -out string
        location to store the secrets fetched from Vault (default "/var/run/secrets/vault")
  -secrets string
        a comma separated list of paths, keys, and variable names e.g (/secret/s1#k1#name, /secret/s1#k2#name, /secret/s2#k5#name
  -stderrthreshold value
        logs at or above this threshold go to stderr
  -terminationMessagePath string
        (optional) termination message path (default "/dev/termination-log")
  -tokenPath string
        location of token - used if a token is not provided. (default "/var/run/secrets/")
  -url string
        the Vault server URL (default "")
  -v value
        log level for V logs
  -vmodule value
        comma-separated list of pattern=N settings for file-filtered logging

The secrets string

You can control which secrets are retrieved from Vault using a comma separated list of paths. To retrieve a single entry, you can provide the entry key. For example:

secret/certs, secret/mysql#password

If the key is not specified, all keys at the specified path are retrieved. If a key is specified, you can also provide an optional variable name. For example:


This variable name is used when the secret is stored in the location specified by the out parameter.

Running in a Kubernetes Cluster

To fetch secrets for a Kubernetes application, you can run kube-vault-client as an init container within a Kubernetes pod.

Here is an example for running

apiVersion: extensions/v1beta1
kind: Deployment
  name: ghost
  namespace: ghost-aws-demo-prod
  replicas: 1
  revisionHistoryLimit: 5
    matchLabels: ghost
      maxSurge: 1
      maxUnavailable: 0
    type: RollingUpdate
      creationTimestamp: null
      labels: ghost
      - env:
          value: /var/run/vault
        image: ghost:0.11.9-alpine
        imagePullPolicy: Always
        name: ghost
        - containerPort: 2368
          protocol: TCP
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
        - mountPath: /var/run
          name: vault-secrets
      dnsPolicy: ClusterFirst
      - args:
        - -kubeAuthRole
        - ghost-prod-role
        - -out
        - /var/run/vault
        - -secrets
        - secret/ghost/prod, secret/ghost/prod#password#MY_PASSWORD, secret/ghost/prod#token#MY_TOKEN
        - -url
        - -kubeAuthPath
        - kubernetes/prod/aws-demo/
        name: vault-init-secrets
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
        - mountPath: /var/run
          name: vault-secrets
      serviceAccount: ghost-prod
      serviceAccountName: ghost-prod
      terminationGracePeriodSeconds: 30
      - hostPath:
          path: /var/run
          type: ""
        name: vault-secrets

Exit Codes

To propogate and report errors to Kubernetes APIs and utilities kube-vault-client uses the following exit codes and writes a message to the path specified in the terminationMessagePath command.

Code Meaning
0 Success
35 Invalid usage
36 Missing or invalid JWT token
37 Error during Vault login
38 Error while reading secrets
39 Error while writing secrets


To build the binary and docker image, clone this repository and run:



  • support periodic renewal of secrets that have an associated lease


A Vault client to manage secrets for Kubernetes pods.





No packages published