From b6f18151543b00b7fed0dd0bfe6f3e8f0c287261 Mon Sep 17 00:00:00 2001
From: Michael Schurter <mschurter@hashicorp.com>
Date: Mon, 13 Feb 2023 14:06:56 -0800
Subject: [PATCH] docs: add variable specification docs (#16165)

---
 website/content/docs/commands/var/put.mdx     | 15 ++--
 .../docs/other-specifications/variables.mdx   | 68 +++++++++++++++++++
 website/data/docs-nav-data.json               |  4 ++
 3 files changed, 80 insertions(+), 7 deletions(-)
 create mode 100644 website/content/docs/other-specifications/variables.mdx

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] <variable spec file reference> [<key>=<value>]...
 nomad var put [options] <path to store variable> [<variable spec file reference>] [<key>=<value>]...
 ```
 
-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: <optional>)` - The path to the variable being defined. If
+  empty it must be specified on the command line.
+
+- `namespace` `(string: <optional>)` - The namespace of the variable. May be
+  overridden by the `-namespace` command line flag or `NOMAD_NAMESPACE`
+  environment variable.
+
+- `items` `(object: <required>)` - 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": [