Consul Template チートシート

Consul Template のドキュメントと Go Template のドキュメントの両方を往復するのに疲れたのでまとめました。

対応バージョン: 0.21.0

用語の整理

用語	内容
ドット (dot)	テンプレート実行中に特定のデータを指し示すカーソル。記法 . で参照できる。
アクション (action)	制御構造のこと
引数 (argument)	単純な値のこと
コマンド (command)	引数 or 関数 or メソッド
パイプライン (pipeline)	複数のコマンドを | で連結したもの。パイプで受け取った値は関数やメソッドの引数の末尾に追加される。
空の値 (empty)	false、0、nilポインタまたはインタフェース値、長さがゼロの配列、スライス、マップ、文字列

アクション

内容	記述例	備考
コメント	{{/* 任意のコメント */}}	複数行可
値の出力	{{パイプライン}}
if	{{if パイプライン}} T1 {{end}}
else	{{if パイプライン}} T1 {{else}} T0 {{end}}
else if	{{if パイプライン}} T1 {{else if パイプライン}} T0 {{end}}
ループ	{{range パイプライン}} T1 {{end}}
ループ	{{range パイプライン}} T1 {{else}} T0 {{end}}	パイプラインが空なら T0
テンプレート定義	{{define "名前"}} T1 {{end}}	Nested template definitions
テンプレート実行	{{template "名前"}}	ドットが nil にセットされる
テンプレート実行	{{template "名前" パイプライン}}	ドットがパイプラインの値にセットされる
テンプレート定義+実行	{{block "名前" パイプライン}} T1 {{end}}	以下の記述と同等: {{define "名前"}} T1 {{end}} {{template "名前" .}}
ドット設定	{{with パイプライン}} T1 {{end}}	パイプラインが空なら何もしない
ドット設定	{{with パイプライン}} T1 {{else}} T0 {{end}}	パイプラインが空なら T0
変数の初期化	$variable := パイプライン	任意のアクション内のパイプラインで使用可
range 内の変数の初期化	{{range $index, $element := パイプライン}}

パイプライン

内容	定義	記述例
パイプライン	コマンド コマンド | コマンド	{{"\"output\""}} {{"output" | printf "%q"}}
コマンド	引数 .メソッド名 [引数...] 関数名 [引数...]	"foo" .Method .Method "foo" "bar" "baz" functionName functionName "foo" "bar" "baz"

引数

内容	記述例	備考
値	true, false, "abc", 'a', '\t', 42, 0600, 0xBadFace, 72.40, 6.67428e-11, 6.67428e-11i	Goの文法における真偽値、文字列、文字、数値、浮動小数点数、虚数、複素数の定数
nil	nil
ドット	.
変数	$piOver2, $	ドルマークに続く英数字の文字列(なくてもよい)
フィールド	.Field, .Field1.Field2, .$x.Field1.Field2
マップのキー	.Key, .Field1.Key1.Field2.Key2, $x.key1.key2	キーは英数字(小文字始まりでも可)
引数なしのメソッド	.Method, .Field1.Key1.Method1.Field2.Key2.Method2, $x.Method1.Field
引数なしの関数	fun
グループ	(コマンド) print (.F1 arg1) (.F2 arg2), (.StructValuedMethod "arg").Field

関数

標準関数

関数名	内容	記述例	備考
and	論理積	and x y	xが真のときy、そうでなければx
call	最初の引数の関数に残りの引数をパラメータとして与えて実行した結果	.X.Y 1 2	Goで書くと dot.X.Y(1, 2)
html	HTML のエスケープ	html "foo & bar"
index	最初の引数を続く引数でインデックスした結果	index x 1 2 3	Goの文法では x[1][2][3]
js	JavaScript のエスケープ
len	引数の長さ
not	論理否定値
or	論理和	or x y	xが真のときx、そうでなければy
print	fmt.Sprint
printf	fmt.Sprintf
println	fmt.Sprintln
urlquery	URLエンコード
eq	==	eq 1 2
ne	!=	ne 1 2
lt	<	lt 1 2
le	<=	le 1 2
gt	>	gt 1 2
ge	>=	ge 1 2

Consul Template 関数

