hashicorp / consul-template

--- Consul Template This project provides a convenient way to populate values from [Consul][consul] into the file system using the daemon. The daemon queries a [Consul][consul], [Vault][vault], or [Nomad][nomad] cluster and updates any number of specified templates on the file system. As an added bonus, it can optionally run arbitrary commands when the update process completes. Please see the [examples folder][examples] for some scenarios where this functionality might prove useful. --- **The documentation in this README corresponds to the main branch of Consul Template. It may contain unreleased features or different APIs than the most recently released version.** **Please see the Git tag that corresponds to your version of Consul Template for the proper documentation.** --- Table of Contents • Community Support • Installation • Quick Example • Learn Guides • Configuration • Command Line Flags • Configuration File • Reload Configuration and Templates • Templating Language • API Functions • Scratch • Helper Functions • Math Functions • Observability • Logging • Logging to file • Modes • Once Mode • De-Duplication Mode • Exec Mode • Plugins • Caveats • Docker Image Use • Dots in Service Names • Termination on Error • Commands • Environment • Multiple Commands • Multi-phase Execution • Debugging • FAQ • Contributing Community Support If you have questions about how consul-template works, its capabilities or anything other than a bug or feature request (use github's issue tracker for those), please see our community support resources. Community portal: https://discuss.hashicorp.com/tags/c/consul/29/consul-template Other resources: https://www.consul.io/community.html Additionally, for issues and pull requests, we'll be using the :+1: reactions as a rough voting system to help gauge community priorities. So please add :+1: to any issue or pull request you'd like to see worked on. Thanks. Installation • Download a pre-compiled, released version from the [Consul Template releases page][releases]. • Extract the binary using or . • Move the binary into . To compile from source, please see the instructions in the contributing section. Quick Example This short example assumes Consul is installed locally. • Start a Consul cluster in dev mode: • Author a template to query the kv store: • Start Consul Template: • Write data to the key in Consul: • Observe Consul Template has written the file : For more examples and use cases, please see the [examples folder][examples] in this repository. Learn Guides In addition to these [examples][examples], HashiCorp has published guides and official documentation to help walk through a few common use cases for Consul Template. • Consul KV • Consul Catalog • Vault Agent Templates • Vault Secrets • Nomad Native Service Discovery Configuration Configuration documentation has been moved to docs/configuration.md. Reload Configuration and Templates While there are multiple ways to run Consul Template, the most common pattern is to run Consul Template as a system service. When Consul Template first starts, it reads any configuration files and templates from disk and loads them into memory. From that point forward, changes to the files on disk do not propagate to running process without a reload. The reason for this behavior is simple and aligns with other tools like haproxy. A user may want to perform pre-flight validation checks on the configuration or templates before loading them into the process. Additionally, a user may want to update configuration and templates simultaneously. Having Consul Template automatically watch and reload those files on changes is both operationally dangerous and against some of the paradigms of modern infrastructure. Instead, Consul Template listens for the syscall to trigger a configuration reload. If you update configuration or templates, simply send to the running Consul Template process and Consul Template will reload all the configurations and templates from disk. Templating Language Templating Language documentation has been moved to docs/templating-language.md. Caveats Docker Image Use The Alpine Docker image is configured to support an external volume to render shared templates to. If mounted you will need to make sure that the consul-template user in the docker image has write permissions to the directory. Also if you build your own image using these you need to be sure you have the permissions correct. **The consul-template user in docker has a UID of 100 and a GID of 1000.** This effects the in image directories /consul-template/config, used to add configuration when using this as a parent image, and /consul-template/data, exported as a VOLUME as a location to render shared results. Previously the image initially ran as root in order to ensure the permissions allowed it. But this ran against docker best practices and security policies. If you build your own image based on ours you can override these values with parameters. Dots in Service Names Using dots in service names will conflict with the use of dots for TAG delineation in the template. Dots already interfere with using DNS for service names, so we recommend avoiding dots wherever possible. Termination on Error By default Consul Template is highly fault-tolerant. If Consul is unreachable or a template changes, Consul Template will happily continue running. The only exception to this rule is if the optional exits non-zero. In this case, Consul Template will also exit non-zero. The reason for this decision is so the user can easily configure something like Upstart or God to manage Consul Template as a service. If you want Consul Template to continue watching for changes, even if the optional command argument fails, you can append to your command. Note that is a "shell-ism", not a built-in function. You will also need to run your command under a shell: In this example, even if the Nginx restart command returns non-zero, the overall func…