open-vault/website/content/docs/agent/template.mdx

---
layout: docs
page_title: Vault Agent Template
description: >-
  Vault Agent's Template functionality allows Vault secrets to be rendered to
  files using Consul Template markup.
---

# Vault Agent Templates

Vault Agent's Template functionality allows Vault secrets to be rendered to files
using [Consul Template markup][consul-templating-language].

## Functionality

The `template_config` stanza configures overall default behavior for the
templating engine. Note that `template_config` can only be defined once, and is
different from the `template` stanza. Unlike `template` which focuses on where
and how a specific secret is rendered, `template_config` contains parameters
affecting how the templating engine as a whole behaves and its interaction with
the rest of Agent. This includes, but is not limited to, program exit behavior.
Other parameters that apply to the templating engine as a whole may be added
over time.

The `template` stanza configures the Vault agent for rendering secrets to files
using Consul Template markup language. Multiple `template` stanzas can be
defined to render multiple files.

When the agent is started with templating enabled, it will attempt to acquire a
Vault token using the configured auto-auth Method. On failure, it will back off
for a short while (including some randomness to help prevent thundering herd
scenarios) and retry. On success, secrets defined in the templates will be
retrieved from Vault and rendered locally.

## Templating Language

The template output content can be provided directly as part of the `contents`
option in a `template` stanza or as a separate `.ctmpl` file and specified in
the `source` option of a `template` stanza.

