HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Nomad
Nomad Home

Create and update Nomad variables

This page describes the processes for interacting with Nomad variables. Use the nomad var command reference or the Vars HTTP API 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 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 to generate a Nomad variable specification that you can customize.

Generate an example variable specification in the current directory.

$ nomad var init
Example variable specification written to spec.nv.hcl

Add and update Nomad variables

Use the nomad var put command 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 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.

This example writes the Nomad variables passcode=my-long-passcode and user=me to the path secret/foo. The variables are scoped to the prod namespace.

$ nomad var put -namespace prod secret/foo passcode=my-long-passcode user=me

This example uses a Nomad variable specification file, prefixed with the "@" symbol.

$ nomad var put -namespace prod secret/foo @spec.nv.json

Use a hyphen (-) to instruct the command to read the variable value from standard input. The -out option displays the command's output.

$ echo "abcd1234" | nomad var put -namespace prod -out secret/foo bar=-
Namespace   = prod
Path        = secret/foo
Create Time = 2025-11-19T11:21:56-04:00
Check Index = 28

Items
bar = abcd1234

This example updates the bar value in the secret/foo path and outputs the updated variable in JSON format. You must include the check-index value when you update a Nomad variable.

$ nomad var put -namespace prod -out json -check-index 28 secret/foo bar=efgh5678

Output is similar to this snippet.

{
  "Namespace": "prod",
  "Path": "secret/foo",
  "CreateIndex": 28,
  "ModifyIndex": 39,
  "CreateTime": 1663600883130070567,
  "ModifyTime": 1663601343585644939,
  "Items": {
    "bar": "efgh5678",
  }
}

Delete Nomad variables

Use the nomad var purge command to permanently delete an existing variable.

Purge all the variables at the secret/foo path.

$ nomad var purge secret/foo

Query Nomad variables

Get

Use the nomad var get command to fetch the contents of an existing variable.

This example retrieves the variable stored at path secret/foo.

$ nomad var get secret/foo
Namespace   = default
Path        = secret/foo
Create Time = 2025-11-23T11:14:37-04:00
Check Index = 116

Items
passcode = my-long-passcode

Return only the passcode item from the variable stored at secret/foo.

$ nomad var get -item=passcode secret/foo
my-long-passcode

List

Use the nomad var list command to fetch a list of variable paths accessible to you.

List the variables in the namespace prod.

$ nomad var list -namespace prod
Namespace  Path                     Last Updated
prod       project/another-example  2025-09-19T11:21:56-04:00
prod       project/example          2025-09-19T11:29:03-04:00

List the variables in namespace prod that match the prefix filter project/ex.

$ nomad var list -namespace prod project/ex
Namespace  Path             Last Updated
prod       project/example  2025-09-19T11:29:03-04:00

Use the wildcard namespace indicator (*) to list all the variables you have access to. For many shells, the * character is significant, so you might need to wrap it in double (") or single (') quotation marks.

$ nomad var list -namespace '*'
Namespace  Path                     Last Updated
dev        another-project/example  2022-09-19T11:29:54-04:00
dev        project/example          2022-09-19T11:29:54-04:00
dev        system/config            2022-09-19T11:29:54-04:00
prod       project/another-example  2022-09-19T11:21:56-04:00
prod       project/example          2022-09-19T11:29:03-04:00

List values under the key nomad/jobs.

$ 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.

$ 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.

$ 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, include the next page token.

$ 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.

$ 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.

Lock access to a Nomad variable

The nomad var lock command provides a mechanism for distributed locking. Nomad creates a lock in the given variable, and only when held, invokes the specified child process.

Lock the variable at path secret/foo for a time of fifteen seconds. Execute nomad job run webapp.nomad.hcl if the lock succeeds.

$ nomad var lock -ttl=15s secret/foo "nomad job run webapp.nomad.hcl"

You may also pass in file, prefixed with the "@" symbol. This example store and locks the variables in the spec.nv.json file. Execute nomad job run webapp.nomad.hcl if the lock succeeds.

$ nomad var lock secret/foo @spec.nv.json `nomad job run webapp.nomad.hcl`

Next steps

Refer to the following Nomad variables tutorials for in-depth learning:

To learn how to access Nomad variables in your job specification, refer to Use Nomad variables in tasks.

Edit this page on GitHub