mirror of
https://github.com/kemko/nomad.git
synced 2026-01-02 16:35:44 +03:00
53b083b8c5
* Move commands from docs to its own root-level directory * temporarily use modified dev-portal branch with nomad ia changes * explicitly clone nomad ia exp branch * retrigger build, fixed dev-portal broken build * architecture, concepts and get started individual pages * fix get started section destinations * reference section * update repo comment in website-build.sh to show branch * docs nav file update capitalization * update capitalization to force deploy * remove nomad-vs-kubernetes dir; move content to what is nomad pg * job section * Nomad operations category, deploy section * operations category, govern section * operations - manage * operations/scale; concepts scheduling fix * networking * monitor * secure section * remote auth-methods folder and move up pages to sso; linkcheck * Fix install2deploy redirects * fix architecture redirects * Job section: Add missing section index pages * Add section index pages so breadcrumbs build correctly * concepts/index fix front matter indentation * move task driver plugin config to new deploy section * Finish adding full URL to tutorials links in nav * change SSO to Authentication in nav and file system * Docs NomadIA: Move tutorials into NomadIA branch (#26132) * Move governance and policy from tutorials to docs * Move tutorials content to job-declare section * run jobs section * stateful workloads * advanced job scheduling * deploy section * manage section * monitor section * secure/acl and secure/authorization * fix example that contains an unseal key in real format * remove images from sso-vault * secure/traffic * secure/workload-identities * vault-acl change unseal key and root token in command output sample * remove lines from sample output * fix front matter * move nomad pack tutorials to tools * search/replace /nomad/tutorials links * update acl overview with content from deleted architecture/acl * fix spelling mistake * linkcheck - fix broken links * fix link to Nomad variables tutorial * fix link to Prometheus tutorial * move who uses Nomad to use cases page; move spec/config shortcuts add dividers * Move Consul out of Integrations; move namespaces to govern * move integrations/vault to secure/vault; delete integrations * move ref arch to docs; rename Deploy Nomad back to Install Nomad * address feedback * linkcheck fixes * Fixed raw_exec redirect * add info from /nomad/tutorials/manage-jobs/jobs * update page content with newer tutorial * link updates for architecture sub-folders * Add redirects for removed section index pages. Fix links. * fix broken links from linkcheck * Revert to use dev-portal main branch instead of nomadIA branch * build workaround: add intro-nav-data.json with single entry * fix content-check error * add intro directory to get around Vercel build error * workound for emtpry directory * remove mdx from /intro/ to fix content-check and git snafu * Add intro index.mdx so Vercel build should work --------- Co-authored-by: Tu Nguyen <im2nguyen@gmail.com>
403 lines
19 KiB
Plaintext
403 lines
19 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Go template syntax
|
|
description: |-
|
|
Discover the syntax of the text and template packages in Go and
|
|
become comfortable using them to create templates for Nomad
|
|
jobs.
|
|
---
|
|
|
|
# Go template syntax
|
|
|
|
Go's internal templating language, provided by the text/template package, is the
|
|
basis for many commonly used template implementations. Some HashiCorp specific
|
|
examples are:
|
|
|
|
- Nomad `template` stanzas
|
|
- Consul-template
|
|
- Vault agent templates
|
|
- Nomad Pack
|
|
|
|
Some other implementations you might have seen are:
|
|
|
|
- Hugo
|
|
- Helm
|
|
|
|
Go's template is designed to be extended by developers, and provides access to
|
|
data objects and additional functions that are passed into the template engine
|
|
programmatically. This guide only uses functions universally provided in
|
|
the text/template package, and does not discuss the specifics of data access.
|
|
However, once you have learned the basics of Go templates, implementation
|
|
specific data access is easier to understand.
|
|
|
|
Early in this guide, you will see elements that you are not familiar with
|
|
yet, but don't panic. Use your intuition and experience with other languages as
|
|
your guide. As the guide progresses, it revisits these examples
|
|
with a more thorough explanation.
|
|
|
|
## Starting template
|
|
|
|
Here is a template to get you started on your journey. This guide refers
|
|
to this template while you are learning the names for the syntax.
|
|
|
|
```plaintext
|
|
This is a simple template
|
|
It can {{ "output" }} something.
|
|
It also
|
|
{{- " demonstrates" }} trim markers.
|
|
{{/* it has a comment */}}
|
|
It can {{ "output" }} something.
|
|
It can demonstrate {{ "output" | print }} using pipelines.
|
|
It also {{ $A := "assigns variables" }}{{ $A }}.
|
|
And conditionals:
|
|
{{ $B := 2 }}{{ if eq $B 1 }}B is 1{{ else }}B is 2{{ end }}
|
|
```
|
|
|
|
## Nomenclature
|
|
|
|
Go template uses names for its objects that are not immediately familiar. Once
|
|
you have familiarized yourself with the concepts, the canonical documentation
|
|
becomes easier to read.
|
|
|
|
### Template
|
|
|
|
Not surprisingly, the template is the entire text that is submitted to the
|
|
template engine to be rendered. The template consists of text and "actions". All
|
|
text outside of actions is copied to the output unchanged.
|
|
|
|
### Actions
|
|
|
|
Actions provide the dynamic components of the template. They are set off from
|
|
the text using delimiters. The actions in the sample template are:
|
|
|
|
```plaintext
|
|
{{ "output" }}
|
|
{{- " demonstrates" }}
|
|
{{/* it has a comment */}}
|
|
{{ "output" | print }}
|
|
{{ $A := "assigns variables" }}{{ $A }}.
|
|
{{ $B := 2 }}{{ if eq $B 1 }}{{ else }}{{ end }}
|
|
```
|
|
|
|
Actions are composed of "control structures," or data evaluations through
|
|
"pipelines."
|
|
|
|
<Note>
|
|
|
|
Actions may not span newlines. However, raw-string literals and
|
|
comments may contain newlines. Raw-string literals are a special type of
|
|
string literal discussed later.
|
|
|
|
</Note>
|
|
|
|
### Delimiters
|
|
|
|
As said earlier, actions are set between a left delimiter (`{{` by default)
|
|
and a right delimiter (`}}` by default). The implementation can either use
|
|
alternative delimiters, like Levant's use of `[[` and `]]`; or allow you to
|
|
specify them as in Nomad's `template` stanza.
|
|
|
|
<Note>
|
|
|
|
The HashiCorp Learn tutorials use go template's default delimiters
|
|
of `{{` and `}}` unless specifically stated in the guide itself. Remember
|
|
that these delimiters might need to be customized for your specific use case.
|
|
|
|
</Note>
|
|
|
|
#### Trim markers
|
|
|
|
Go template outputs everything between actions, including whitespace and
|
|
line feeds. This can make it challenging to read nested template code.
|
|
|
|
If an action's left delimiter is followed immediately by
|
|
a minus sign and ASCII space character `{{- `, all trailing white space
|
|
is trimmed from the immediately preceding text. Similarly, if the right
|
|
delimiter is preceded by a space and minus sign ` -}}`, all
|
|
leading white space is trimmed from the immediately following text.
|
|
|
|
<Note>
|
|
|
|
The ASCII space must be present in these trim markers. `{{-3}}`
|
|
parses as an action containing the number -3.
|
|
|
|
</Note>
|
|
|
|
### Comments
|
|
|
|
Comments are a special action created using a `/*` immediately following the
|
|
left delimiter and a `*/` immediately preceding the right delimiter. The sample
|
|
template has a comment.
|
|
|
|
```plaintext
|
|
{{/* it has a comment */}}
|
|
```
|
|
|
|
Comments can span multiple lines. Any elements within the comment start and end
|
|
delimiters is not processed by the rendering engine. Comments can also contain
|
|
trim markers on one or both ends to remove whitespace. Comments with trim markers
|
|
must have a space between the `-` and the start or end of the comment.
|
|
|
|
```plaintext
|
|
{{- /* example comment with trim markers /* -}}
|
|
```
|
|
|
|
<Tip>
|
|
|
|
Comment out sections of a template while you are debugging it to
|
|
simplify your troubleshooting.
|
|
|
|
</Tip>
|
|
|
|
### Pipelines
|
|
|
|
A pipeline is one or more "commands" chained together using the pipe `|` symbol.
|
|
A command is a:
|
|
|
|
- simple value (argument)
|
|
- function or method call, possibly with multiple arguments.
|
|
|
|
For example:
|
|
|
|
```plaintext
|
|
It can demonstrate {{ "output" | print }} using pipelines.
|
|
```
|
|
|
|
This template line uses pipelining to send the string literal "output" to the
|
|
print function.
|
|
|
|
#### Simple values
|
|
|
|
Simple values are typically used as either the sole element in an action, like a
|
|
string literal
|
|
|
|
```plaintext
|
|
{{ "output" }}
|
|
```
|
|
|
|
which is rendered to the template in place. Simple values can also be references
|
|
to data provided as context to the template. This context is represented by a
|
|
period '.' and called "dot".
|
|
|
|
<Note>
|
|
|
|
Implementation-specific tutorials will describe dot and its usage
|
|
in further detail.
|
|
|
|
</Note>
|
|
|
|
#### Literals
|
|
|
|
Go template supports the following types as literals.
|
|
|
|
| Data type | Example | Specification | Notes |
|
|
| ---------------- | -------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------ |
|
|
| `string` | "output" | [String literal spec](https://golang.org/ref/spec#String_literals) | may not contain unescaped line feeds |
|
|
| `raw string` | \`"out<br />put"\` | [String literal spec](https://golang.org/ref/spec#String_literals) | can contain raw linefeed characters |
|
|
| `integer` | 42 <br />0xBadFace<br /> | [Integer literal Spec](https://golang.org/ref/spec#Integer_literals) | |
|
|
| `floating point` | 0.<br />72.40<br />2.71828<br /> | [Floating-point literal Spec](https://golang.org/ref/spec#Floating-point_literals) | |
|
|
| `boolean` | true<br />false | [Boolean type](https://golang.org/ref/spec#Boolean_types) | |
|
|
|
|
#### Function calls
|
|
|
|
Go template provides a very limited number of functions universally, and instead
|
|
relies on the specific implementation to add functions to enhance the user
|
|
experience. However, `print` is one of the available functions.
|
|
|
|
```plaintext
|
|
{{ "output" | print }}
|
|
```
|
|
|
|
Later in the guide, there is a list of the built-in functions provided by all
|
|
Go template environments.
|
|
|
|
#### Method calls
|
|
|
|
Since Go template provides an empty context to the template by default, there
|
|
are no methods to be called. Refer to an implementation specific guide for more
|
|
information on method calls.
|
|
|
|
### Control structures
|
|
|
|
Go template control structures are used to provide branching, iteration, and
|
|
sub-templates. The control structure documentation uses `T0` and `T1` as
|
|
placeholders for the specific template content that would be contained there.
|
|
|
|
T0 and T1 might see a different version of dot depending on the control
|
|
structure that is generating them. For example, `with` and `range` redefine
|
|
dot to a new scope when their pipeline is non-empty.
|
|
|
|
## Control structure list
|
|
|
|
### if
|
|
|
|
```plaintext
|
|
{{if pipeline}} T1 {{end}}
|
|
```
|
|
|
|
If the value of the pipeline is empty, no output is generated; otherwise, T1 is
|
|
executed. The empty values are false, 0, any nil pointer or interface value, and
|
|
any array, slice, map, or string of length zero. Dot is unaffected.
|
|
|
|
```plaintext
|
|
{{if pipeline}} T1 {{else}} T0 {{end}}
|
|
```
|
|
|
|
If the value of the pipeline is empty, T0 is executed; otherwise, T1 is
|
|
executed. Dot is unaffected.
|
|
|
|
```plaintext
|
|
{{if pipeline}} T1 {{else if pipeline}} T0 {{end}}
|
|
```
|
|
|
|
To simplify the appearance of if-else chains, the else action
|
|
of an if may include another if directly; the effect is exactly
|
|
the same as writing:
|
|
|
|
```plaintext
|
|
{{if pipeline}} T1 {{else}}{{if pipeline}} T0 {{end}}{{end}}
|
|
```
|
|
|
|
The sample template uses `if` and the `eq` function to branch
|
|
between outputs.
|
|
|
|
```plaintext
|
|
{{ if eq $B 1 }}B is 1{{ else }}B is not 1{{ end }}
|
|
```
|
|
|
|
### range
|
|
|
|
```plaintext
|
|
{{range pipeline}} T1 {{end}}
|
|
```
|
|
|
|
The value of the pipeline must be an array, slice, map, or channel.
|
|
If the value of the pipeline has length zero, nothing is output;
|
|
otherwise, dot is set to the successive elements of the array,
|
|
slice, or map and T1 is executed. If the value is a map and the
|
|
keys are of basic type with a defined order, the elements are
|
|
visited in sorted key order.
|
|
|
|
```plaintext
|
|
{{range pipeline}} T1 {{else}} T0 {{end}}
|
|
```
|
|
|
|
The value of the pipeline must be an array, slice, map, or channel.
|
|
If the value of the pipeline has length zero, dot is unaffected and
|
|
T0 is executed; otherwise, dot is set to the successive elements
|
|
of the array, slice, or map and T1 is executed.
|
|
|
|
One place you can test range is using the `-t` flag on many of the
|
|
nomad commands. For example, you can retrieve the Node ID and version
|
|
of each client in your cluster with the following command.
|
|
|
|
```shell-session
|
|
$ nomad node status -t '{{range .}}{{print .ID}} {{println .Version}}{{end}}'
|
|
```
|
|
|
|
### with
|
|
|
|
```plaintext
|
|
{{with pipeline}} T1 {{end}}
|
|
```
|
|
|
|
If the value of the pipeline is empty, no output is generated; otherwise, dot is
|
|
set to the value of the pipeline and T1 is executed.
|
|
|
|
```plaintext
|
|
{{with pipeline}} T1 {{else}} T0 {{end}}
|
|
```
|
|
|
|
If the value of the pipeline is empty, dot is unaffected and T0 is executed;
|
|
otherwise, dot is set to the value of the pipeline and T1 is executed.
|
|
|
|
### define
|
|
|
|
```plaintext
|
|
{{define "name"}} T1 {{end}}
|
|
```
|
|
|
|
Create a template with the specified name that can be invoked using a `template`
|
|
control structure
|
|
|
|
### template
|
|
|
|
```plaintext
|
|
{{template "name"}}
|
|
```
|
|
|
|
The template with the specified name is executed with nil data.
|
|
|
|
```plaintext
|
|
{{template "name" pipeline}}
|
|
```
|
|
|
|
The template with the specified name is executed with dot set to the value of
|
|
the pipeline.
|
|
|
|
### block
|
|
|
|
```plaintext
|
|
{{block "name" pipeline}} T1 {{end}}
|
|
```
|
|
|
|
A block is shorthand for defining a template
|
|
|
|
```plaintext
|
|
{{define "name"}} T1 {{end}}
|
|
```
|
|
|
|
and then executing it in place
|
|
|
|
```plaintext
|
|
{{template "name" pipeline}}
|
|
```
|
|
|
|
The typical use is to define a set of root templates that are then customized by
|
|
redefining the block templates within.
|
|
|
|
## Function list
|
|
|
|
Go template provides the following functions. Most implementations provide
|
|
additional functions and can optionally override the default implementations.
|
|
Consult the specific application's documentation for more information.
|
|
|
|
### Functions
|
|
|
|
| Function name | Description |
|
|
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| and | Returns the boolean AND of its arguments by returning the first empty argument or the last argument, that is, "and x y" behaves as "if x then y else x". **All the arguments are evaluated.** |
|
|
| call | Returns the result of calling the first argument, which must be a function, with the remaining arguments as parameters. Thus "call .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where Y is a func-valued field, map entry, or the like. The first argument must be the result of an evaluation that yields a value of function type (as distinct from a predefined function such as print). The function must return either one or two result values, the second of which is of type error. If the arguments don't match the function or the returned error value is non-nil, execution stops. |
|
|
| index | Returns the result of indexing its first argument by the following arguments. Thus `index x 1 2 3` is, in Go syntax, `x[1][2][3]`. Each indexed item must be a map, slice, or array. |
|
|
| slice | slice returns the result of slicing its first argument by the remaining arguments. Thus:<ul><li>`slice x 1 2` is, in Go syntax, `x[1:2]`</li><li> `slice x` is `x[:]`</li><li> `slice x 1` is `x[1:]`, </li><li>`slice x 1 2 3` is `x[1:2:3]`</li></ul> The first argument must be a string, slice, or array. |
|
|
| len | Returns the integer length of its argument. |
|
|
| not | Returns the boolean negation of its single argument. |
|
|
| or | Returns the boolean OR of its arguments by returning the first non-empty argument or the last argument, that is,"or x y" behaves as "if x then x else y". **All the arguments are evaluated.** |
|
|
| print | An alias for [fmt.Sprint][] |
|
|
| printf | An alias for [fmt.Sprintf][] |
|
|
| println | An alias for [fmt.Sprintln][] |
|
|
|
|
### Comparison functions
|
|
|
|
| Function name | Description |
|
|
| ------------- | ----------------------------------------- |
|
|
| eq | Returns the boolean truth of arg1 == arg2 |
|
|
| ne | Returns the boolean truth of arg1 != arg2 |
|
|
| lt | Returns the boolean truth of arg1 < arg2 |
|
|
| le | Returns the boolean truth of arg1 <= arg2 |
|
|
| gt | Returns the boolean truth of arg1 > arg2 |
|
|
| ge | Returns the boolean truth of arg1 >= arg2 |
|
|
|
|
### Specialized output functions
|
|
|
|
| Function name | Description |
|
|
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
| html | Returns the escaped HTML equivalent of the textual representation of its arguments. |
|
|
| js | Returns the escaped JavaScript equivalent of the textual representation of its arguments. |
|
|
| urlquery | Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. |
|
|
|
|
|
|
[fmt.sprint]: https://golang.org/pkg/fmt/#Sprint
|
|
[fmt.sprintf]: https://golang.org/pkg/fmt/#Sprintf
|
|
[fmt.sprintln]: https://golang.org/pkg/fmt/#Sprintln
|