In order to fetch secrets from Vault, whether those are static secrets, dynamic
credentials, or certificates, Vault Agent templates require the use of the
`secret`
[function](https://github.com/hashicorp/consul-template/blob/master/docs/templating-language.md#secret)
or `pkiCert`
[function](https://github.com/hashicorp/consul-template/blob/main/docs/templating-language.md#pkicert)
from Consul Template.

The `secret` function works for all types of secrets and depending on the type
of secret that's being rendered by this function, template will have different
renewal behavior as detailed in the [Renewals
section](#renewals-and-updating-secrets). The `pkiCert` function is intended to
work specifically for certificates issued by the [PKI Secrets
Engine](/docs/secrets/pki). Refer to the [Certificates](#certificates) section
for differences in certificate renewal behavior between `secret` and `pkiCert`.

The following links contain additional resources for the templating language used by Vault Agent templating.

- [Consul Templating Documentation][consul-templating-language]
- [Go Templating Language Documentation](https://pkg.go.dev/text/template#pkg-overview)

### Template Language Example

The following is an example of a template that retrieves a generic secret from Vault's
KV store:
```
{{ with secret "secret/my-secret" }}
{{ .Data.data.foo }}
{{ end }}
```

The following is an example of a template that issues a PKI certificate in
Vault's PKI secrets engine. The fetching of the certificate or key from a PKI role
through this function will be based on the certificate's expiration.

To generate a new certificate and create a bundle with the key, certificate, and CA, use:
```
{{ with pkiCert "pki/issue/my-domain-dot-com" "common_name=foo.example.com" }}
{{ .Data.Key }}
{{ .Data.Cert }}
{{ .Data.CA }}
{{ end }}
```

To fetch only the issuing CA for this mount, use:

```
{{- with secret "pki/cert/ca" -}}
{{ .Data.certificate }}
{{- end -}}
```

Alternatively, `pki/cert/ca_chain` can be used to fetch the full CA chain.

## Global Configurations

The top level `template_config` block has the following configuration entries that affect
all templates:

- `exit_on_retry_failure` `(bool: false)` - This option configures Vault Agent
to exit after it has exhausted its number of template retry attempts due to
failures.

- `static_secret_render_interval` `(string or integer: 5m)` - If specified, configures
  how often Vault Agent Template should render non-leased secrets such as KV v2.
  This setting will not change how often Vault Agent Templating renders leased
  secrets. Uses [duration format strings](/docs/concepts/duration-format).

### `template_config` Stanza Example

```hcl
template_config {
  exit_on_retry_failure = true
  static_secret_render_interval = "10m"
}
```

### Interaction between `exit_on_retry_failure` and `error_on_missing_key`

The parameter
[`error_on_missing_key`](/docs/agent/template#error_on_missing_key) can be
specified within the `template` stanza which determines if a template should
error when a key is missing in the secret. When `error_on_missing_key` is not
specified or set to `false` and the key to render is not in the secret's
response, the templating engine will ignore it (or render `"<no value>"`) and
continue on with its rendering.

If the desire is to have Agent fail and exit on a missing key, both
`template.error_on_missing_key` and `template_config.exit_on_retry_failure` must
be set to true. Otherwise, the templating engine will error and render to its
destination, but agent will not exit and will retry until the key exists or until
the process is terminated.

Note that a missing key from a secret's response is different from a missing or
non-existent secret. The templating engine will always error if a secret is
missing, but will only error for a missing key if `error_on_missing_key` is set.
Whether Vault Agent will exit when the templating engine errors depends on the
value of `exit_on_retry_failure`.

## Template Configurations

The top level `template` block has multiple configuration entries. The
parameters found in the template configuration section in the consul-template
[documentation
page](https://github.com/hashicorp/consul-template/blob/main/docs/configuration.md#templates)
can be used here:

- `source` `(string: "")` - Path on disk to use as the input template. This
  option is required if not using the `contents` option.
- `destination` `(string: required)` - Path on disk where the rendered secrets should
  be created. If the parent directories do not exist, Vault
  Agent will attempt to create them, unless `create_dest_dirs` is false.
- `create_dest_dirs` `(bool: true)` - This option tells Vault Agent to create
  the parent directories of the destination path if they do not exist.
- `contents` `(string: "")` - This option allows embedding the contents of
  a template in the configuration file rather then supplying the `source` path to
  the template file. This is useful for short templates. This option is mutually
  exclusive with the `source` option.
- `command` `(string: "")` - This is the optional command to run when the
  template is rendered. The command will only run if the resulting template changes.
  The command must return within 30s (configurable), and it must have a successful
  exit code. Vault Agent is not a replacement for a process monitor or init system.
  This is deprecated in favor of the `exec` option.
- `command_timeout` `(duration: 30s)` - This is the maximum amount of time to
  wait for the optional command to return. This is deprecated in favor of the
  `exec` option.
- `error_on_missing_key` `(bool: false)` - Exit with an error when accessing
  a struct or map field/key that does notexist. The default behavior will print `<no value>`
  when accessing a field that does not exist. It is highly recommended you set this
  to "true".
- `exec` `(object: optional)` - The exec block executes a command when the
  template is rendered and the output has changed. The block parameters are
  `command` `(string slice: required)` and `timeout` `(string: optional, defaults
  to 30s)`.
- `perms` `(string: "")` - This is the permission to render the file. If
  this option is left unspecified, Vault Agent will attempt to match the permissions
  of the file that already exists at the destination path. If no file exists at that
  path, the permissions are 0644.
- `backup` `(bool: true)` - This option backs up the previously rendered template
  at the destination path before writing a new one. It keeps exactly one backup.
  This option is useful for preventing accidental changes to the data without having
  a rollback strategy.
- `left_delimiter` `(string: "{{")` - Delimiter to use in the template. The
  default is "{{" but for some templates, it may be easier to use a different
  delimiter that does not conflict with the output file itself.
- `right_delimiter` `(string: "}}")` - Delimiter to use in the template. The
  default is "}}" but for some templates, it may be easier to use a different
  delimiter that does not conflict with the output file itself.
- `sandbox_path` `(string: "")` - If a sandbox path is provided, any path
  provided to the `file` function is checked that it falls within the sandbox path.
  Relative paths that try to traverse outside the sandbox path will exit with an error.
- `wait` `(object: required)` - This is the `minimum(:maximum)` to wait before rendering
  a new template to disk and triggering a command, separated by a colon (`:`).


### Example `template` Stanza

```hcl
template {
  source      = "/tmp/agent/template.ctmpl"
  destination = "/tmp/agent/render.txt"
}
```

If you only want to use the Vault agent to render one or more templates and do
not need to sink the acquired credentials, you can omit the `sink` stanza from
the `auto_auth` stanza in the agent configuration.

## Renewals and Updating Secrets

The Vault Agent templating automatically renews and fetches secrets/tokens.
Unlike [Vault Agent caching](/docs/agent/caching), the behavior of how Vault Agent
templating does this depends on the type of secret or token. The following is a
high level overview of different behaviors.

### Renewable Secrets

If a secret or token is renewable, Vault Agent will renew the secret after 2/3
of the secret's lease duration has elapsed.

### Non-Renewable Secrets

If a secret or token isn't renewable or leased, Vault Agent will fetch the secret every 5 minutes.
This can be configured using Template config [static_secret_render_interval](/docs/agent/template-config#static_secret_render_interval) (requires Vault 1.8+).
Non-renewable secrets include (but not limited to) [KV Version 2](/docs/secrets/kv/kv-v2).

### Non-Renewable Leased Secrets

If a secret or token is non-renewable but leased, Vault Agent will fetch the secret when 85% of the
secrets time-to-live (TTL) is reached. Leased, non-renewable secrets include (but not limited
to) dynamic secrets such as [database credentials](/docs/secrets/databases) and [KV Version 1](/docs/secrets/kv/kv-v1).

### Static Roles

If a secret has a `rotation_period`, such as a [database static role](/docs/secrets/databases#static-roles),
Vault Agent template will fetch the new secret as it changes in Vault. It does
this by inspecting the secret's time-to-live (TTL).

### Certificates

As of Vault 1.11, certificates can be rendered using either `pkiCert` or
`secret` template functions, although it is recommended to use `pkiCert` to
avoid unnecessarily generating certificates whenever Agent restarts or
re-authenticates.

#### Rendering using the `pkiCert` template function

If a [certificate](/docs/secrets/pki) is rendered using the `pkiCert` template
function, Vault Agent template will have the following fetching and re-rendering
behaviors on certificates:

- Fetches a new certificate on Agent startup if none has been previously
rendered or the current rendered one has expired.
- On Agent's auto-auth re-authentication, due to a token expiry for example,
skip fetching unless the current rendered one has expired.

#### Rendering using the `secret` template function

If a [certificate](/docs/secrets/pki) is rendered using the `secret` template
function, Vault Agent template will have the following fetching and re-rendering
behaviors on certificates:

- Fetches a new certificate on Agent startup, even if previously rendered
  certificates are still valid.
- If `generate_lease` is unset or set to `false`, it uses the certificate's
  `validTo` field to determine re-fetch interval.
- If `generate_lease` is set to `true`, apply the non-renewable, leased secret
  rules.
- On Agent's auto-auth re-authentication, due to a token expiry for example, it
  fetches and re-renders a new certificate even if the existing certificate is
  valid.

## Templating Configuration Example

The following demonstrates Vault Agent Templates configuration blocks.

```hcl
# Other Vault Agent configuration blocks
# ...

template_config {
  static_secret_render_interval = "10m"
  exit_on_retry_failure = true
}

template {
  source      = "/tmp/agent/template.ctmpl"
  destination = "/tmp/agent/render.txt"
}

template {
  contents     = "{{ with secret \"secret/my-secret\" }}{{ .Data.data.foo }}{{ end }}"
  destination  = "/tmp/agent/render-content.txt"
}
```

[consul-templating-language]: https://github.com/hashicorp/consul-template/blob/v0.28.1/docs/templating-language.md