From 2aaf71dac4b464934f4c901c6b85efce7ec0a745 Mon Sep 17 00:00:00 2001 From: Jim Kalafut Date: Thu, 25 Feb 2021 22:36:45 -0800 Subject: [PATCH] Revert "Add docs for Agent's template_retry option added in #10644, based on those from consul-template configuration. Also fix some existing config docs that weren't adhering to our conventions. (#10911)" 8e0c00cdb19cc64c54a3b0aa7e6375b22819c74d --- website/content/docs/agent/template.mdx | 60 +++++++------------------ 1 file changed, 17 insertions(+), 43 deletions(-) diff --git a/website/content/docs/agent/template.mdx b/website/content/docs/agent/template.mdx index 5bd9c05d3fe5..27332363aaf9 100644 --- a/website/content/docs/agent/template.mdx +++ b/website/content/docs/agent/template.mdx @@ -4,7 +4,7 @@ page_title: Vault Agent Template sidebar_title: Templates description: >- Vault Agent's Template functionality allows Vault secrets to be rendered to - files + files using Consul Template markup. --- @@ -30,42 +30,43 @@ rendered locally. The top level `template` block has multiple configurations entries: -- `source` `(string: "")` - Path on disk to use as the input template. This +- `source` `(object: optional)` - 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 +- `destination` `(object: required)` - Path on disk where the rendered secrets should be created. If the parent directories 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 +- `create_dest_dirs` `(object: required)` - This option tells Vault Agent to create + the parent directories of the destination path if they do not exist. The default + value is true. +- `contents` `(object: optional)` - 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 +- `command` `(object: optional)` - 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. -- `command_timeout` `(duration: 30s)` - This is the maximum amount of time to - wait for the optional command to return. -- `error_on_missing_key` `(bool: false)` - Exit with an error when accessing +- `command_timeout` `(object: optional)` - This is the maximum amount of time to + wait for the optional command to return. Default is 30s. +- `error_on_missing_key` `(object: optional)` - Exit with an error when accessing a struct or map field/key that does notexist. The default behavior will print `` when accessing a field that does not exist. It is highly recommended you set this to "true". -- `perms` `(string: "")` - This is the permission to render the file. If +- `perms` `(object: optional)` - 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 +- `backup` `(object: optional)` - 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 +- `left_delimiter` `(object: optional)` - 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 +- `right_delimiter` `(object: optional)` - 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 +- `sandbox_path` `(object: optional)` - 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 @@ -119,39 +120,12 @@ template { source = "/tmp/agent/template.ctmpl" destination = "/tmp/agent/render.txt" } - -template_retry { - enabled = true - attempts = 5 - backoff = "100ms" - max_backoff = "400ms" -} ``` 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. -The `template_retry` stanza controls the retry behavior when an error is returned -from Vault. Vault Agent is highly fault tolerant, meaning it does not exit in the -face of failure. Instead, it uses exponential back-off and retry functions -to wait for the cluster to become available, as is customary in distributed -systems. - -`template_retry` options: -- `enabled` `(bool: true)` - This enabled retries. Retries are enabled by default, -so this is redundant unless set to false. -- `attempts` `(int: 12)` - This specifies the number of attempts to make before -giving up. Each attempt adds the exponential backoff sleep time. Setting this to -zero will implement an unlimited number of retries. -- `backoff` `(duration: "250ms")` - This is the base amount of time to sleep -between retry attempts. Each retry sleeps for an exponent of 2 longer than this -base. For 5 retries, the sleep times would be: 250ms, 500ms, 1s, 2s, then 4s. -- `max_backoff` `(duration: "1m")` - This is the maximum amount of time to sleep -between retry attempts. When max_backoff is set to zero, there is no upper limit to the -exponential sleep between retry attempts. If max_backoff is set to 10s and backoff is -set to 1s, sleep times would be: 1s, 2s, 4s, 8s, 10s, 10s, ... - ## Renewals and Updating Secrets The Vault Agent templating automatically renews and fetches secrets/tokens. @@ -161,7 +135,7 @@ high level overview of different behaviors. ### Renewable Secrets -If a secret or token is renewable, Vault Agent will renew the secret after 2/3 +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