Variables CLI documentation (#14249)
This commit is contained in:
Charlie Voiselle
GitHub
parent
03312f3227
commit
8eb1689fca
|
|
@ -0,0 +1,61 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: "Command: var get"
|
||||
description: |-
|
||||
The "var get" command retrieves the variable at the given path from
|
||||
Nomad. If no variable exists at that path, an error is returned.
|
||||
---
|
||||
|
||||
# Command: var get
|
||||
|
||||
The `var get` command is used to get the contents of an existing variable.
|
||||
|
||||
## Usage
|
||||
|
||||
```plaintext
|
||||
nomad var get [options] <path>
|
||||
```
|
||||
|
||||
If ACLs are enabled, this command requires a token with the `variables:read`
|
||||
capability for the target variable's namespace.
|
||||
|
||||
## General Options
|
||||
|
||||
@include 'general_options.mdx'
|
||||
|
||||
## Output Options
|
||||
|
||||
- `-item` `(string: "")`: Print only the value of the given item. Specifying
|
||||
this option will take precedence over other formatting directives. The result
|
||||
will not have a trailing newline making it ideal for piping to other
|
||||
processes.
|
||||
|
||||
- `-out` `(enum: go-template | hcl | json | none | table )`: Format to render the
|
||||
variable in. When using "go-template", you must provide the template content
|
||||
with the `-template` option. Defaults to "table" when stdout is a terminal and
|
||||
to "json" when stdout is redirected.
|
||||
|
||||
- `-template` `(string: "")` Template to render output with. Required when
|
||||
output is "go-template".
|
||||
|
||||
## 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
|
||||
```
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: "Commands: var"
|
||||
description: |-
|
||||
The "var" command groups subcommands for interacting with Nomad variables.
|
||||
---
|
||||
|
||||
# Command: var
|
||||
|
||||
The `var` command is used to interact with Nomad [variables].
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `nomad var <subcommand> [options] [args]`
|
||||
|
||||
Run `nomad var <subcommand> -h` for help on that subcommand. The following
|
||||
subcommands are available:
|
||||
|
||||
- [`var init`][init] - Create a variable specification file
|
||||
- [`var list`][list] - List variables the user has access to
|
||||
- [`var get`][get] - Retrieve a variable
|
||||
- [`var put`][put] - Insert or update a variable
|
||||
- [`var purge`][purge] - Permanently delete a variable
|
||||
|
||||
## Examples
|
||||
|
||||
Create or update the variable stored at the path "secret/creds", which contains
|
||||
an item named `passcode` with the value `my-long-passcode`.
|
||||
|
||||
```shell-session
|
||||
$ nomad var put -out=table secret/creds passcode=my-long-passcode
|
||||
Successfully created variable "secret/creds"!
|
||||
|
||||
Namespace = default
|
||||
Path = secret/creds
|
||||
Create Time = 2022-08-23T11:14:37-04:00
|
||||
Check Index = 116
|
||||
|
||||
Items
|
||||
passcode = my-long-passcode
|
||||
```
|
||||
|
||||
Update a value:
|
||||
```shell-session
|
||||
$ nomad var get secret/creds | nomad var put -in=json -out=table -v - user=dba
|
||||
Reading whole JSON variable specification from stdin
|
||||
Successfully updated variable "secret/creds"!
|
||||
|
||||
Namespace = default
|
||||
Path = secret/creds
|
||||
Create Time = 2022-08-23T11:14:37-04:00
|
||||
Check Index = 116
|
||||
|
||||
Items
|
||||
passcode = my-long-passcode
|
||||
user = dba
|
||||
```
|
||||
|
||||
[variables]: /docs/concepts/variables
|
||||
[init]: /docs/commands/var/init
|
||||
[get]: /docs/commands/var/get
|
||||
[list]: /docs/commands/var/list
|
||||
[put]: /docs/commands/var/put
|
||||
[purge]: /docs/commands/var/purge
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: 'Commands: var init'
|
||||
description: |
|
||||
Generate an example variable specification.
|
||||
---
|
||||
|
||||
# Command: var init
|
||||
|
||||
The `var init` creates an example variable specification file that can be used
|
||||
as a starting point to customize further.
|
||||
|
||||
## Usage
|
||||
|
||||
```plaintext
|
||||
nomad var init <filename>
|
||||
```
|
||||
|
||||
When no filename is supplied, a default filename of "spec.nv.hcl" or
|
||||
"spec.nv.json" will be used depending on the output format.
|
||||
|
||||
## Init Options
|
||||
|
||||
- `-out` `(enum: hcl | json)`: Format of generated variable
|
||||
specification. Defaults to `hcl`.
|
||||
|
||||
## Examples
|
||||
|
||||
Create an example variable specification:
|
||||
|
||||
```shell-session
|
||||
$ nomad var init
|
||||
Example variable specification written to spec.nv.hcl
|
||||
```
|
||||
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: "Command: var list"
|
||||
description: |-
|
||||
The "var list" command lists data from Nomad's variables datastore at
|
||||
or beginning with the given prefix.
|
||||
---
|
||||
|
||||
# Command: var list
|
||||
|
||||
The `var list` command returns a list of variable paths accessible to the
|
||||
current user, optionally filtered to paths containing a provided prefix. Do not
|
||||
encode sensitive information in variable paths. The variable's items are not
|
||||
accessible via this command.
|
||||
|
||||
When using pagination, the next page token is provided as part of the output of
|
||||
the command. When the output format is JSON, the returned variable list is
|
||||
wrapped with additional metadata that contains the next page token. For non-JSON
|
||||
output, the next page token is printed as a message to standard error and
|
||||
standard output contains the variables from the specifically requested page.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
```plaintext
|
||||
nomad var list [options] [<prefix>]
|
||||
```
|
||||
|
||||
If ACLs are enabled, this command requires the `variables:list` capability for
|
||||
the namespaces containing the variables to list.
|
||||
|
||||
## General Options
|
||||
|
||||
@include 'general_options.mdx'
|
||||
|
||||
## List Options
|
||||
|
||||
- `-per-page` `(int: <unset>)`: How many results to show per page.
|
||||
|
||||
- `-page-token` `(string: "")`: Where to start pagination.
|
||||
|
||||
- `-filter` `(string: "")`: Specifies an expression used to filter query
|
||||
results. Queries using this option are less efficient than using the prefix
|
||||
parameter; therefore, the prefix parameter should be used whenever possible.
|
||||
|
||||
- `-out` `(enum: go-template | json | table | terse )`: Format to render the
|
||||
variable in. When using "go-template", you must provide the template content
|
||||
with the `-template` option. Defaults to "table" when stdout is a terminal and
|
||||
to "json" when stdout is redirected.
|
||||
|
||||
- `-template` `(string: "")` Template to render output with. Required when
|
||||
output is "go-template".
|
||||
|
||||
## 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.
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: "Command: var purge"
|
||||
description: |-
|
||||
The "var purge" command permanently removes the specified variable
|
||||
from Nomad.
|
||||
---
|
||||
|
||||
# Command: var purge
|
||||
|
||||
The `var purge` command permanently deletes an existing variable from Nomad's
|
||||
variable storage.
|
||||
|
||||
## Usage
|
||||
|
||||
```plaintext
|
||||
nomad var purge [options] <path>
|
||||
```
|
||||
|
||||
The `var purge` command requires the path to the variable.
|
||||
|
||||
If ACLs are enabled, this command requires a token with the `variables:destroy`
|
||||
capability for the target variable's namespace.
|
||||
|
||||
## General Options
|
||||
|
||||
@include 'general_options.mdx'
|
||||
|
||||
## Command Options
|
||||
|
||||
- `-check-index` `(int: <unset>)`: If set, the variable is only acted upon if
|
||||
the server-side version's index matches the provided value. When a variable
|
||||
specification contains a modify index, that modify index is used as the
|
||||
check-index for the check-and-set operation and can be overridden using this
|
||||
flag.
|
||||
|
||||
## Examples
|
||||
|
||||
Purge the variable at the "secret/creds" path.
|
||||
|
||||
```shell-session
|
||||
$ nomad var purge -y secret/creds
|
||||
Successfully purged variable "secret/creds"!
|
||||
```
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: "Command: var put"
|
||||
description: |-
|
||||
The "var put" command writes a variable to the given path in Nomad.
|
||||
---
|
||||
|
||||
# Command: var put
|
||||
|
||||
The `var put` command creates or updates an existing variable.
|
||||
|
||||
## Usage
|
||||
|
||||
```plaintext
|
||||
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".
|
||||
|
||||
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
|
||||
string, an @-prefixed file reference, or a '-' to get the value from stdin. Item
|
||||
values provided from file references or stdin are consumed as-is with no
|
||||
additional processing and do not require the input format to be specified.
|
||||
|
||||
Values supplied as command line arguments supersede values provided in any
|
||||
variable specification piped into the command or loaded from file. If ACLs are
|
||||
enabled, this command requires the `variables:write` capability for the
|
||||
destination namespace.
|
||||
|
||||
## General Options
|
||||
|
||||
@include 'general_options.mdx'
|
||||
|
||||
## Put Options
|
||||
|
||||
- `-check-index` `(int: <unset>)`: If set, the variable is only acted upon if
|
||||
the server-side version's index matches the provided value. When a variable
|
||||
specification contains a modify index, that modify index is used as the
|
||||
check-index for the check-and-set operation and can be overridden using this
|
||||
flag.
|
||||
|
||||
- `-force`: Perform this operation regardless of the state or index of the
|
||||
variable on the server-side.
|
||||
|
||||
- `-in` `(enum: hcl | json)`: Parser to use for data supplied via standard input
|
||||
or when the variable specification's type can not be known using the file
|
||||
extension. Defaults to "json".
|
||||
|
||||
- `-out` `(enum: go-template | hcl | json | none | table)`: Format to render
|
||||
created or updated variable. Defaults to "none" when stdout is a terminal and
|
||||
"json" when the output is redirected.
|
||||
|
||||
- `-template` `(string: "")`: Template to render output with. Required when
|
||||
format is "go-template", invalid for other formats.
|
||||
|
||||
- `-verbose`: Provides additional information via standard error to preserve
|
||||
standard output (stdout) for redirected output.
|
||||
|
||||
## 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" | vault var put secret/foo bar=-
|
||||
```
|
||||
|
|
@ -904,6 +904,35 @@
|
|||
"title": "ui",
|
||||
"path": "commands/ui"
|
||||
},
|
||||
{
|
||||
"title": "var",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "commands/var"
|
||||
},
|
||||
{
|
||||
"title": "get",
|
||||
"path": "commands/var/get"
|
||||
},
|
||||
{
|
||||
"title": "init",
|
||||
"path": "commands/var/init"
|
||||
},
|
||||
{
|
||||
"title": "list",
|
||||
"path": "commands/var/list"
|
||||
},
|
||||
{
|
||||
"title": "put",
|
||||
"path": "commands/var/put"
|
||||
},
|
||||
{
|
||||
"title": "purge",
|
||||
"path": "commands/var/purge"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "version",
|
||||
"path": "commands/version"
|
||||
|
|
|
|||
Loading…
Reference in New Issue