Docs: Add manage Nomad variables page

website/content/commands/var/get.mdx

@@ -39,25 +39,7 @@ documentation for details.
 
 ## Examples
 
-Retrieve the variable stored at path "secret/creds":
-
-```shell-session
-$ nomad var get secret/creds
-Namespace   = default
-Path        = secret/creds
-Create Time = 2022-08-23T11:14:37-04:00
-Check Index = 116
-
-Items
-passcode = my-long-passcode
-```
-
-Return only the "passcode" item from the variable stored at "secret/creds":
-
-```shell-session
-$ nomad var get -item=passcode secret/creds
-my-long-passcode
-```
+@include 'variables/get-example.mdx'
 
 ## General options
 

website/content/commands/var/init.mdx

@@ -28,9 +28,4 @@ When no filename is supplied, a default filename of "spec.nv.hcl" or
 
 ## Examples
 
-Create an example variable specification:
-
-```shell-session
-$ nomad var init
-Example variable specification written to spec.nv.hcl
-```
+@include 'variables/init-example.mdx'

website/content/commands/var/list.mdx

@@ -52,88 +52,7 @@ documentation for details.
 
 ## Examples
 
-List values under the key "nomad/jobs":
-
-```shell-session
-$ nomad var list nomad/jobs
-Namespace  Path                           Last Updated
-default    nomad/jobs/example             2022-08-23T10:35:47-04:00
-default    nomad/jobs/variable            2022-08-23T10:24:45-04:00
-default    nomad/jobs/variable/www        2022-08-23T10:24:45-04:00
-default    nomad/jobs/variable/www/nginx  2022-08-23T10:24:46-04:00
-```
-
-List values under the key "nomad/jobs/variable/www" in JSON format:
-
-```shell-session
-$ nomad var list -out=json -namespace="*" nomad/jobs/variable/www
-[
-  {
-    "Namespace": "default",
-    "Path": "nomad/jobs/variable/www",
-    "CreateIndex": 1457,
-    "ModifyIndex": 1457,
-    "CreateTime": 1662061225600373000,
-    "ModifyTime": 1662061225600373000
-  },
-  {
-    "Namespace": "default",
-    "Path": "nomad/jobs/variable/www/nginx",
-    "CreateIndex": 800,
-    "ModifyIndex": 1000,
-    "CreateTime": 1662061717905426000,
-    "ModifyTime": 1662062162982630000
-  }
-]
-```
-
-Perform a paginated query:
-
-```shell-session
-$ nomad var list -per-page=3
-Namespace  Path                           Last Updated
-default    nomad/jobs/example             2022-08-23T10:35:47-04:00
-default    nomad/jobs/variable            2022-08-23T10:24:45-04:00
-default    nomad/jobs/variable/www        2022-08-23T10:24:45-04:00
-Next page token: default.nomad/jobs/variable/www/nginx
-```
-
-To fetch the next page :
-
-```shell-session
-$ nomad var list -per-page=3 \
-  -page-token=default.nomad/jobs/variable/www/nginx
-Namespace  Path                 Last Updated
-default    nomad/jobs/variable/www/nginx  2022-08-23T10:24:46-04:00
-```
-
-Perform a paginated query with JSON formatting:
-
-```shell-session
-$ nomad var list -out=json -namespace="*" -per-page=1 nomad/jobs/variable/www
-{
-    "Data": [
-        {
-           "Namespace": "default",
-            "Path": "nomad/jobs/variable/www",
-            "CreateIndex": 1457,
-            "ModifyIndex": 1457,
-            "CreateTime": 1662061225600373000,
-            "ModifyTime": 1662061225600373000
-        }
-    ],
-    "QueryMeta": {
-        "KnownLeader": true,
-        "LastContact": 0,
-        "LastIndex": 43,
-        "NextToken": "default.nomad/jobs/variable/www/nginx",
-        "RequestTime": 875792
-    }
-}
-```
-
-As with the tabular version, provide the `QueryMeta.NextToken` value as the
-`-page-token` value to fetch the next page.
+@include 'variables/list-example.mdx'
 
 ## General options
 

website/content/commands/var/lock.mdx

@@ -74,20 +74,7 @@ taking the sum of the length in bytes of all of the unencrypted keys and values.
 
 ## Examples
 
-Attempts to acquire a lock over the variable at path "secret/creds" for a time of
-15s and executes  `nomad job run webapp.nomad.hcl` if it succeeds:
-
-```shell-session
-$ nomad var lock -ttl=15s secret/creds "nomad job run webapp.nomad.hcl"
-```
-
-The data can also be consumed from a file on disk by prefixing with the "@"
-symbol. For example, you can store a variable using a specification created with
-the `nomad var init` command.
-
-```shell-session
-$ nomad var lock secret/foo @spec.nv.json `nomad job run webapp.nomad.hcl`
-```
+@include 'variables/lock-example.mdx'
 
 ## General options
 

website/content/commands/var/purge.mdx

@@ -33,12 +33,7 @@ documentation for details.
 
 ## Examples
 
