From 8eb1689fca51e6c1a84a8216a401768e3ee2eb93 Mon Sep 17 00:00:00 2001 From: Charlie Voiselle <464492+angrycub@users.noreply.github.com> Date: Mon, 12 Sep 2022 16:44:31 -0400 Subject: [PATCH] Variables CLI documentation (#14249) --- website/content/docs/commands/var/get.mdx | 61 +++++++++ website/content/docs/commands/var/index.mdx | 64 +++++++++ website/content/docs/commands/var/init.mdx | 34 +++++ website/content/docs/commands/var/list.mdx | 137 ++++++++++++++++++++ website/content/docs/commands/var/purge.mdx | 44 +++++++ website/content/docs/commands/var/put.mdx | 87 +++++++++++++ website/data/docs-nav-data.json | 29 +++++ 7 files changed, 456 insertions(+) create mode 100644 website/content/docs/commands/var/get.mdx create mode 100644 website/content/docs/commands/var/index.mdx create mode 100644 website/content/docs/commands/var/init.mdx create mode 100644 website/content/docs/commands/var/list.mdx create mode 100644 website/content/docs/commands/var/purge.mdx create mode 100644 website/content/docs/commands/var/put.mdx diff --git a/website/content/docs/commands/var/get.mdx b/website/content/docs/commands/var/get.mdx new file mode 100644 index 000000000..3b91e15cc --- /dev/null +++ b/website/content/docs/commands/var/get.mdx @@ -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] +``` + +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 +``` diff --git a/website/content/docs/commands/var/index.mdx b/website/content/docs/commands/var/index.mdx new file mode 100644 index 000000000..87daebef5 --- /dev/null +++ b/website/content/docs/commands/var/index.mdx @@ -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 [options] [args]` + +Run `nomad var -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 diff --git a/website/content/docs/commands/var/init.mdx b/website/content/docs/commands/var/init.mdx new file mode 100644 index 000000000..8d4f0f0a4 --- /dev/null +++ b/website/content/docs/commands/var/init.mdx @@ -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 +``` + +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 +``` diff --git a/website/content/docs/commands/var/list.mdx b/website/content/docs/commands/var/list.mdx new file mode 100644 index 000000000..f11c07e7d --- /dev/null +++ b/website/content/docs/commands/var/list.mdx @@ -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] [] +``` + +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: )`: 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. diff --git a/website/content/docs/commands/var/purge.mdx b/website/content/docs/commands/var/purge.mdx new file mode 100644 index 000000000..22f252741 --- /dev/null +++ b/website/content/docs/commands/var/purge.mdx @@ -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] +``` + +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: )`: 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"! +``` diff --git a/website/content/docs/commands/var/put.mdx b/website/content/docs/commands/var/put.mdx new file mode 100644 index 000000000..9a508fbf2 --- /dev/null +++ b/website/content/docs/commands/var/put.mdx @@ -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] [=]... +nomad var put [options] [] [=]... +``` + +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: )`: 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=- +``` diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index c97243e69..aa52eecd6 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -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"