diff --git a/website/content/docs/agent/template-config.mdx b/website/content/docs/agent/template-config.mdx deleted file mode 100644 index 7b1498eba9..0000000000 --- a/website/content/docs/agent/template-config.mdx +++ /dev/null @@ -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 `""`) 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. diff --git a/website/content/docs/agent/template.mdx b/website/content/docs/agent/template.mdx index b63b7a9339..f2df9ad2ee 100644 --- a/website/content/docs/agent/template.mdx +++ b/website/content/docs/agent/template.mdx @@ -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 `""`) 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" +} +``` \ No newline at end of file diff --git a/website/content/docs/platform/k8s/helm/configuration.mdx b/website/content/docs/platform/k8s/helm/configuration.mdx index 68528398c7..bd5a81fe9d 100644 --- a/website/content/docs/platform/k8s/helm/configuration.mdx +++ b/website/content/docs/platform/k8s/helm/configuration.mdx @@ -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. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index ff11d24528..ea32d2d759 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -897,10 +897,6 @@ "title": "Templates", "path": "agent/template" }, - { - "title": "Template Config", - "path": "agent/template-config" - }, { "title": "Windows service", "path": "agent/winsvc"