docs: note replacement of - characters in meta env vars (#19501)

The keys of `meta` fields have all characters outside of `[A-Za-z0-9_.]` replaced by underscores when we create `NOMAD_META` environment variables. Make sure this replacement is documented. Fixes: #15359
hashicorp · Dec 15, 2023 · 14200a8 · 14200a8
1 parent e39b39e
commit 14200a8
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 10 deletions.
diff --git a/website/content/docs/job-specification/meta.mdx b/website/content/docs/job-specification/meta.mdx
@@ -47,8 +47,8 @@ Meta values are made available inside tasks as [runtime environment variables][e
 
 The "parameters" for the `meta` block 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. Any `-` character existing in the key
-will also be converted to `_`.
+automatically be converted to strings. Any character in a key other than
+`[A-Za-z0-9_.]` will be converted to `_`.
 
 ## `meta` Examples
 

diff --git a/website/content/docs/runtime/environment.mdx b/website/content/docs/runtime/environment.mdx
@@ -89,13 +89,14 @@ For more details on the task directories, see the [Filesystem internals][].
 
 ## Meta
 
-The job specification also allows you to specify a `meta` block to supply arbitrary
-configuration to a task. This allows you to easily provide job-specific
-configuration even if you use the same executable unit in multiple jobs. These
-key-value pairs are passed through to the job as `NOMAD_META_<key>=<value>`
-environment variables. Prior to Nomad 0.5.5 the key was uppercased and since
-then both the original case and an uppercased version are injected. The
-uppercased version will be deprecated in a future release.
+The job specification also allows you to specify a `meta` block to supply
+arbitrary configuration to a task. This allows you to easily provide
+job-specific configuration even if you use the same executable unit in multiple
+jobs. These key-value pairs are passed through to the job as
+`NOMAD_META_<key>=<value>` environment variables. Any character in a key other
+than `[A-Za-z0-9_.]` will be converted to `_`. Prior to Nomad 0.5.5 the key was
+uppercased and since then both the original case and an uppercased version are
+injected. The uppercased version will be deprecated in a future release.
 
 Currently there is no enforcement that the meta keys be lowercase, but using
 multiple keys with the same uppercased representation will lead to undefined

diff --git a/website/content/partials/envvars.mdx b/website/content/partials/envvars.mdx
@@ -22,7 +22,7 @@
 | `NOMAD_PARENT_CGROUP`    | The parent cgroup used to contain task cgroups (Linux only)                                                                                                                                                                                                                     |
 | `NOMAD_NAMESPACE`        | Namespace in which the allocation is running                                                                                                                                                                                                                                    |
 | `NOMAD_REGION`           | Region in which the allocation is running                                                                                                                                                                                                                                       |
-| `NOMAD_META_<key>`       | The metadata value given by `key` on the task's metadata. <br/> **Note:** this is different from [`${meta.<key>}`](/nomad/docs/runtime/interpolation#node-variables-) which are keys in the node's metadata.                                                                    |
+| `NOMAD_META_<key>`       | The metadata value given by `key` on the task's metadata. Any character in a key other than `[A-Za-z0-9_.]` will be converted to `_`. <br/> **Note:** this is different from [`${meta.<key>}`](/nomad/docs/runtime/interpolation#node-variables-) which are keys in the node's metadata.                                                                    |
 | `VAULT_TOKEN`            | The task's Vault token. See the [Vault Integration][vault] documentation for more details                                                                                                                                                                                       |
 
 ### Network-related Variables