mirror of
https://github.com/hashicorp/vault.git
synced 2026-05-28 04:10:44 -04:00
docs/agent: merge template and template config (#15117)
* docs/agent: merge template and template config * Fix example * Update per review
This commit is contained in:
Jason O'Donnell
GitHub
parent
0e5a4a6703
commit
43d8fb971e
4 changed files with 113 additions and 112 deletions
|
|
@ -1,59 +0,0 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Vault Agent Template Config
|
||||
description: |-
|
||||
Vault Agent's Template Config to set Templating Engine behavior
|
||||
---
|
||||
|
||||
# Vault Agent Template Config
|
||||
|
||||
Template Config configures Vault Agent behavior common to all `template` stanzas.
|
||||
|
||||
For template-specific rendering configuration, refer to the parameters within the
|
||||
[`template`](/docs/agent/template) stanza.
|
||||
|
||||
## 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.
|
||||
|
||||
### 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`.
|
||||
|
||||
## Configuration
|
||||
|
||||
The top level `template_config` block has the following configuration entries:
|
||||
|
||||
- `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.
|
||||
|
|
@ -3,9 +3,7 @@ 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.
|
||||
files using Consul Template markup.
|
||||
---
|
||||
|
||||
# Vault Agent Templates
|
||||
|
|
@ -13,11 +11,17 @@ description: >-
|
|||
Vault Agent's Template functionality allows Vault secrets to be rendered to files
|
||||
using [Consul Template markup](https://github.com/hashicorp/consul-template/blob/v0.27.1/docs/templating-language.md).
|
||||
|
||||
For globally applicable templating engine configuration, refer to the parameters
|
||||
within the [`template_config`](/docs/agent/template-config) stanza.
|
||||
|
||||
## 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.
|
||||
|
|
@ -35,7 +39,65 @@ The following links contain additional resources for the templating language use
|
|||
- [Consul Templating Documentation](https://github.com/hashicorp/consul-template/blob/v0.27.1/docs/templating-language.md)
|
||||
- [Go Templating Language Documentation](https://pkg.go.dev/text/template#pkg-overview)
|
||||
|
||||
## Configuration
|
||||
## Example Template
|
||||
|
||||
Template with Vault Agent requires the use of the `secret` [function from Consul
|
||||
Template](https://github.com/hashicorp/consul-template/blob/master/docs/templating-language.md#secret).
|
||||
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 }}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
### Example
|
||||
|
||||
```python
|
||||
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 configurations entries:
|
||||
|
||||
|
|
@ -80,50 +142,10 @@ The top level `template` block has multiple configurations entries:
|
|||
- `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
|
||||
|
||||
Template with Vault Agent requires the use of the `secret` [function from Consul
|
||||
Template](https://github.com/hashicorp/consul-template/blob/master/docs/templating-language.md#secret).
|
||||
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 }}
|
||||
```
|
||||
|
||||
## Example Configuration
|
||||
|
||||
The following demonstrates configuring Vault Agent to template secrets using the
|
||||
AppRole Auth method:
|
||||
### Example
|
||||
|
||||
```python
|
||||
pid_file = "./pidfile"
|
||||
|
||||
vault {
|
||||
address = "https://127.0.0.1:8200"
|
||||
}
|
||||
|
||||
auto_auth {
|
||||
method {
|
||||
type = "approle"
|
||||
|
||||
config = {
|
||||
role_id_file_path = "/etc/vault/roleid"
|
||||
secret_id_file_path = "/etc/vault/secretid"
|
||||
}
|
||||
}
|
||||
|
||||
sink {
|
||||
type = "file"
|
||||
|
||||
config = {
|
||||
path = "/tmp/file-foo"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
template {
|
||||
source = "/tmp/agent/template.ctmpl"
|
||||
destination = "/tmp/agent/render.txt"
|
||||
|
|
@ -171,3 +193,45 @@ using the certificates `validTo` field.
|
|||
|
||||
This does not apply to certificates generated with `generate_lease: true`. If set
|
||||
Vault Agent template will apply the non-renewable, leased secret rules.
|
||||
|
||||
## Auto Auth and Templating Example
|
||||
|
||||
The following demonstrates configuring Vault Agent to template secrets using the
|
||||
AppRole Auth method:
|
||||
|
||||
```python
|
||||
pid_file = "./pidfile"
|
||||
|
||||
vault {
|
||||
address = "https://127.0.0.1:8200"
|
||||
}
|
||||
|
||||
auto_auth {
|
||||
method {
|
||||
type = "approle"
|
||||
|
||||
config = {
|
||||
role_id_file_path = "/etc/vault/roleid"
|
||||
secret_id_file_path = "/etc/vault/secretid"
|
||||
}
|
||||
}
|
||||
|
||||
sink {
|
||||
type = "file"
|
||||
|
||||
config = {
|
||||
path = "/tmp/file-foo"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
template_config {
|
||||
static_secret_render_interval = "10m"
|
||||
exit_on_retry_failure = true
|
||||
}
|
||||
|
||||
template {
|
||||
source = "/tmp/agent/template.ctmpl"
|
||||
destination = "/tmp/agent/render.txt"
|
||||
}
|
||||
```
|
||||
|
|
@ -94,7 +94,7 @@ and consider if they're appropriate for your deployment.
|
|||
- `template` (`string: "map"`) - The default template type for rendered secrets if no custom templates are defined.
|
||||
Possible values include `map` and `json`.
|
||||
|
||||
- `templateConfig` - Default values within Agent's [`template_config` stanza](/docs/agent/template-config).
|
||||
- `templateConfig` - Default values within Agent's [`template_config` stanza](/docs/agent/template).
|
||||
|
||||
- `exitOnRetryFailure` (`boolean: true`) - Controls whether Vault Agent exits after it has exhausted its number of template retry attempts due to failures.
|
||||
|
||||
|
|
|
|||
|
|
@ -897,10 +897,6 @@
|
|||
"title": "Templates",
|
||||
"path": "agent/template"
|
||||
},
|
||||
{
|
||||
"title": "Template Config",
|
||||
"path": "agent/template-config"
|
||||
},
|
||||
{
|
||||
"title": "Windows service",
|
||||
"path": "agent/winsvc"
|
||||
|
|
|
|||
Loading…
Reference in a new issue