docs: keyring commands (#13690)

Document the secure variables keyring commands, document the aliased
gossip keyring commands, and note that the old gossip keyring commands
are deprecated.

command/operator_secure_variables_keyring_install.go

@@ -23,22 +23,17 @@ func (c *OperatorSecureVariablesKeyringInstallCommand) Help() string {
 	helpText := `
 Usage: nomad operator secure-variables keyring install [options] <filepath>
 
-  Install a new encryption key used for storage secure variables. The key file
-  must be a JSON file previously written by Nomad to the keystore. The key
-  file will be read from stdin by specifying "-", otherwise a path to the file
-  is expected.
+  Install a new encryption key used for storing secure variables and workload
+  identity signing. The key file must be a JSON file previously written by Nomad
+  to the keystore. The key file will be read from stdin by specifying "-",
+  otherwise a path to the file is expected.
 
   If ACLs are enabled, this command requires a management token.
 
 General Options:
 
-  ` + generalOptionsUsage(usageOptsDefault|usageOptsNoNamespace) + `
+  ` + generalOptionsUsage(usageOptsDefault|usageOptsNoNamespace)
 
-Keyring Options:
-
-  -verbose
-    Show full information.
-`
 	return strings.TrimSpace(helpText)
 }
 
@@ -61,11 +56,8 @@ func (c *OperatorSecureVariablesKeyringInstallCommand) Name() string {
 }
 
 func (c *OperatorSecureVariablesKeyringInstallCommand) Run(args []string) int {
-	var verbose bool
-
 	flags := c.Meta.FlagSet("secure-variables keyring install", FlagSetClient)
 	flags.Usage = func() { c.Ui.Output(c.Help()) }
-	flags.BoolVar(&verbose, "verbose", false, "")
 
 	if err := flags.Parse(args); err != nil {
 		return 1

website/content/docs/commands/operator/gossip/keyring-generate.mdx

@@ -0,0 +1,36 @@
+---
+layout: docs
+page_title: 'Commands: operator gossip keyring generate'
+description: >
+  The `operator gossip keyring generate` command generates an encryption key that can be used for
+  Nomad server's gossip traffic encryption. The keygen command uses a
+  cryptographically strong pseudo-random number generator to generate the key.
+---
+
+# Command: operator gossip keyring generate
+
+The `operator gossip keyring generate` command generates an encryption
+key that can be used for Nomad server's gossip traffic encryption. The
+keygen command uses a cryptographically strong pseudo-random number
+generator to generate the key.
+
+The resulting key is encoded in the [RFC4648] "URL and filename safe"
+base64 alphabet. If you use another tool such as OpenSSL to generate
+the gossip key, you should pipe the input through the `base64(1)`
+command to ensure it is safely encoded. For example: `openssl rand 32
+| base64`
+
+## Usage
+
+```plaintext
+nomad operator gossip keyring generate
+```
+
+## Example
+
+```shell-session
+$ nomad operator gossip keyring generate
+6RhfKFZ5uYEaU6RgWzx69ssLcpiIkvnEZs5KBOQxvxA=
+```
+
+[rfc4648]: https://tools.ietf.org/html/rfc4648#section-5

website/content/docs/commands/operator/gossip/keyring-install.mdx

@@ -0,0 +1,36 @@
+---
+layout: docs
+page_title: 'Commands: operator gossip keyring install'
+description: |
+  Install a new gossip encryption key
+---
+
+# Command: operator gossip keyring install
+
+The `operator gossip keyring install` command is used to install a new
+encryption key used for gossip. This will broadcast the new key to all
+members in the cluster.
+
+This command can only be run against server nodes. It returns 0 if all nodes
+reply and there are no errors. If any node fails to reply or reports failure,
+the exit code will be 1.
+
+If ACLs are enabled, this command requires a token with the `agent:write`
+capability.
+
+## Usage
+
+```plaintext
+nomad operator gossip keyring install [options] <key>
+```
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## Examples
+
+```shell-session
+$ nomad operator gossip keyring install AOUfjGff+MrTBzNU7NCOTmYajKRkGv8r2ToxheWd+jk=
+Installing new gossip encryption key...
+```

website/content/docs/commands/operator/gossip/keyring-list.mdx

@@ -0,0 +1,41 @@
+---
+layout: docs
+page_title: 'Commands: operator gossip keyring list'
+description: |
+  List gossip keys
+---
+
+# Command: operator gossip keyring list
+
+The `operator gossip keyring list` command lists all gossip keys
+currently in use within the cluster.
+
+This command can only be run against server nodes. It returns 0 if all
+nodes reply and there are no errors. If any node fails to reply or
+reports failure, the exit code will be 1.
+
+If ACLs are enabled, this command requires a token with the
+`agent:write` capability.
+
+## Usage
+
+```plaintext
+nomad operator gossip keyring list [options]
+```
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## Examples
+
+The output of the `nomad operator gossip keyring list` command
+consolidates information from all the Nomad servers.
+
+```shell-session
+$ nomad operator gossip keyring list
+Gathering installed encryption keys...
+Key
+HD5Y61iE+neTxd1n6TnXhCPViPIUq5QpWq8WW8012XA=
+AOUfjGff+MrTBzNU7NCOTmYajKRkGv8r2ToxheWd+jk=
+```

website/content/docs/commands/operator/gossip/keyring-remove.mdx

@@ -0,0 +1,40 @@
+---
+layout: docs
+page_title: 'Commands: operator gossip keyring remove'
+description: |
+  Remove a new gossip encryption key
+---
+
+# Command: operator gossip keyring remove
+
+The `operator gossip keyring remove` command removes the given key
+from the cluster. This operation may only be performed on keys which
+are not currently the primary key.
+
+This command can only be run against server nodes. It returns 0 if all nodes
+reply and there are no errors. If any node fails to reply or reports failure,
+the exit code will be 1.
+
+If ACLs are enabled, this command requires a token with the `agent:write`
+capability.
+
+## Usage
+
+```plaintext
+nomad operator gossip keyring remove [options] <key>
+```
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## Examples
+
+```shell-session
+$ nomad operator gossip keyring remove HD5Y61iE+neTxd1n6TnXhCPViPIUq5QpWq8WW8012XA=
+Removing gossip encryption key...
+error: Unexpected response code: 500 (3/3 nodes reported failure)
+
+$ nomad operator gossip keyring remove AOUfjGff+MrTBzNU7NCOTmYajKRkGv8r2ToxheWd+jk=
+Removing gossip encryption key...
+```

website/content/docs/commands/operator/gossip/keyring-use.mdx

@@ -0,0 +1,36 @@
+---
+layout: docs
+page_title: 'Commands: operator gossip keyring use'
+description: |
+  Use a new gossip encryption key
+---
+
+# Command: operator gossip keyring use
+
+The `operator gossip keyring use` command changes the encryption key
+used for gossip. The key must already be installed before this
+operation can succeed.
+
+This command can only be run against server nodes. It returns 0 if all nodes
+reply and there are no errors. If any node fails to reply or reports failure,
+the exit code will be 1.
+
+If ACLs are enabled, this command requires a token with the `agent:write`
+capability.
+
+## Usage
+
+```plaintext
+nomad operator gossip keyring use [options] <key>
+```
+
+## General Options
+
+@include 'general_options_no_namespace.mdx'
+
+## Examples
+
+```shell-session
+$ nomad operator gossip keyring use HD5Y61iE+neTxd1n6TnXhCPViPIUq5QpWq8WW8012XA=
+Changing primary gossip encryption key...
+```

website/content/docs/commands/operator/keygen.mdx

@@ -9,6 +9,10 @@ description: >
 
 # Command: operator keygen
 
+~> **Warning:** This command is deprecated and will be removed in
+   Nomad 1.5.0. Use the `nomad operator gossip keyring generate`
+   subcommand instead.
+
 The `operator keygen` command generates an encryption key that can be used for
 Nomad server's gossip traffic encryption. The keygen command uses a
 cryptographically strong pseudo-random number generator to generate the key.

website/content/docs/commands/operator/keyring.mdx

@@ -5,6 +5,10 @@ page_title: 'Commands: operator keyring'
 
 # Command: operator keyring
 
+~> **Warning:** This command is deprecated and will be removed in
+   Nomad 1.5.0. Use the `nomad operator gossip keyring` subcommands
+   instead.
+
 The `operator keyring` command is used to examine and modify the encryption keys
 used in Nomad server. It is capable of distributing new encryption keys to the
 cluster, retiring old encryption keys, and changing the keys used by the cluster

website/content/docs/commands/operator/secure-variables/keyring-install.mdx

@@ -0,0 +1,33 @@
+---
+layout: docs
+page_title: 'Commands: operator secure-variables keyring install'
+description: |
+  Install an encryption key
+---
+
+# Command: operator secure-variables keyring install
+
+The `operator secure-variables keyring install` command installs a new
+encryption key used for secure variables and workload identity
+signing. The key file must be a JSON file previously written by Nomad
+to the keystore. The key file will be read from stdin by specifying
+"-", otherwise a path to the file is expected.
+
+If ACLs are enabled, this command requires a management token.
+
+## Usage
+
+```plaintext
+nomad operator secure-variables keyring install [options] <filepath>
+```
+
+## General Options
+
+@include 'general_options.mdx'
+
+## Examples
+
+```shell-session
+$ nomad operator secure-variables keyring install ./14ba0470-a5b4-41f4-a1e4-83b4c82d1324.nks.json
+Installed encryption key 14ba0470-a5b4-41f4-a1e4-83b4c82d1324
+```

website/content/docs/commands/operator/secure-variables/keyring-list.mdx

@@ -0,0 +1,42 @@
+---
+layout: docs
+page_title: 'Commands: operator secure-variables keyring list'
+description: |
+  List encryption key metadata
+---
+
+# Command: operator secure-variables keyring list
+
+The `operator secure-variables keyring list` command lists the
+currently installed keys. This list returns key metadata and not
+sensitive key material.
+
+If ACLs are enabled, this command requires a management token.
+
+## Usage
+
+```plaintext
+nomad operator secure-variables keyring list [options]
+```
+
+## General Options
+
+@include 'general_options.mdx'
+
+## List Options
+
+- `-verbose`: Enable verbose output
+
+## Examples
+
+```shell-session
+$ nomad operator secure-variables keyring list
+Key       State     Create Time
+33374156  active    2022-07-11T19:11:07Z
+8d87a371  inactive  2022-07-11T19:10:37Z
+
+$ nomad operator secure-variables keyring list -verbose
+Key                                   State     Create Time
+33374156-9f81-b14c-83d4-a2f1f87dbf99  active    2022-07-11T19:11:07Z
+8d87a371-3594-e1e4-8ae1-3980122b0f25  inactive  2022-07-11T19:10:37Z
+```

website/content/docs/commands/operator/secure-variables/keyring-remove.mdx

@@ -0,0 +1,34 @@
+---
+layout: docs
+page_title: 'Commands: operator secure-variables keyring remove'
+description: |
+  Remove an unused encryption key
+---
+
+# Command: operator secure-variables keyring remove
+
+The `operator secure-variables keyring remove` command removes an
+encryption key from the cluster. This operation may only be performed
+on keys that are not the active key.
+
+If ACLs are enabled, this command requires a management token.
+
+## Usage
+
+```plaintext
+nomad operator secure-variables keyring remove [options] <key ID>
+```
+
+## General Options
+
+@include 'general_options.mdx'
+
+## Examples
+
+```shell-session
+$ nomad operator secure-variables keyring remove 48596ce5-3ff5-8f77-2dcf-301682ada0ce
+error: Unexpected response code: 500 (active root key cannot be deleted - call rotate first)
+
+$ nomad operator secure-variables keyring remove 33374156-9f81-b14c-83d4-a2f1f87dbf99
+Removed encryption key 33374156-9f81-b14c-83d4-a2f1f87dbf99
+```

website/content/docs/commands/operator/secure-variables/keyring-rotate.mdx

@@ -0,0 +1,43 @@
+---
+layout: docs
+page_title: 'Commands: operator secure-variables keyring rotate'
+description: |
+  Rotate encryption key
+---
+
+# Command: operator secure-variables keyring rotate
+
+The `operator secure-variables keyring rotate` command generates a new
+encryption key for all future variables.
+
+If ACLs are enabled, this command requires a management token.
+
+## Usage
+
+```plaintext
+nomad operator secure-variables keyring rotate [options]
+```
+
+## General Options
+
+@include 'general_options.mdx'
+
+## Rotate Options
+
+- `-full`: Decrypt all existing variables and re-encrypt with the new
+    key. This command will immediately return and the re-encryption
+    process will run asynchronously on the leader.
+
+- `-verbose`: Enable verbose output
+
+## Examples
+
+```shell-session
+$ nomad operator secure-variables keyring rotate
+Key       State   Create Time
+f19f6029  active  2022-07-11T19:14:36Z
+
+$ nomad operator secure-variables keyring rotate -verbose
+Key                                   State   Create Time
+53186ac1-9002-c4b6-216d-bb19fd37a791  active  2022-07-11T19:14:47Z
+```

website/data/docs-nav-data.json

@@ -562,6 +562,31 @@
             "title": "debug",
             "path": "commands/operator/debug"
           },
+          {
+            "title": "gossip",
+            "routes": [
+              {
+                "title": "keyring generate",
+                "path": "commands/operator/gossip/keyring-generate"
+              },
+              {
+                "title": "keyring install",
+                "path": "commands/operator/gossip/keyring-install"
+              },
+              {
+                "title": "keyring list",
+                "path": "commands/operator/gossip/keyring-list"
+              },
+              {
+                "title": "keyring remove",
+                "path": "commands/operator/gossip/keyring-remove"
+              },
+              {
+                "title": "keyring use",
+                "path": "commands/operator/gossip/keyring-use"
+              }
+            ]
+          },
           {
             "title": "keygen",
             "path": "commands/operator/keygen"
@@ -612,6 +637,27 @@
               }
             ]
           },
+          {
+            "title": "secure-variables",
+            "routes": [
+              {
+                "title": "keyring install",
+                "path": "commands/operator/secure-variables/keyring-install"
+              },
+              {
+                "title": "keyring list",
+                "path": "commands/operator/secure-variables/keyring-list"
+              },
+              {
+                "title": "keyring remove",
+                "path": "commands/operator/secure-variables/keyring-remove"
+              },
+              {
+                "title": "keyring rotate",
+                "path": "commands/operator/secure-variables/keyring-rotate"
+              }
+            ]
+          },
           {
             "title": "snapshot",
             "routes": [