docs templates: Document some template logic

Adds documentation for `if` and `range` statements in Go templates
and also more explicitly points people at the Go documentation for
more information.

1 files changed, 42 insertions, 1 deletions

diff --git a/docs/templates.md b/docs/templates.md
index bfd254630302..8dff28dd1c38 100644
--- a/docs/templates.md
+++ b/docs/templates.md
@@ -5,6 +5,13 @@ The template file format is based on Go's [templating engine][] in combination
 with a small extension library called [sprig][] that adds additional template
 functions.
 
+Go templates can either simply display variables or build more complicated
+*pipelines* in which variables are passed to functions for further processing,
+or in which conditionals are evaluated for more complex template logic.
+
+It is recommended that you check out the Golang [documentation][] for the templating
+engine in addition to the cherry-picked features listed here.
+
 ## Basic variable interpolation
 
 The basic template format uses `{{ .variableName }}` as the interpolation format.
@@ -66,7 +73,7 @@ certKeyPath: my-website/cert-key
 
 # The following interpolations are possible:
 
-{{ .name | upper }} 
+{{ .name | upper }}
 -> DONALD
 
 {{ .name | upper | repeat 2 }}
@@ -76,6 +83,39 @@ certKeyPath: my-website/cert-key
 -> Returns content of 'my-website/cert-key' from pass
 ```
 
+## Conditionals & ranges
+
+Some logic is supported in Golang templates and can be used in Kontemplate, too.
+
+With the following values:
+
+```
+useKube2IAM: true
+servicePorts:
+  - 8080
+  - 9090
+```
+
+The following interpolations are possible:
+
+```
+# Conditionally insert something in the template:
+metadata:
+  annotations:
+    foo: bar
+    {{ if .useKube2IAM -}} iam.amazonaws.com/role: my-api {{- end }}
+```
+
+```
+# Iterate over a list of values
+ports:
+  {{ range .servicePorts }}
+  - port: {{ . }}
+  {{ end }}
+```
+
+Check out the Golang documentation (linked above) for more information about template logic.
+
 ## Caveats
 
 Kontemplate does not by itself parse any of the content of the templates, which
@@ -86,6 +126,7 @@ You can perform some validation by using `kontemplate apply --dry-run` which
 will make use of the Dry-Run functionality in `kubectl`.
 
 [templating engine]: https://golang.org/pkg/text/template/
+[documentation]: https://golang.org/pkg/text/template/
 [sprig]: http://masterminds.github.io/sprig/
 [Go documentation]: https://golang.org/pkg/text/template/#hdr-Functions
 [pass]: https://www.passwordstore.org/