This document assumes you have a working Kubernetes cluster which has a:

  • Working install of Vault.
  • Working install of the mutating webhook via helm or manually.
  • That you have a working knowledge of Kubernetes.
  • That you have the ability to apply Deployments or PodSpec’s to the cluster.
  • That you have the ability to change the configuration of the mutating webhook.

When to use vault-agent 🔗︎

  • You have an application or tool that requires to read its configuration from a file.
  • You wish to have secrets that have a TTL and expire.
  • You have no issues with running your application with a sidecar.

General concept 🔗︎

  • Your pod starts up, the webhook will inject one container into the pods lifecycle.
  • The sidecar container is running Vault, using the vault agent that accesses Vault using the configuration specified inside a configmap and writes a configuration file based on a pre configured template (written inside the same configmap) onto a temporary file system which your application can use.

Pre Configuration 🔗︎

ShareProcessNamespace 🔗︎

As of Kubernetes 1.10 you can share the process list of all containers in a pod, please check your Kubernetes API server FeatureGates configuration to find if it is on or not, it is default on in 1.12. The webhook will disable it by default in any version less than 1.12 and enable it by default for version 1.12 and above. You can override this configuration using the annotation or webhook vault_agent_share_process_namespace environment variable.

If you wish to use Vault TTLs, you need a way to HUP your application on configuration file change. Vault Agent can be configured to do that with a command attribute which will run when it writes a new configuration file. You can find a basic example below which uses/requires the ShareProcessNamespace feature and the Kubernetes Auth:

apiVersion: v1
kind: ConfigMap
  labels: my-app my-app-vault-agent
    branches: "true"
  name: my-app-vault-agent
  config.hcl: |
    vault {
      // This is needed until
      // gets fixed, otherwise it is automated by the webhook.
      ca_cert = "/vault/tls/ca.crt"
    auto_auth {
      method "kubernetes" {
        mount_path = "auth/kubernetes"
        config = {
          role = "my-role"
      sink "file" {
        config = {
          path = "/vault/.vault-token"
    template {
      contents = <<EOH
        {{- with secret "database/creds/readonly" }}
        username: {{ .Data.username }}
        password: {{ .Data.password }}
        {{ end }}
      destination = "/etc/secrets/config"
      command     = "/bin/sh -c \"kill -HUP $(pidof vault-demo-app) || true\""

Configuration 🔗︎

There are two places to configure the Webhook, you can set some sane defaults in the environment of the mutating webhook or you can configure it via annotations in your PodSpec.

Defaults via environment variables: 🔗︎

Variable default Explanation
VAULT_IMAGE vault:latest the vault image to use for the sidecar container
VAULT_IMAGE_PULL_POLICY IfNotPresent The pull policy for the vault agent container
VAULT_ADDR Kubernetes service Vault endpoint URL
VAULT_TLS_SECRET "” supply a secret with the vault TLS CA so TLS can be verified
VAULT_AGENT_SHARE_PROCESS_NAMESPACE Kubernetes version <1.12 default off, 1.12 or higher default on ShareProcessNamespace override

PodSpec annotations: 🔗︎

Annotation default Explanation Same as VAULT_ADDR above Same as VAULT_TLS_SECRET above "” A configmap name which holds the vault agent configuration false do not run vault-agent in daemon mode, useful for kubernetes jobs Same as VAULT_AGENT_SHARE_PROCESS_NAMESPACE above “100m” Specify the vault-agent container CPU resource limit “128Mi” Specify the vault-agent container memory resource limit “/vault/secrets” Mount path of Vault Agent rendered files

How to enable vault agent in the webhook? 🔗︎

For the webhook to detect that it will need to mutate or change a PodSpec, it must have the annotation otherwise the PodSpec will be ignored for configuration with Vault Agent.