01a3a29e51
This PR updates template and meta docs pages to give examples of accessing meta values in templates. To do so one must use the environment variable form of the meta key name, which isn't obvious and wasn't yet documented.
115 lines
2.4 KiB
Plaintext
115 lines
2.4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: meta Stanza - Job Specification
|
|
description: The "meta" stanza allows for user-defined arbitrary key-value pairs.
|
|
---
|
|
|
|
# `meta` Stanza
|
|
|
|
<Placement
|
|
groups={[
|
|
['job', 'meta'],
|
|
['job', 'group', 'meta'],
|
|
['job', 'group', 'task', 'meta'],
|
|
]}
|
|
/>
|
|
|
|
The `meta` stanza allows for user-defined arbitrary key-value pairs. It is
|
|
possible to use the `meta` stanza at the [job][], [group][], or [task][] level.
|
|
|
|
```hcl
|
|
job "docs" {
|
|
meta {
|
|
my-key = "my-value"
|
|
}
|
|
|
|
group "example" {
|
|
meta {
|
|
my-key = "my-value"
|
|
}
|
|
|
|
task "server" {
|
|
meta {
|
|
my-key = "my-value"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Metadata is merged up the job specification, so metadata defined at the job
|
|
level applies to all groups and tasks within that job. Metadata defined at the
|
|
group layer applies to all tasks within that group.
|
|
|
|
Meta values are made available inside tasks as [runtime environment variables][env_meta].
|
|
|
|
## `meta` Parameters
|
|
|
|
The "parameters" for the `meta` stanza can be any key-value. The keys and values
|
|
are both of type `string`, but they can be specified as other types. They will
|
|
automatically be converted to strings.
|
|
|
|
## `meta` Examples
|
|
|
|
The following examples only show the `meta` stanzas. Remember that the
|
|
`meta` stanza is only valid in the placements listed above.
|
|
|
|
### Coercion
|
|
|
|
This example shows the different ways to specify key-value pairs. Internally,
|
|
these values will be stored as their string representation. No type information
|
|
is preserved.
|
|
|
|
```hcl
|
|
meta {
|
|
key = "true"
|
|
key = true
|
|
|
|
key = 1.4
|
|
key = "1.4"
|
|
}
|
|
```
|
|
|
|
### Interpolation
|
|
|
|
This example shows using [Nomad interpolation][interpolation] to populate
|
|
environment variables.
|
|
|
|
```hcl
|
|
meta {
|
|
class = "${node.class}"
|
|
}
|
|
```
|
|
|
|
### Meta keys with dots
|
|
|
|
Meta keys that aren't valid HCLv2 identifiers, like ones containing `.`, require an alternative map assignment syntax.
|
|
|
|
```hcl
|
|
meta = {
|
|
"project.team" = "sre"
|
|
}
|
|
```
|
|
|
|
## `meta` Usage Examples
|
|
|
|
### Templates
|
|
|
|
To make use of a `meta` value in a template, refer to its environment variable
|
|
form.
|
|
|
|
```hcl
|
|
template {
|
|
destination = "local/out.txt"
|
|
data = <<EOH
|
|
{{ env "NOMAD_META_mykey" }}
|
|
EOH
|
|
}
|
|
```
|
|
|
|
[job]: /docs/job-specification/job 'Nomad job Job Specification'
|
|
[group]: /docs/job-specification/group 'Nomad group Job Specification'
|
|
[task]: /docs/job-specification/task 'Nomad task Job Specification'
|
|
[interpolation]: /docs/runtime/interpolation 'Nomad interpolation'
|
|
[env_meta]: /docs/runtime/environment#meta
|