API Functions

関数名	内容	記述例	備考
datacenters	データセンターリストを返す	{{datacenters}}
file	ローカルファイルを読み込んで返す	{{file "/path/to/local/file"}}
key	KV の値を返す	{{key "service/redis/maxconns@east-aws"}} {{key "service/redis/maxconns"}}
keyExists	KV のキーがあるかどうか返す	{{ if keyExists "app/beta_active" }} # ... {{ else }} # ...<br>{{ end }}
keyOrDefault	Consul の KV の値を返す。キーがなければデフォルト値を返す	{{keyOrDefault "service/redis/maxconns@east-aws" "5"}}
ls	key-value ペアを返す	{{range ls "service/redis@east-aws"}}{{.Key}} {{.Value}}{{end}}
node	単一ノードの値を返す	{{node "node1"}} {{node}} {{node "node1" "@east-aws"}}	ノード名を省略すると自分自身のノード
nodes	全ノードのリストを返す	{{nodes}} {{nodes "@east-aws"}}
secret	Vaultの値(単一)を返す	{{with secret "secret/passwords"}} {{.Data.password}}{{end}}
secrets	Vaultの値(複数)を返す	{{range secrets "secret/"}} {{.}}{{end}}
service	サービスのリストを返す	{{service "release.web@east-aws"}} `{{service "web	any"}}<br>{{service "web
services	全サービスのリストを返す	{{services}} {{services "@east-aws"}}
tree	KV のツリーを返す	{{range tree "service/redis@east-aws"}} {{.Key}} {{.Value}}{{end}}	ネストしたキーは / で区切られる

Scratch

テンプレート内で使えるテンポラリな Key-Value ストア。

関数名	内容	記述例	備考
scratch.Key	キーの有無を返す	{{ scratch.Key "foo" }}
scratch.Get	値を返す	{{ scratch.Get "foo" }}
scratch.Set	値を設定 (上書きあり)	{{ scratch.Set "foo" "bar" }}
scratch.SetX	値を設定 (上書きなし)	{{ scratch.SetX "foo" "bar" }}
scratch.MapSet	マップに値を設定 (上書きあり)	{{ scratch.MapSet "vars" "foo" "bar" }}
scratch.MapSetX	マップに値を設定 (上書きなし)	{{ scratch.MapSetX "vars" "foo" "bar" }}
scratch.MapValues	マップの値をリストで返す	{{ scratch.MapValues "vars" }}

Helper Functions

関数名	内容	記述例	備考
base64Decode	BASE64 デコード	{{ base64Decode "aGVsbG8=" }}
base64Encode	BASE64 エンコード	{{ base64Encode "hello" }}
base64URLDecode	BASE64 デコード (URL セーフ)	{{ base64URLDecode "aGVsbG8=" }}
base64URLEncode	BASE64 エンコード (URL セーフ)	{{ base64Encode "hello" }}
byKey	tree 関数の返した値を第1階層のキーでグループ化	{{range $key, $pairs := tree "groups" | byKey}} {{$key}}: {{range $pair := $pairs}} {{.Key}}={{.Value}} {{end}}{{end}}
byTag	service, services 関数の返した値をタグでグループ化	{{range $tag, $services := service "web" | byTag}}{{$tag}} {{range $services}} server {{.Name}} {{.Address}}:{{.Port}} {{end}}{{end}}
contains	リストが引数に指定した値を含むかどうか	{{ if .Tags | contains "production" }} # ... {{ end }}
containsAll	リストが引数に指定したリストをすべて含むかどうか	{{ if containsAll $requiredTags .Tags }} # ... {{ end }}
containsAny	リストが引数に指定したリストを一つでも含むかどうか	{{ if containsAny $acceptableTags .Tags }} # ... {{ end }}
containsNone	リストが引数に指定したリストを全く含まないかどうか	{{ if containsNone $forbiddenTags .Tags }} # ... {{ end }}
env	環境変数を返す	{{env "CLUSTER_ID"}}
executeTemplate	定義したテンプレートを実行	{{ define "custom" }}my custom template{{ end }} This is my other template: {{ executeTemplate "custom" }} And I can call it multiple times: {{ executeTemplate "custom" }} Even with a new context: {{ executeTemplate "custom" 42 }} Or save it to a variable: {{ $var := executeTemplate "custom" }}
explode	tree, ls 関数の返した値をネストしたマップに変換する	{{ tree "config" | explode }}
in	値が引数に指定したリストに含まれるかどうか	{{ if in .Tags "production" }} # ... {{ end }}	contains 関数と引数の順番が逆
indent	インデント	{{ tree "foo"	explode
loop	指定回数繰り返す	{{range loop 5}} # Comment{{end}} {{range $i := loop 5 8}} stanza-{{$i}}{{end}}	loop a b だと a から b - 1 まで繰り返す
join	文字列リストを連結	{{$items | join ","}}
trimSpace	空白を削除	{{ file "/etc/ec2_version"| trimSpace }}
parseBool	文字列を boolean に変換	{{if key "feature/enabled" | parseBool}}{{end}}
parseFloat	文字列を float64 に変換	{{"1.2" | parseFloat}}
parseInt	文字列を int64 に変換	{{range $i := loop key "config/pool_size" | parseInt}} # ...{{end}}
parseJSON	JSON をパース	{{with $d := key "user/info" | parseJSON}}{{$d.name}}{{end}}
parseUint	文字列を uint64 に変換	{{"1" | parseUint}}
plugin	Consul Template plugin を実行	{{tree "foo" | explode | toJSON | plugin "my-plugin"}}	プラグインは外部コマンドとして実装できる。
regexMatch	正規表現マッチ	{{"foo.bar" | regexMatch "foo([.a-z]+)"}}
regexReplaceAll	正規表現で置換	{{"foo.bar" | regexReplaceAll "foo([.a-z]+)" "$1"}}
replaceAll	文字列置換	{{"foo.bar" | replaceAll "." "_"}}
split	文字列を分割	{{"foo\nbar\n" | split "\n"}}
timestamp	タイムスタンプを RFC3339 形式 (1970-01-01T00:00:00Z) の文字列で返す	{{timestamp}} {{timestamp "2006-01-02"}} {{timestamp "unix"}}	引数を指定すると、time.Format()のフォーマットで返す。unix とすると UNIX Timestamp (ただし文字列) で返す。
toJSON	tree, ls 関数の返した値を JSON 形式の文字列に変換	{{ tree "config" | explode | toJSON }}
toJSONPretty	tree, ls 関数の返した値をインデントされた JSON 形式の文字列に変換	{{ tree "config" | explode | toJSONPretty }}
toLower	小文字に変換	{{key "user/name" | toLower}}
toTitle	Titlecase に変換	{{key "user/name" | toTitle}}
toTOML	tree, ls 関数の返した値を TOML 形式の文字列に変換	{{ tree "config"	explode
toUpper	大文字に変換	{{key "user/name" | toUpper}}
toYAML	tree, ls 関数の返した値を YAML 形式の文字列に変換	{{ tree "config" | explode | toYAML }}

Math Functions

関数名	内容	記述例	備考
add	足し算	{{ add 1 2 }} → 3 {{ 1 | add 2 }} → 3
subtract	引き算	{{ subtract 2 5 }} → 3 {{ 5 | subtract 2 }} → 3	引数の順番に注意
multiply	掛け算	{{ multiply 2 2 }} → 4 {{ 2 | multiply 2 }} → 4
divide	割り算	{{ divide 2 10 }} → 5 {{ 10 | divide 2 }} → 5	引数の順番に注意
modulo	剰余	{{ modulo 2 5 }} → 1 {{ 5 | modulo 2 }}→ 1	引数の順番に注意

空白の制御

Go 1.6 / Consul Template 0.13.0 以降で利用可能。

• {{ の代わりに {{- を使うと直前の連続する空白が削除される
• }} の代わりに -}} を使うと直後の連続する空白が削除される
• 削除される空白は space, horizontal tab, carriage return, and newline
• {{-, -}} とテンプレート記述本体の間はスペースで区切る必要がある

記述例	出力
{{23 -}} < {{- 45}}	23<45

参照

• Go Template (日本語訳)
• Consul Template