forked from hashicorp/consul-template
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.md
2769 lines (2063 loc) · 82.6 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Consul Template
[![CircleCI](https://circleci.com/gh/hashicorp/consul-template.svg?style=svg)](https://circleci.com/gh/hashicorp/consul-template)
[![Go Documentation](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://godoc.org/github.com/hashicorp/consul-template)
This project provides a convenient way to populate values from [Consul][consul]
into the file system using the `consul-template` daemon.
The daemon `consul-template` queries a [Consul][consul] or [Vault][vault]
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 master branch of Consul Template. It may contain unreleased features or different APIs than the most recently released version.**
**Please see the [Git tag](https://github.com/hashicorp/consul-template/releases) that corresponds to your version of Consul Template for the proper documentation.**
---
## Table of Contents
- [Community Support](#community-support)
- [Installation](#installation)
- [Quick Example](#quick-example)
- [Usage](#usage)
- [Command Line Flags](#command-line-flags)
- [Configuration File Format](#configuration-file-format)
- [Templating Language](#templating-language)
- [API Functions](#api-functions)
- [caLeaf](#caleaf)
- [caRoot](#caroot)
- [connect](#connect)
- [datacenters](#datacenters)
- [file](#file)
- [key](#key)
- [keyExists](#keyexists)
- [keyOrDefault](#keyordefault)
- [ls](#ls)
- [safeLs](#safels)
- [node](#node)
- [nodes](#nodes)
- [secret](#secret)
- [secrets](#secrets)
- [service](#service)
- [services](#services)
- [tree](#tree)
- [safeTree](#safetree)
- [Scratch](#scratch)
- [scratch.Key](#scratchkey)
- [scratch.Get](#scratchget)
- [scratch.Set](#scratchset)
- [scratch.SetX](#scratchsetx)
- [scratch.MapSet](#scratchmapset)
- [scratch.MapSetX](#scratchmapsetx)
- [scratch.MapValues](#scratchmapvalues)
- [Helper Functions](#helper-functions)
- [base64Decode](#base64decode)
- [base64Encode](#base64encode)
- [base64URLDecode](#base64urldecode)
- [base64URLEncode](#base64urlencode)
- [byKey](#bykey)
- [byTag](#bytag)
- [byMeta](#bymeta)
- [contains](#contains)
- [containsAll](#containsall)
- [containsAny](#containsany)
- [containsNone](#containsnone)
- [containsNotAll](#containsnotall)
- [env](#env)
- [executeTemplate](#executetemplate)
- [explode](#explode)
- [explodeMap](#explodemap)
- [indent](#indent)
- [in](#in)
- [loop](#loop)
- [join](#join)
- [trimSpace](#trimspace)
- [parseBool](#parsebool)
- [parseFloat](#parsefloat)
- [parseInt](#parseint)
- [parseJSON](#parsejson)
- [parseUint](#parseuint)
- [parseYAML](#parseyaml)
- [plugin](#plugin)
- [regexMatch](#regexmatch)
- [regexReplaceAll](#regexreplaceall)
- [replaceAll](#replaceall)
- [sha256Hex](#sha256hex)
- [split](#split)
- [timestamp](#timestamp)
- [toJSON](#tojson)
- [toJSONPretty](#tojsonpretty)
- [toLower](#tolower)
- [toTitle](#totitle)
- [toTOML](#totoml)
- [toUpper](#toupper)
- [toYAML](#toyaml)
- [sockaddr](#sockaddr)
- [Math Functions](#math-functions)
- [add](#add)
- [subtract](#subtract)
- [multiply](#multiply)
- [divide](#divide)
- [modulo](#modulo)
- [minimum](#minimum)
- [maximum](#maximum)
- [Plugins](#plugins)
- [Authoring Plugins](#authoring-plugins)
- [Important Notes](#important-notes)
- [Caveats](#caveats)
- [Docker Image Use](#docker-image-use)
- [Dots in Service Names](#dots-in-service-names)
- [Once Mode](#once-mode)
- [Exec Mode](#exec-mode)
- [De-Duplication Mode](#de-duplication-mode)
- [Termination on Error](#termination-on-error)
- [Commands](#commands)
- [Environment](#environment)
- [Multiple Commands](#multiple-commands)
- [Multi-phase Execution](#multi-phase-execution)
- [Running and Process Lifecycle](#running-and-process-lifecycle)
- [Debugging](#debugging)
- [Telemetry](#telemetry)
- [FAQ](#faq)
- [Contributing](#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/c/consul
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
1. Download a pre-compiled, released version from the [Consul Template releases page][releases].
1. Extract the binary using `unzip` or `tar`.
1. Move the binary into `$PATH`.
To compile from source, please see the instructions in the
[contributing section](#contributing).
## Quick Example
This short example assumes Consul is installed locally.
1. Start a Consul cluster in dev mode:
```shell
$ consul agent -dev
```
1. Author a template `in.tpl` to query the kv store:
```liquid
{{ key "foo" }}
```
1. Start Consul Template:
```shell
$ consul-template -template "in.tpl:out.txt" -once
```
1. Write data to the key in Consul:
```shell
$ consul kv put foo bar
```
1. Observe Consul Template has written the file `out.txt`:
```shell
$ cat out.txt
bar
```
For more examples and use cases, please see the [examples folder][examples] in
this repository.
## Usage
For the full list of options:
```shell
$ consul-template -h
```
### Command Line Flags
The CLI interface supports all options in the configuration file and vice-versa. Here are a few examples of common integrations on the command line.
Render the template on disk at `/tmp/template.ctmpl` to `/tmp/result`:
```shell
$ consul-template \
-template "/tmp/template.ctmpl:/tmp/result"
```
Render multiple templates in the same process. The optional third argument to
the template is a command that will execute each time the template changes.
```shell
$ consul-template \
-template "/tmp/nginx.ctmpl:/var/nginx/nginx.conf:nginx -s reload" \
-template "/tmp/redis.ctmpl:/var/redis/redis.conf:service redis restart" \
-template "/tmp/haproxy.ctmpl:/var/haproxy/haproxy.conf"
```
Render a template using a custom Consul and Vault address:
```shell
$ consul-template \
-consul-addr "10.4.4.6:8500" \
-vault-addr "https://10.5.32.5:8200"
```
Render all templates and then spawn and monitor a child process as a supervisor:
```shell
$ consul-template \
-template "/tmp/in.ctmpl:/tmp/result" \
-exec "/sbin/my-server"
```
For more information on supervising, please see the
[Consul Template Exec Mode documentation](#exec-mode).
### Configuration File Format
Configuration files are written in the [HashiCorp Configuration Language][hcl].
By proxy, this means the configuration is also JSON compatible.
```hcl
# This denotes the start of the configuration section for Consul. All values
# contained in this section pertain to Consul.
consul {
# This block specifies the basic authentication information to pass with the
# request. For more information on authentication, please see the Consul
# documentation.
auth {
enabled = true
username = "test"
password = "test"
}
# This is the address of the Consul agent. By default, this is
# 127.0.0.1:8500, which is the default bind and port for a local Consul
# agent. It is not recommended that you communicate directly with a Consul
# server, and instead communicate with the local Consul agent. There are many
# reasons for this, most importantly the Consul agent is able to multiplex
# connections to the Consul server and reduce the number of open HTTP
# connections. Additionally, it provides a "well-known" IP address for which
# clients can connect.
address = "127.0.0.1:8500"
# This is a Consul Enterprise namespace to use for reading/writing. This can
# also be set via the CONSUL_NAMESPACE environment variable.
# BETA: this is to be considered a beta feature as it has had limited testing
namespace = "foo"
# This is the ACL token to use when connecting to Consul. If you did not
# enable ACLs on your Consul cluster, you do not need to set this option.
#
# This option is also available via the environment variable CONSUL_TOKEN.
token = "abcd1234"
# This controls the retry behavior when an error is returned from Consul.
# Consul Template 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.
retry {
# This enabled retries. Retries are enabled by default, so this is
# redundant.
enabled = true
# 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.
attempts = 12
# 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.
backoff = "250ms"
# 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, ...
max_backoff = "1m"
}
# This block configures the SSL options for connecting to the Consul server.
ssl {
# This enables SSL. Specifying any option for SSL will also enable it.
enabled = true
# This enables SSL peer verification. The default value is "true", which
# will check the global CA chain to make sure the given certificates are
# valid. If you are using a self-signed certificate that you have not added
# to the CA chain, you may want to disable SSL verification. However, please
# understand this is a potential security vulnerability.
verify = false
# This is the path to the certificate to use to authenticate. If just a
# certificate is provided, it is assumed to contain both the certificate and
# the key to convert to an X509 certificate. If both the certificate and
# key are specified, Consul Template will automatically combine them into an
# X509 certificate for you.
cert = "/path/to/client/cert"
key = "/path/to/client/key"
# This is the path to the certificate authority to use as a CA. This is
# useful for self-signed certificates or for organizations using their own
# internal certificate authority.
ca_cert = "/path/to/ca"
# This is the path to a directory of PEM-encoded CA cert files. If both
# `ca_cert` and `ca_path` is specified, `ca_cert` is preferred.
ca_path = "path/to/certs/"
# This sets the SNI server name to use for validation.
server_name = "my-server.com"
}
}
# This is the signal to listen for to trigger a reload event. The default
# value is shown below. Setting this value to the empty string will cause CT
# to not listen for any reload signals.
reload_signal = "SIGHUP"
# This is the signal to listen for to trigger a graceful stop. The default
# value is shown below. Setting this value to the empty string will cause CT
# to not listen for any graceful stop signals.
kill_signal = "SIGINT"
# This is the maximum interval to allow "stale" data. By default, only the
# Consul leader will respond to queries; any requests to a follower will
# forward to the leader. In large clusters with many requests, this is not as
# scalable, so this option allows any follower to respond to a query, so long
# as the last-replicated data is within these bounds. Higher values result in
# less cluster load, but are more likely to have outdated data.
max_stale = "10m"
# This is amount of time in seconds to do a blocking query for.
# Many endpoints in Consul support a feature known as "blocking queries".
# A blocking query is used to wait for a potential change using long polling.
block_query_wait = "60s"
# This is the log level. If you find a bug in Consul Template, please enable
# debug logs so we can help identify the issue. This is also available as a
# command line flag.
log_level = "warn"
# This is the path to store a PID file which will contain the process ID of the
# Consul Template process. This is useful if you plan to send custom signals
# to the process.
pid_file = "/path/to/pid"
# This is the quiescence timers; it defines the minimum and maximum amount of
# time to wait for the cluster to reach a consistent state before rendering a
# template. This is useful to enable in systems that have a lot of flapping,
# because it will reduce the the number of times a template is rendered.
wait {
min = "5s"
max = "10s"
}
# This denotes the start of the configuration section for Vault. All values
# contained in this section pertain to Vault.
vault {
# This is the address of the Vault leader. The protocol (http(s)) portion
# of the address is required.
address = "https://vault.service.consul:8200"
# This is a Vault Enterprise namespace to use for reading/writing secrets.
#
# This value can also be specified via the environment variable VAULT_NAMESPACE.
namespace = "foo"
# This is the token to use when communicating with the Vault server.
# Like other tools that integrate with Vault, Consul Template makes the
# assumption that you provide it with a Vault token; it does not have the
# incorporated logic to generate tokens via Vault's auth methods.
#
# This value can also be specified via the environment variable VAULT_TOKEN.
# When using a token from Vault Agent, the vault_agent_token_file setting
# should be used instead, as that will take precedence over this field.
token = "abcd1234"
# This tells Consul Template to load the Vault token from the contents of a file.
# If this field is specified:
# - by default Consul Template will not try to renew the Vault token, if you want it
# to renew you will need to specify renew_token = true as below.
# - Consul Template will periodically stat the file and update the token if it has
# changed.
# vault_agent_token_file = "/tmp/vault/agent/token"
# This tells Consul Template that the provided token is actually a wrapped
# token that should be unwrapped using Vault's cubbyhole response wrapping
# before being used. Please see Vault's cubbyhole response wrapping
# documentation for more information.
unwrap_token = true
# This option tells Consul Template to automatically renew the Vault token
# given. If you are unfamiliar with Vault's architecture, Vault requires
# tokens be renewed at some regular interval or they will be revoked. Consul
# Template will automatically renew the token at half the lease duration of
# the token. The default value is true, but this option can be disabled if
# you want to renew the Vault token using an out-of-band process.
#
# Note that secrets specified in a template (using {{secret}} for example)
# are always renewed, even if this option is set to false. This option only
# applies to the top-level Vault token itself.
renew_token = true
# This section details the retry options for connecting to Vault. Please see
# the retry options in the Consul section for more information (they are the
# same).
retry {
# ...
}
# This section details the SSL options for connecting to the Vault server.
# Please see the SSL options in the Consul section for more information (they
# are the same).
ssl {
# ...
}
}
# This block defines the configuration for connecting to a syslog server for
# logging.
syslog {
# This enables syslog logging. Specifying any other option also enables
# syslog logging.
enabled = true
# This is the name of the syslog facility to log to.
facility = "LOCAL5"
}
# This block defines the configuration for de-duplication mode. Please see the
# de-duplication mode documentation later in the README for more information
# on how de-duplication mode operates.
deduplicate {
# This enables de-duplication mode. Specifying any other options also enables
# de-duplication mode.
enabled = true
# This is the prefix to the path in Consul's KV store where de-duplication
# templates will be pre-rendered and stored.
prefix = "consul-template/dedup/"
}
# This block defines the configuration for exec mode. Please see the exec mode
# documentation at the bottom of this README for more information on how exec
# mode operates and the caveats of this mode.
exec {
# This is the command to exec as a child process. There can be only one
# command per Consul Template process.
command = "/usr/bin/app"
# This is a random splay to wait before killing the command. The default
# value is 0 (no wait), but large clusters should consider setting a splay
# value to prevent all child processes from reloading at the same time when
# data changes occur. When this value is set to non-zero, Consul Template
# will wait a random period of time up to the splay value before reloading
# or killing the child process. This can be used to prevent the thundering
# herd problem on applications that do not gracefully reload.
splay = "5s"
env {
# This specifies if the child process should not inherit the parent
# process's environment. By default, the child will have full access to the
# environment variables of the parent. Setting this to true will send only
# the values specified in `custom_env` to the child process.
pristine = false
# This specifies additional custom environment variables in the form shown
# below to inject into the child's runtime environment. If a custom
# environment variable shares its name with a system environment variable,
# the custom environment variable takes precedence. Even if pristine,
# whitelist, or blacklist is specified, all values in this option
# are given to the child process.
custom = ["PATH=$PATH:/etc/myapp/bin"]
# This specifies a list of environment variables to exclusively include in
# the list of environment variables exposed to the child process. If
# specified, only those environment variables matching the given patterns
# are exposed to the child process. These strings are matched using Go's
# glob function, so wildcards are permitted.
whitelist = ["CONSUL_*"]
# This specifies a list of environment variables to exclusively prohibit in
# the list of environment variables exposed to the child process. If
# specified, any environment variables matching the given patterns will not
# be exposed to the child process, even if they are whitelisted. The values
# in this option take precedence over the values in the whitelist.
# These strings are matched using Go's glob function, so wildcards are
# permitted.
blacklist = ["VAULT_*"]
}
# This defines the signal that will be sent to the child process when a
# change occurs in a watched template. The signal will only be sent after the
# process is started, and the process will only be started after all
# dependent templates have been rendered at least once. The default value is
# nil, which tells Consul Template to stop the child process and spawn a new
# one instead of sending it a signal. This is useful for legacy applications
# or applications that cannot properly reload their configuration without a
# full reload.
reload_signal = ""
# This defines the signal sent to the child process when Consul Template is
# gracefully shutting down. The application should begin a graceful cleanup.
# If the application does not terminate before the `kill_timeout`, it will
# be terminated (effectively "kill -9"). The default value is "SIGINT".
kill_signal = "SIGINT"
# This defines the amount of time to wait for the child process to gracefully
# terminate when Consul Template exits. After this specified time, the child
# process will be force-killed (effectively "kill -9"). The default value is
# "30s".
kill_timeout = "2s"
}
# This block defines the configuration for a template. Unlike other blocks,
# this block may be specified multiple times to configure multiple templates.
# It is also possible to configure templates via the CLI directly.
template {
# This is the source file on disk to use as the input template. This is often
# called the "Consul Template template". This option is required if not using
# the `contents` option.
source = "/path/on/disk/to/template.ctmpl"
# This is the destination path on disk where the source template will render.
# If the parent directories do not exist, Consul Template will attempt to
# create them, unless create_dest_dirs is false.
destination = "/path/on/disk/where/template/will/render.txt"
# This options tells Consul Template to create the parent directories of the
# destination path if they do not exist. The default value is true.
create_dest_dirs = true
# 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.
contents = "{{ keyOrDefault \"service/redis/maxconns@east-aws\" \"5\" }}"
# 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.
# Consul Template is not a replacement for a process monitor or init system.
# Please see the [Command](#command) section below for more.
command = "restart service foo"
# This is the maximum amount of time to wait for the optional command to
# return. If you set the timeout to 0s the command is run in the background
# without monitoring it for errors. If also using Once, consul-template can
# exit before the command is finished. Default is 30s.
command_timeout = "60s"
# Exit with an error when accessing a struct or map field/key that does not
# exist. The default behavior will print "<no value>" when accessing a field
# that does not exist. It is highly recommended you set this to "true" when
# retrieving secrets from Vault.
error_on_missing_key = false
# This is the permission to render the file. If this option is left
# unspecified, Consul Template 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.
perms = 0600
# 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.
backup = true
# These are the delimiters to use in the template. The default is "{{" and
# "}}", but for some templates, it may be easier to use a different delimiter
# that does not conflict with the output file itself.
left_delimiter = "{{"
right_delimiter = "}}"
# These are functions that are not permitted in the template. If a template
# includes one of these functions, it will exit with an error.
function_blacklist = []
# 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.
sandbox_path = ""
# This is the `minimum(:maximum)` to wait before rendering a new template to
# disk and triggering a command, separated by a colon (`:`). If the optional
# maximum value is omitted, it is assumed to be 4x the required minimum value.
# This is a numeric time with a unit suffix ("5s"). There is no default value.
# The wait value for a template takes precedence over any globally-configured
# wait.
wait {
min = "2s"
max = "10s"
}
# These are example configurations for monitoring Consul Template metrics.
# This block is an HCL mapping to OpenTelemetry configurations for
# various exporters. Configuring telemetry is only supported in
# configuration files and not as CLI flags. Only one metric provider can
# be used at a given time. More details on the metrics collected can be found
# in the Telemetry section.
telemetry {
stdout {
reporting_interval = "60s"
pretty_print = false
do_not_print_time = false
}
dogstatsd {
// address describes the destination for exporting dogstatsd data.
// e.g., udp://host:port tcp://host:port unix:///socket/path
address = "udp://127.0.0.1:8125"
reporting_interval = "60s"
}
prometheus {
reporting_interval = "60s"
port = 8888
}
}
}
```
Note that not all fields are required. If you are not retrieving secrets from
Vault, you do not need to specify a Vault configuration section. Similarly, if
you are not logging to syslog, you do not need to specify a syslog
configuration.
For additional security, tokens may also be read from the environment using the
`CONSUL_TOKEN` or `VAULT_TOKEN` environment variables respectively. It is highly
recommended that you do not put your tokens in plain-text in a configuration
file.
Instruct Consul Template to use a configuration file with the `-config` flag:
```shell
$ consul-template -config "/my/config.hcl"
```
This argument may be specified multiple times to load multiple configuration
files. The right-most configuration takes the highest precedence. If the path to
a directory is provided (as opposed to the path to a file), all of the files in
the given directory will be merged in
[lexical order](http://golang.org/pkg/path/filepath/#Walk), recursively. Please
note that symbolic links are _not_ followed.
**Commands specified on the CLI take precedence over a config file!**
### Templating Language
Consul Template parses files authored in the [Go Template][text-template]
format. If you are not familiar with the syntax, please read Go's documentation
and examples. In addition to the Go-provided template functions, Consul Template
provides the following functions:
#### API Functions
API functions interact with remote API calls, communicating with external
services like [Consul][consul] and [Vault][vault].
##### `caLeaf`
Query [Consul][consul] for the leaf certificate representing a single service.
```liquid
{{ caLeaf "<NAME>" }}
```
For example:
```liquid
{{ with caLeaf "proxy" }}{{ .CertPEM }}{{ end }}
```
renders
```text
-----BEGIN CERTIFICATE-----
MIICizCCAjGgAwIBAgIBCDAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg
...
lXcQzfKlIYeFWvcAv4cA4W258gTtqaFRDRJ2i720eQ==
-----END CERTIFICATE-----
```
The two most useful fields are `.CertPEM` and `.PrivateKeyPEM`. For a complete
list of available fields, see consul's documentation on
[LeafCert](https://godoc.org/github.com/hashicorp/consul/api#LeafCert).
##### `caRoot`
Query [Consul][consul] for all [connect][connect] trusted certificate authority
(CA) root certificates.
```liquid
{{ caRoots }}
```
For example:
```liquid
{{ range caRoots }}{{ .RootCertPEM }}{{ end }}
```
renders
```text
-----BEGIN CERTIFICATE-----
MIICWDCCAf+gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg
...
bcA+Su3r8qSRppTlc6D0UOYOWc1ykQKQOK7mIg==
-----END CERTIFICATE-----
```
The most useful field is `.RootCertPEM`. For a complete list of available
fields, see consul's documentation on
[CARootList](https://godoc.org/github.com/hashicorp/consul/api#CARootList).
##### `connect`
Query [Consul][consul] for [connect][connect]-capable services based on their
health.
```liquid
{{ connect "<TAG>.<NAME>@<DATACENTER>~<NEAR>|<FILTER>" }}
```
Syntax is exactly the same as for the [service](#service) function below.
```liquid
{{ range connect "web" }}
server {{ .Name }} {{ .Address }}:{{ .Port }}{{ end }}
```
renders the IP addresses of all _healthy_ nodes with a logical
[connect][connect]-capable service named "web":
```text
server web01 10.5.2.45:21000
server web02 10.2.6.61:21000
```
##### `datacenters`
Query [Consul][consul] for all datacenters in its catalog.
```liquid
{{ datacenters }}
```
For example:
```liquid
{{ range datacenters }}
{{ . }}{{ end }}
```
renders
```text
dc1
dc2
```
An optional boolean can be specified which instructs Consul Template to ignore
datacenters which are inaccessible or do not have a current leader. Enabling
this option requires an O(N+1) operation and therefore is not recommended in
environments where performance is a factor.
```liquid
// Ignores datacenters which are inaccessible
{{ datacenters true }}
```
##### `file`
Read and output the contents of a local file on disk. If the file cannot be
read, an error will occur. When the file changes, Consul Template will pick up
the change and re-render the template.
```liquid
{{ file "<PATH>" }}
```
For example:
```liquid
{{ file "/path/to/my/file" }}
```
renders
```text
file contents
```
This does not process nested templates. See
[`executeTemplate`](#executeTemplate) for a way to render nested templates.
##### `key`
Query [Consul][consul] for the value at the given key path. If the key does not
exist, Consul Template will block rendering until the key is present. To avoid
blocking, use `keyOrDefault` or `keyExists`.
```liquid
{{ key "<PATH>@<DATACENTER>" }}
```
The `<DATACENTER>` attribute is optional; if omitted, the local datacenter is
used.
For example:
```liquid
{{ key "service/redis/maxconns" }}
```
renders
```text
15
```
##### `keyExists`
Query [Consul][consul] for the value at the given key path. If the key exists,
this will return true, false otherwise. Unlike `key`, this function will not
block if the key does not exist. This is useful for controlling flow.
```liquid
{{ keyExists "<PATH>@<DATACENTER>" }}
```
The `<DATACENTER>` attribute is optional; if omitted, the local datacenter is
used.
For example:
```liquid
{{ if keyExists "app/beta_active" }}
# ...
{{ else }}
# ...
{{ end }}
```
##### `keyOrDefault`
Query [Consul][consul] for the value at the given key path. If the key does not
exist, the default value will be used instead. Unlike `key`, this function will
not block if the key does not exist.
```liquid
{{ keyOrDefault "<PATH>@<DATACENTER>" "<DEFAULT>" }}
```
The `<DATACENTER>` attribute is optional; if omitted, the local datacenter is
used.
For example:
```liquid
{{ keyOrDefault "service/redis/maxconns" "5" }}
```
renders
```text
5
```
Note that Consul Template uses a [multi-phase
execution](#multi-phase-execution). During the first phase of evaluation, Consul
Template will have no data from Consul and thus will _always_ fall back to the
default value. Subsequent reads from Consul will pull in the real value from
Consul (if the key exists) on the next template pass. This is important because
it means that Consul Template will never "block" the rendering of a template due
to a missing key from a `keyOrDefault`. Even if the key exists, if Consul has
not yet returned data for the key, the default value will be used instead.
##### `ls`
Query [Consul][consul] for all top-level kv pairs at the given key path.
```liquid
{{ ls "<PATH>@<DATACENTER>" }}
```
The `<DATACENTER>` attribute is optional; if omitted, the local datacenter is
used.
For example:
```liquid
{{ range ls "service/redis" }}
{{ .Key }}:{{ .Value }}{{ end }}
```
renders
```text
maxconns:15
minconns:5
```
##### `safeLs`
Same as [ls](#ls), but refuse to render template, if the KV prefix query return blank/empty data.
This is especially useful, for rendering mission critical files, that are being populated by consul-template.
For example:
```text
/root/.ssh/authorized_keys
/etc/sysconfig/iptables
```
Using `safeLs` on empty prefixes will result in template output not being rendered at all.
To learn how `safeLs` was born see [CT-1131](https://github.com/hashicorp/consul-template/issues/1131) [C-3975](https://github.com/hashicorp/consul/issues/3975) and [CR-82](https://github.com/hashicorp/consul-replicate/issues/82).
##### `node`
Query [Consul][consul] for a node in the catalog.
```liquid
{{node "<NAME>@<DATACENTER>"}}
```
The `<NAME>` attribute is optional; if omitted, the local agent node is used.
The `<DATACENTER>` attribute is optional; if omitted, the local datacenter is
used.
For example:
```liquid
{{ with node }}
{{ .Node.Address }}{{ end }}
```
renders
```text
10.5.2.6
```
To query a different node:
```liquid
{{ with node "node1@dc2" }}
{{ .Node.Address }}{{ end }}
```
renders
```text
10.4.2.6
```
To access map data such as `TaggedAddresses` or `Meta`, use
[Go's text/template][text-template] map indexing.
##### `nodes`
Query [Consul][consul] for all nodes in the catalog.
```liquid