Create a variable as key-value pairs.
nomad var put my/first/var user=me password=passW0rd thoughts=awesome
Get a variable.
nomad var get my/first/var
Namespace = default
Path = my/first/var
Create Time = 2022-09-01 15:40:25.600373 -0400 EDT
Check Index = 1457
Items
password = passW0rd
thoughts = awesome
user = me
Get the variable in a more machine friendly format.
nomad var get -out=pretty-json my/first/var
{
"Namespace": "default",
"Path": "my/first/var",
"CreateIndex": 1457,
"ModifyIndex": 1457,
"CreateTime": 1662061225600373000,
"ModifyTime": 1662061225600373000,
"Items": {
"password": "passW0rd",
"thoughts": "awesome",
"user": "me"
}
}
While the default of the nomad var put
command is not to output the variable, you can set the -out
flag to have it output the variable that it created.
nomad var put -out pretty-json my/second/var status="getting the flow"
{
"Namespace": "default",
"Path": "my/second/var",
"CreateIndex": 1468,
"ModifyIndex": 1468,
"CreateTime": 1662061717905426000,
"ModifyTime": 1662061717905426000,
"Items": {
"status": "getting the flow"
}
}
Using command piping, you can use the nomad var get
and nomad var put
to update a variable in place.
nomad var get my/second/var | \
nomad var put -out=pretty-json - status="getting updates"
{
"Namespace": "default",
"Path": "my/second/var",
"CreateIndex": 1468,
"ModifyIndex": 1479,
"CreateTime": 1662061717905426000,
"ModifyTime": 1662062162982630000,
"Items": {
"status": "getting updates"
}
}
You can add more Items to a variable in the same way.
nomad var get my/second/var | \
nomad var put -out=pretty-json - new=niiice
{
"Namespace": "default",
"Path": "my/second/var",
"CreateIndex": 1468,
"ModifyIndex": 1483,
"CreateTime": 1662061717905426000,
"ModifyTime": 1662062312002302000,
"Items": {
"new": "niiice",
"status": "getting updates"
}
}
To remove an item, set the Item key's value to ""
nomad var get my/second/var | \
nomad var put -out=pretty-json - new=""
{
"Namespace": "default",
"Path": "my/second/var",
"CreateIndex": 1468,
"ModifyIndex": 1486,
"CreateTime": 1662061717905426000,
"ModifyTime": 1662062477731007000,
"Items": {
"status": "getting updates"
}
}
However, you can not remove all of the Items in a variable. To completely remove a variable, you should use the nomad var purge
command.
In the previous examples, you might have noticed that when performing the updates with pipelines that the commands included a hyphen character for the path. This character is a reference to standard input (STDIN). Here are the possible references and where they might occur.
Reference | Path | Data | Value | Notes |
---|---|---|---|---|
- |
✅(1) | ✅(1) | ✅ | This reference can only be used once (1) When used as the path or data parameter, the format must be supplied using the -in flag. |
@«filename» |
✅(2) | ✅(2) | ✅ | (2) When used as the path or data parameter, the file extension must be .hcl or .json OR the format must be supplied using the -in flag. |
For the next few examples, create a file named items.json using the following command.
echo '{"Items":{"item1":"value1", "item2":"value2"}}' > items.json
You can use this in as a file reference as the data parameter to create a variable with the items contained in the file.
nomad var put -out=pretty-json my/third/var @items.json
{
"Namespace": "default",
"Path": "my/third/var",
"CreateIndex": 1516,
"ModifyIndex": 1516,
"CreateTime": 1662064037167150000,
"ModifyTime": 1662064037167150000,
"Items": {
"item1": "value1",
"item2": "value2"
}
}
You can also pass key-value pairs when using a file reference for the variable data.
nomad var put -out pretty-json my/fourth/var @items.json item2="overridden"
{
"Namespace": "default",
"Path": "my/fourth/var",
"CreateIndex": 1521,
"ModifyIndex": 1521,
"CreateTime": 1662064246116265000,
"ModifyTime": 1662064246116265000,
"Items": {
"item1": "value1",
"item2": "overridden"
}
}
You can even delete items from the data reference before they are committed to the variable's data.
nomad var put -out pretty-json my/fifth/var @items.json item2=""
{
"Namespace": "default",
"Path": "my/fifth/var",
"CreateIndex": 1524,
"ModifyIndex": 1524,
"CreateTime": 1662064354522447000,
"ModifyTime": 1662064354522447000,
"Items": {
"item1": "value1"
}
}
You might have noticed in the previous examples that each command created a different variable. The nomad var put
command defaults to a "check and set" strategy when performing updates. This strategy requires that the incoming variable has the same Modify Index as the variable on the server, which helps to reduce the danger of concurrent modifications to a variable's value
In the earliest examples in this guide, the output of nomad var get
was piped into the nomad var put
command. This provides the nomad var put
command with the current ModifyIndex of the variable on the server.
There are two options for directly updating a variable without fetching the value as part of the update process.
-
Use the
-check-index
flag -
Use the
-force
flag
If your request does not have the proper ModifyIndex, you will receive a cas conflict
error. The error text will show the ModifyIndex you passed and the server-side ModifyIndex.
nomad var put my/fifth/var item1="updated"
Error creating variable: cas conflict: expected ModifyIndex 0; found 1524
You can provide the expected ModifyIndex with the -check-index
flag. Recall from earlier, the output generated when you put my/fifth/var
contained a ModifyIndex
value. The sample output in this guide has a ModifyIndex of 1524.
Use the correct check-index value based on the output generated from when you created my/fifth/var
and set item2="new"
nomad var put -check-index 1524 my/fifth/var item2="new"
{
"Namespace": "default",
"Path": "my/fifth/var",
"CreateIndex": 1524,
"ModifyIndex": 1540,
"CreateTime": 1662064354522447000,
"ModifyTime": 1662065159344723000,
"Items": {
"item2": "new"
}
}
Note: When putting a variable without a fetch, the Items array is OVERWRITTEN with the new values. If you want to update the variable's existing Items, you should get the existing state first—either as piped data or to a file that you then reference in the put.