diff --git a/website/content/docs/commands/var/put.mdx b/website/content/docs/commands/var/put.mdx index 6726ff0bf..34a361ad3 100644 --- a/website/content/docs/commands/var/put.mdx +++ b/website/content/docs/commands/var/put.mdx @@ -16,13 +16,13 @@ nomad var put [options] [=]... nomad var put [options] [] [=]... ``` -Variable metadata and items can be supplied using a variable specification, by -using command arguments, or by a combination of the two techniques. An entire -variable specification can be provided to the command via standard input (stdin) -by setting the first argument to "-" or from a file by using an @-prefixed path -to a variable specification file. When providing variable data via stdin, you -must provide the `-in` flag with the format of the specification, which must be -either "hcl" or "json". +Variable metadata and items can be supplied using a [variable +specification][varspec], by using command arguments, or by a combination of the +two techniques. An entire variable specification can be provided to the command +via standard input (stdin) by setting the first argument to "-" or from a file +by using an @-prefixed path to a variable specification file. When providing +variable data via stdin, you must provide the `-in` flag with the format of the +specification, which must be either "hcl" or "json". Items to be stored in the variable can be supplied using the specification, as a series of key-value pairs, or both. The value for a key-value pair can be a @@ -107,5 +107,6 @@ $ echo "abcd1234" | nomad var put secret/foo bar=- [variable]: /nomad/docs/concepts/variables +[varspec]: /nomad/docs/other-specifications/variables [ACL Policy]: /nomad/docs/other-specifications/acl-policy#variables [RFC3986]: https://www.rfc-editor.org/rfc/rfc3986#section-2 diff --git a/website/content/docs/other-specifications/variables.mdx b/website/content/docs/other-specifications/variables.mdx new file mode 100644 index 000000000..193600b43 --- /dev/null +++ b/website/content/docs/other-specifications/variables.mdx @@ -0,0 +1,68 @@ +--- +layout: docs +page_title: Nomad Variable Specification +description: Learn about Nomad's Variable specification. +--- + +# Nomad Variable Specification + +[Nomad Variables][nv] may be specified as HCL files and submitted by the +[`nomad var put`][var-put] CLI command. + +Unlike [Job specifications][jobspecs], Nomad Variables specifications do *not* +support HCL2 features like functions. + +Example variable specification generated by [`nomad var init`][var-init]: + +```hcl +# A variable path can be specified in the specification file +# and will be used when writing the variable without specifying a +# path in the command or when writing JSON directly to the `/var/` +# HTTP API endpoint +# path = "path/to/variable" + +# The Namespace to write the variable can be included in the specification. This +# value can be overridden by specifying the "-namespace" flag on the "put" +# command. +# namespace = "default" + +# The items map is the only strictly required part of a variable +# specification, since path and namespace can be set via other means. +# It contains the sensitive material to encrypt and store as a Nomad +# variable. The entire items map is encrypted and decrypted as a +# single unit. + +# REMINDER: While keys in the items map can contain dots, using them +# in templates is easier when they do not. As a best practice, avoid +# dotted keys when possible. +items { + key1 = "value 1" + key2 = "value 2" +} +``` + +Example usage if the above is in a file named `spec.nv.hcl`: + +```shell-session +$ nomad var put -in hcl some/path @spec.nv.hcl +``` + +## Variable Specification Parameters + +- `path` `(string: )` - The path to the variable being defined. If + empty it must be specified on the command line. + +- `namespace` `(string: )` - The namespace of the variable. May be + overridden by the `-namespace` command line flag or `NOMAD_NAMESPACE` + environment variable. + +- `items` `(object: )` - Object of keys and values to set. Must be + strings. + +See [Variable Restrictions][var-restrict] for details on `path` and `items` +name restrictions. + +[nv]: /nomad/docs/concepts/variables +[var-init]: /nomad/docs/commands/var/init +[var-put]: /nomad/docs/commands/var/put +[var-restrict]: /nomad/docs/commands/var/put#restrictions diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index a9f2c7d4d..3ff074c6c 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1678,6 +1678,10 @@ "title": "ACL Policy", "path": "other-specifications/acl-policy" }, + { + "title": "Variables", + "path": "other-specifications/variables" + }, { "title": "Volume", "routes": [