mirror of https://github.com/status-im/consul.git
Adding the new Consul Template Guide. (#4947)
* Adding the new Consul Template Guide. * Update website/source/docs/guides/consul-template.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/consul-template.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/consul-template.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/consul-template.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Making updates based on Pauls feedback. * Update website/source/docs/guides/consul-template.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/consul-template.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/consul-template.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Couple more updates based on Pauls feedback. * updated the intro to include how template can replace api use * updated the address * Adding minikube guide to the index page.
This commit is contained in:
kaitlincarter-hc
GitHub
parent
c5ae9caa28
commit
71a0aa5049
|
|
@ -0,0 +1,188 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Consul Template"
|
||||
sidebar_current: "docs-guides-consul-template"
|
||||
description: |-
|
||||
Consul template provides a programmatic method for rendering configuration files from Consul data.
|
||||
---
|
||||
|
||||
# Consul Template
|
||||
|
||||
The Consul template tool provides a programmatic method
|
||||
for rendering configuration files from a variety of locations,
|
||||
including Consul KV. It is an ideal option for replacing complicated API
|
||||
queries that often require custom formatting.
|
||||
The template tool is based on Go templates and shares many
|
||||
of the same attributes.
|
||||
|
||||
Consul template is a useful tool with several uses, we will focus on two
|
||||
of it's use cases.
|
||||
|
||||
1. *Update configuration files*. The Consul template tool can be used
|
||||
to update service configuration files. A common use case is managing load
|
||||
balancer configuration files that need to be updated regularly in a dynamic
|
||||
infrastructure on machines many not be able to directly connect to the Consul cluster.
|
||||
|
||||
1. *Discover data about the Consul cluster and service*. It is possible to collect
|
||||
information about the services in your Consul cluster. For example, you could
|
||||
collect a list of all services running on the cluster or you could discover all
|
||||
service addresses for the Redis service. Note, this use case has limited
|
||||
scope for production.
|
||||
|
||||
In this guide we will briefly discuss how `consul-template` works,
|
||||
how to install it, and two use cases.
|
||||
|
||||
Before completing this guide, we assume some familiarity with
|
||||
[Consul KV](https://learn.hashicorp.com/consul/getting-started/kv.html)
|
||||
and [Go templates](https://golang.org/pkg/text/template/).
|
||||
|
||||
## Introduction to Consul Template
|
||||
|
||||
Consul template is a simple, yet powerful tool. When initiated, it
|
||||
reads one or more template files and queries Consul for all
|
||||
data needed to render them. Typically, you run `consul-template` as a
|
||||
daemon which will fetch the initial values and then continue to watch
|
||||
for updates, re-rendering the template whenever there are relevant changes in
|
||||
the cluster. You can alternatively use the `-once` flag to fetch and render
|
||||
the template once which is useful for testing and
|
||||
setup scripts that are triggered by some other automation for example a
|
||||
provisioning tool. Finally, the template can also run arbitrary commands after the update
|
||||
process completes. For example, it can send the HUP signal to the
|
||||
load balancer service after a configuration change has been made.
|
||||
|
||||
The Consul template tool is flexible, it can fit into many
|
||||
different environments and workflows. Depending on the use-case, you
|
||||
may have a single `consul-template` instance on a handful of hosts
|
||||
or may need to run several instances on every host. Each `consul-template`
|
||||
process can manage multiple unrelated files though and will de-duplicate
|
||||
the fetches as needed if those files share data dependencies so it can
|
||||
reduce the load on Consul servers to share where possible.
|
||||
|
||||
## Install Consul Template
|
||||
|
||||
For this guide, we are using a local Consul agent in development
|
||||
mode which can be started with `consul agent -dev`. To quickly set
|
||||
up a local Consul agent, refer to the getting started [guide](https://learn.hashicorp.com/consul/getting-started/install). The
|
||||
Consul agent must be running to complete all of the following
|
||||
steps.
|
||||
|
||||
The Consul template tool is not included with the Consul binary and will
|
||||
need to be installed separately. It can be installed from a precompiled
|
||||
binary or compiled from source. We will be installing the precompiled binary.
|
||||
|
||||
First, download the binary from the [Consul Template releases page](https://releases.hashicorp.com/consul-template/).
|
||||
|
||||
```sh
|
||||
curl -O https://releases.hashicorp.com/consul-template/0.19.5/consul-template<_version_OS>.tgz
|
||||
```
|
||||
|
||||
Next, extract the binary and move it into you `$PATH`.
|
||||
|
||||
```sh
|
||||
tar -zxf consul-template<_version_OS>.tgz
|
||||
```
|
||||
|
||||
To compile from source, please see the instructions in the
|
||||
[contributing section in Github](https://github.com/hashicorp/consul-template#contributing).
|
||||
|
||||
## Use Case: Consul KV
|
||||
|
||||
In this first use case example, we will render a template that pulls the HashiCorp address
|
||||
from Consul KV. To do this we will create a simple template that contains the HashiCorp
|
||||
address, run `consul-template`, add a value to Consul KV for HashiCorp's address, and
|
||||
finally view the rendered file.
|
||||
|
||||
First, we will need to create a template file `find_address.tpl` to query
|
||||
Consul's KV store:
|
||||
|
||||
```liquid
|
||||
{{ key "/hashicorp/street_address" }}
|
||||
```
|
||||
|
||||
Next, we will run `consul-template` specifying both
|
||||
the template to use and the file to update.
|
||||
|
||||
```shell
|
||||
$ consul-template -template "find_address.tpl:hashicorp_address.txt"
|
||||
```
|
||||
|
||||
The `consul-template` process will continue to run until you kill it with `CRTL+c`.
|
||||
For now, we will leave it running.
|
||||
|
||||
Finally, open a new terminal so we can write data to the key in Consul using the command
|
||||
line interface.
|
||||
|
||||
```shell
|
||||
$ consul kv put hashicorp/street_address "101 2nd St"
|
||||
$ Success! Data written to: hashicorp/street_address
|
||||
```
|
||||
|
||||
We can ensure the data was written by viewing the `hashicorp_address.txt`
|
||||
file which will be located in the same directory where `consul-template`
|
||||
was run.
|
||||
|
||||
```shell
|
||||
$ cat hashicorp_address.txt
|
||||
101 2nd St
|
||||
```
|
||||
|
||||
If you update the key `hashicorp/street_address`, you can see the changes to the file
|
||||
immediately. Go ahead and try `consul kv put hashicorp/street_address "22b Baker ST"`.
|
||||
|
||||
You can see that this simple process can have powerful implications. For example, it is
|
||||
possible to use this same process for updating your [HAProxy load balancer
|
||||
configuration](https://github.com/hashicorp/consul-template/blob/master/examples/haproxy.md).
|
||||
|
||||
You can now kill the `consul-template` process with `CTRL+c`.
|
||||
|
||||
## Use Case: Discover All Services
|
||||
|
||||
In this use case example, we will discover all the services running in the Consul cluster.
|
||||
To follow along, you use the local development agent from the previous example.
|
||||
|
||||
First, we will need to create a new template `all-services.tpl` to query all services.
|
||||
|
||||
```liquid
|
||||
{{range services}}# {{.Name}}{{range service .Name}}
|
||||
{{.Address}}{{end}}
|
||||
|
||||
{{end}}
|
||||
```
|
||||
|
||||
Next, run Consul template specifying the template we just created and the `-once` flag.
|
||||
The `-once` flag will tell the process to run once and then quit.
|
||||
|
||||
```shell
|
||||
$ consul-template -template="all-services.tpl:all-services.txt" -once
|
||||
```
|
||||
|
||||
If you complete this on your local development agent, you should
|
||||
still see the `consul` service when viewing `all-services.txt`.
|
||||
|
||||
```text
|
||||
# consul
|
||||
127.0.0.7
|
||||
```
|
||||
On a development or production cluster, you would see a list of all the services.
|
||||
For example:
|
||||
|
||||
```text
|
||||
# consul
|
||||
104.131.121.232
|
||||
|
||||
# redis
|
||||
104.131.86.92
|
||||
104.131.109.224
|
||||
104.131.59.59
|
||||
|
||||
# web
|
||||
104.131.86.92
|
||||
104.131.109.224
|
||||
104.131.59.59
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
In this guide we learned how to set up and use the Consul template tool.
|
||||
To see additional examples, refer to the examples folder
|
||||
in [github](https://github.com/hashicorp/consul-template/tree/master/examples).
|
||||
|
|
@ -28,6 +28,8 @@ The following guides are available:
|
|||
|
||||
* [Consul with Containers](/docs/guides/consul-containers.html) - This guide describes critical aspects of operating a Consul cluster that's run inside containers.
|
||||
|
||||
* [Consul Template](/docs/guides/consul-template.html) - This guide covers the Consul template tool, which provides a programmatic method for populating values into the file system.
|
||||
|
||||
* [Creating Certificates](/docs/guides/creating-certificates.html) - This guide describes how to setup CA and certificates to secure a Consul cluster with TLS.
|
||||
|
||||
* [Deployment Guide](/docs/guides/deployment-guide.html) - This deployment guide covers the steps required to install and configure a single HashiCorp Consul cluster as defined in the Consul Reference Architecture.
|
||||
|
|
@ -42,6 +44,8 @@ The following guides are available:
|
|||
|
||||
* [Geo Failover](/docs/guides/geo-failover.html) - This guide covers using [prepared queries](/api/query.html) to implement geo failover for services.
|
||||
|
||||
* [Minikube with Consul](/docs/guides/minikube.html) - In this guide, you'll start a local Kubernetes cluster with minikube, install Consul,and then deploy two custom services.
|
||||
|
||||
* [Leader Election](/docs/guides/leader-election.html) - The goal of this guide is to cover how to build client-side leader election using Consul.
|
||||
|
||||
* [Monitoring Consul with Telegraf](/docs/guides/monitoring-telegraf.html) - This guide demonstrates how to setup Consul for monitoring with Telegraf.
|
||||
|
|
@ -58,4 +62,4 @@ The following guides are available:
|
|||
|
||||
* [Server Performance](/docs/guides/performance.html) - This guide covers minimum requirements for Consul servers as well as guidelines for running Consul servers in production.
|
||||
|
||||
* [Windows Service](/docs/guides/windows-guide.html) - This guide covers how to run Consul as a service on Windows.
|
||||
* [Windows Service](/docs/guides/windows-guide.html) - This guide covers how to run Consul as a service on Windows.
|
||||
|
|
|
|||
|
|
@ -402,6 +402,9 @@
|
|||
<li<%= sidebar_current("docs-guides-consul-containers") %>>
|
||||
<a href="/docs/guides/consul-containers.html">Consul with Containers</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-guides-consul-template") %>>
|
||||
<a href="/docs/guides/consul-template.html">Consul Template</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-guides-creating-certificates") %>>
|
||||
<a href="/docs/guides/creating-certificates.html">Creating Certificates</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue