Using consul-template in the mutating webhook

With Bank-Vaults you can use Consul Template as an addition to vault-env to handle secrets that expire, and supply them to applications that read their configurations from a file.

When to use consul-template

  • You have an application or tool that must read its configuration from a file.
  • You wish to have secrets that have a TTL and expire.
  • You do not wish to be limited on which vault secrets backend you use.
  • You can also expire tokens/revoke tokens (to do this you need to have a ready/live probe that can send a HUP to consul-template when the current details fail).


The following shows the general workflow for using Consul Template:

  1. Your pod starts up. The webhook injects an init container (running vault agent) and a sidecar container (running consul-template) into the pods lifecycle.
  2. The vault agent in the init container logs in to Vault and retrieves a Vault token based on the configured VAULT_ROLE and Kubernetes Service Account.
  3. The consul-template running in the sidecar container logs in to Vault using the Vault token and writes a configuration file based on a pre-configured template in a configmap onto a temporary file system which your application can use.


This document assumes the following.

  • You have a working Kubernetes cluster which has:

  • You have a working knowledge of Kubernetes.

  • You can apply Deployments or PodSpec’s to the cluster.

  • You can change the configuration of the mutating webhook.

Use Vault TTLs

If you wish to use Vault TTLs, you need a way to HUP your application on configuration file change. You can configure the Consul Template to execute a command when it writes a new configuration file using the command attribute. The following is a basic example (adapted from here).


To configure the webhook, you can either:

Enable Consul Template in the webhook

For the webhook to detect that it will need to mutate or change a PodSpec, add the annotation to the Deployment or PodSpec you want to mutate, otherwise it will be ignored for configuration with Consul Template.

Defaults via environment variables

VAULT_IMAGEvault:latestthe vault image to use for the init container
VAULT_ENV_IMAGEbanzaicloud/vault-env:latestthe vault-env image to use
VAULT_CT_IMAGEhashicorp/consul-template:latestthe consul template image to use
VAULT_ADDRhttps:// service Vault endpoint URL
VAULT_SKIP_VERIFY“false”should vault agent and consul template skip verifying TLS
VAULT_TLS_SECRET""supply a secret with the vault TLS CA so TLS can be verified
VAULT_AGENT“true”enable the vault agent
VAULT_CT_SHARE_PROCESS_NAMESPACEKubernetes version <1.12 default off, 1.12 or higher default onShareProcessNamespace override

PodSpec annotations

AnnotationdefaultExplanation as VAULT_ADDR above Vault role for Vault agent to use<method type>The mount path of the method as VAULT_SKIP_VERIFY above as VAULT_TLS_SECRET above as VAULT_AGENT above""A configmap name which holds the consul template configuration""Specify a custom image for consul template not run consul-template in daemon mode, useful for kubernetes jobs Pull policy for the consul template container as VAULT_CT_SHARE_PROCESS_NAMESPACE above“100m”Specify the consul-template container CPU resource limit“128Mi”Specify the consul-template container memory resource limit“false”When enabled will only log warnings when Vault secrets are missing""Comma seprated list of VAULT_* related environment variables to pass through to main process. E.g.VAULT_ADDR,VAULT_ROLE.“/vault/secret”Mount path of Consul template rendered files