-Purge the variable at the "secret/creds" path.
-
-```shell-session
-$ nomad var purge -y secret/creds
-Successfully purged variable "secret/creds"!
-```
+@include 'variables/purge-example.mdx'
 
 ## General options
 

website/content/commands/var/put.mdx

@@ -83,25 +83,7 @@ taking the sum of the length in bytes of all of the unencrypted keys and values.
 
 ## Examples
 
-Writes the data to the path "secret/creds":
-
-```shell-session
-$ nomad var put secret/creds passcode=my-long-passcode
-```
-
-The data can also be consumed from a file on disk by prefixing with the "@"
-symbol. For example, you can store a variable using a specification created with
-the `nomad var init` command.
-
-```shell-session
-$ nomad var put secret/foo @spec.nv.json
-```
-
-Or it can be read from standard input using the "-" symbol:
-
-```shell-session
-$ echo "abcd1234" | nomad var put secret/foo bar=-
-```
+@include 'variables/put-example.mdx'
 
 ## General options
 

website/content/docs/concepts/variables.mdx

@@ -1,50 +1,51 @@
 ---
 layout: docs
-page_title: Nomad Variables
+page_title: Nomad variables
 description: Nomad's variables feature lets you store and use encrypted configuration data in your job specifications. Learn how Access Control List (ACL) policies restrict access to variables within a namespace, how a job task's workload identity grants access to variables, and how locking a variable blocks access to that variable.
 ---
 
-# Nomad Variables
+# Nomad variables
 
 This page contains conceptual information about the Nomad variables feature,
 which lets you store and use encrypted configuration data in your job
 specifications. Learn how Access Control List (ACL) policies restrict access to variables within a namespace, how a job task's workload identity grants access to variables, and how locking a variable blocks access to that variable.
 
-Most Nomad workloads need access to config values or secrets. Nomad has a
-`template` block to [provide such configuration to tasks](/nomad/docs/job-specification/template#nomad-variables),
-but prior to Nomad 1.4 has left the role of storing that configuration to
-external services such as [HashiCorp Consul] and [HashiCorp Vault].
+## Introduction
 
-Nomad variables provide the option to store configuration at file-like paths
-directly in Nomad's state store. [Access these variables](/nomad/docs/job-specification/template#nomad-variables) directly from
-your task templates. The contents of these variables are encrypted
-and replicated between servers via raft. Access to variables is controlled by
+Most Nomad workloads need access to configuration values or secrets. Nomad has a
+`template` block to [provide these values to
+tasks](/nomad/docs/job-specification/template#nomad-variables). Nomad variables
+provide the option to store configuration at file-like paths
+directly in Nomad's state store so that you can access these variables directly from
+your task templates. Nomad encrypts and replicates the contents of these variables between servers with Raft communication. Access to variables is controlled by
 ACL policies, and tasks have implicit ACL policies that allow them to access
 their own variables. You can create, read, update, or delete variables via the
 command line, the Nomad API, or in the Nomad web UI.
 
 Note that the variables feature is intended for small pieces of configuration
 data needed by workloads. Because writing to the Nomad state store uses
 resources needed by Nomad, it is not well-suited for large or fast-changing
-data. For example, do not store batch job results as variables - these should be
+data. For example, do not store batch job results as variables. These should be
 stored in an external database. Variables are also not intended to be a full
 replacement for HashiCorp Vault. Unlike Vault, Nomad stores the root encryption
-key on the servers. See [Key Management][] for details.
+key on the servers. Refer to [Key Management][] for details.
 
-## ACL for Variables
+## Policies
 
 Every variable belongs to a specific Nomad namespace. ACL policies can restrict
 access to variables within a namespace on a per-path basis, using a list of
-`path` blocks, located under `namespace.variables`. See the [ACL policy
-specification] docs for details about the syntax and structure of an ACL policy.
+`path` blocks, located under `namespace.variables`. Refer to the [ACL policy
+specification] for details about the syntax and structure of an ACL policy.
 
-Path definitions may also include wildcard symbols, also called globs, allowing
+Path definitions may also include a wildcard symbol that allows
 a single path policy definition to apply to a set of paths within that
-namespace. For example, the policy below allows full access to variables at all
-paths in the "dev" namespace that are prefixed with "project/" (including child
-paths) but only read access to paths prefixed with "system/". Note that the glob
+namespace.
+
+In the following example, the policy allows full access to variables at all
+paths in the `dev` namespace that are prefixed with `project/`, including child
+paths, but only read access to paths prefixed with `system/`. Note that the wildcard
 can match an empty string and all other characters. This policy grants read
-access to paths prefixed with "system/" but not a path named "system" (without a
+access to paths prefixed with `system/` but not a path named `system` (without a
 trailing slash).
 
 ```hcl
@@ -76,7 +77,7 @@ The available capabilities for variables are as follows:
 | list       | List the metadata but not contents of variables at this path.                                                         |
 | destroy    | Delete variables at this path.                                                                                        |
 
-## Task Access to Variables
+## Task access to variables
 
 Tasks can access variables with the [`template`] block or using the [Task API].
 The [workload identity] for each task grants it automatic read and list access to
@@ -210,7 +211,7 @@ and no renew or release calls were made, the variable will remain locked for at
 least the lock delay duration, to avoid a possible split-brain situation, where
 there are two holders at the same time.
 
-### Leader election backed by Nomad Variable Locks
+### Leader election backed by Nomad variable locks
 
 For some applications, like HDFS or the Nomad Autoscaler, it is necessary to
 have multiple instances running to ensure redundancy in case of a failure, but

website/content/docs/manage/variables.mdx

@@ -0,0 +1,93 @@
+---
+layout: docs
+page_title: Create and update Nomad variables
+description: |-
+  Use the Nomad CLI or API to create, store, and update Nomad variables.
+---
+
+# Create and update Nomad variables
+
+This page describes the processes for interacting with Nomad variables. Use the
+[`nomad var` command reference](/nomad/commands/var) or the [Vars HTTP
+API](/nomad/api-docs/variables) to manage Nomad variables.
+
+## Background
+
+Nomad variables provide the option to securely store configuration at
+file-like paths directly in Nomad's state store. For complete documentation on
+the Nomad variables feature and related concepts, refer to the following:
+
+- [Nomad variables concepts](/nomad/docs/concepts/variables)
+- [Nomad variable specification](/nomad/docs/other-specifications/variables)
+- [Key management](/nomad/docs/manage/key-management)
+- [Workload identity](/nomad/docs/concepts/workload-identity)
+
+Nomad scopes a Nomad variable to a namespace and allows access to Nomad
+variables according to ACL policies.
+
+## Generate a Nomad variable specification
+
+Use the [`nomad var init` command](/nomad/commands/var/init) to generate a Nomad
+variable specification that you can customize.
+
+@include 'variables/init-example.mdx'
+
+## Add and update Nomad variables
+
+Use the [`nomad var put` command](/nomad/commands/var/put) to create and update
+Nomad variables. Supply variable items by including a Nomad variable
+specification file, a series of key-value pairs, or both. Refer to the [`nomad
+var put` command reference](/nomad/commands/var/put) for details on formatting
+keys and values. Values that you supply as command line arguments supersede
+values provided in any variable specification piped into the command or loaded
+from file.
+
+You may also use  the `nomad var put` command to overwrite all items in a
+variable. To avoid conflicting with other writes that may have happened since
+you last read the variable, you must use the `-check-index` flag and set it to
+the last modified index.
+
+@include 'variables/put-example.mdx'
+
+## Delete Nomad variables
+
+Use the [`nomad var purge` command](/nomad/commands/var/purge) to permanently
+delete an existing variable.
+
+@include 'variables/purge-example.mdx'
+
+## Query Nomad variables
+
+### Get
+
+Use the [`nomad var get` command](/nomad/commands/var/get) to fetch the contents of an existing variable.
+
+@include 'variables/get-example.mdx'
+
+### List
+
+Use the [`nomad var list` command](/nomad/commands/var/list) to fetch a list of
+variable paths accessible to you.
+
+@include 'variables/list-example.mdx'
+
+## Lock access to a Nomad variable
+
+The [`nomad var lock` command](/nomad/commands/var/lock) provides a mechanism
+for distributed locking. Nomad creates a lock in the given variable, and only
+when held, invokes the specified child process.
+
+@include 'variables/lock-example.mdx'
+
+## Next steps
+
+Refer to the following Nomad variables tutorials for in-depth learning:
+
+- [Create and update Nomad
+  variables](/nomad/tutorials/variables/variables-create) contains advanced
+  examples for updating Nomad variables.
+- [Configure access control for Nomad
+  variables](/nomad/tutorials/variables/variables-acls) shows how to configure
+  ACL policies for Nomad variables.
+
+To learn how to access Nomad variables in your job specification, refer to [Use Nomad variables in tasks](/nomad/docs/job-declare/nomad-variables).

website/content/docs/other-specifications/variables.mdx

@@ -9,8 +9,8 @@ description: |-
 
 [Nomad variables][nv] let you store and use encrypted configuration data in your
 job specifications. Specify variables as HCL files and submit them with the
-[`nomad var put` command][var-put. Unlike [job specifications][jobspecs], Nomad
-Variables specifications do not support HCL2 features like functions.
+[`nomad var put` command][var-put]. Unlike [job specifications][jobspecs], Nomad
+variables specifications do not support HCL2 features like functions.
 
 This example is a variable specification generated by [`nomad var init` command][var-init].
 
@@ -59,8 +59,7 @@ $ nomad var put -in hcl some/path @spec.nv.hcl
 - `items` `(object: <required>)` - Object of keys and values to set. Must be
   strings.
 
-Refer to the [Restrictions section][var-restrict] in the command reference for
-details on `path` and `items` name restrictions.
+Refer to the [`nomad var put` restrictions section][var-restrict] for details on `path` and `items` name restrictions.
 
 ## Resources