From 587360543b2ca8f6e4bd9ee0bc55eb8ac5eea3e0 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Wed, 20 Jul 2022 14:14:10 -0400 Subject: [PATCH] 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. --- ...erator_secure_variables_keyring_install.go | 18 ++------ .../operator/gossip/keyring-generate.mdx | 36 +++++++++++++++ .../operator/gossip/keyring-install.mdx | 36 +++++++++++++++ .../commands/operator/gossip/keyring-list.mdx | 41 +++++++++++++++++ .../operator/gossip/keyring-remove.mdx | 40 ++++++++++++++++ .../commands/operator/gossip/keyring-use.mdx | 36 +++++++++++++++ .../content/docs/commands/operator/keygen.mdx | 4 ++ .../docs/commands/operator/keyring.mdx | 4 ++ .../secure-variables/keyring-install.mdx | 33 +++++++++++++ .../secure-variables/keyring-list.mdx | 42 +++++++++++++++++ .../secure-variables/keyring-remove.mdx | 34 ++++++++++++++ .../secure-variables/keyring-rotate.mdx | 43 +++++++++++++++++ website/data/docs-nav-data.json | 46 +++++++++++++++++++ 13 files changed, 400 insertions(+), 13 deletions(-) create mode 100644 website/content/docs/commands/operator/gossip/keyring-generate.mdx create mode 100644 website/content/docs/commands/operator/gossip/keyring-install.mdx create mode 100644 website/content/docs/commands/operator/gossip/keyring-list.mdx create mode 100644 website/content/docs/commands/operator/gossip/keyring-remove.mdx create mode 100644 website/content/docs/commands/operator/gossip/keyring-use.mdx create mode 100644 website/content/docs/commands/operator/secure-variables/keyring-install.mdx create mode 100644 website/content/docs/commands/operator/secure-variables/keyring-list.mdx create mode 100644 website/content/docs/commands/operator/secure-variables/keyring-remove.mdx create mode 100644 website/content/docs/commands/operator/secure-variables/keyring-rotate.mdx diff --git a/command/operator_secure_variables_keyring_install.go b/command/operator_secure_variables_keyring_install.go index fc8031538..4657a92a4 100644 --- a/command/operator_secure_variables_keyring_install.go +++ b/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] - 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 diff --git a/website/content/docs/commands/operator/gossip/keyring-generate.mdx b/website/content/docs/commands/operator/gossip/keyring-generate.mdx new file mode 100644 index 000000000..d703f46ae --- /dev/null +++ b/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 diff --git a/website/content/docs/commands/operator/gossip/keyring-install.mdx b/website/content/docs/commands/operator/gossip/keyring-install.mdx new file mode 100644 index 000000000..e30c21b5b --- /dev/null +++ b/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] +``` + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Examples + +```shell-session +$ nomad operator gossip keyring install AOUfjGff+MrTBzNU7NCOTmYajKRkGv8r2ToxheWd+jk= +Installing new gossip encryption key... +``` diff --git a/website/content/docs/commands/operator/gossip/keyring-list.mdx b/website/content/docs/commands/operator/gossip/keyring-list.mdx new file mode 100644 index 000000000..e05d940bd --- /dev/null +++ b/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= +``` diff --git a/website/content/docs/commands/operator/gossip/keyring-remove.mdx b/website/content/docs/commands/operator/gossip/keyring-remove.mdx new file mode 100644 index 000000000..97009d769 --- /dev/null +++ b/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] +``` + +## 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... +``` diff --git a/website/content/docs/commands/operator/gossip/keyring-use.mdx b/website/content/docs/commands/operator/gossip/keyring-use.mdx new file mode 100644 index 000000000..708b50678 --- /dev/null +++ b/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] +``` + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Examples + +```shell-session +$ nomad operator gossip keyring use HD5Y61iE+neTxd1n6TnXhCPViPIUq5QpWq8WW8012XA= +Changing primary gossip encryption key... +``` diff --git a/website/content/docs/commands/operator/keygen.mdx b/website/content/docs/commands/operator/keygen.mdx index e12e18997..35347abda 100644 --- a/website/content/docs/commands/operator/keygen.mdx +++ b/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. diff --git a/website/content/docs/commands/operator/keyring.mdx b/website/content/docs/commands/operator/keyring.mdx index 4a4200cb9..d9bfb1394 100644 --- a/website/content/docs/commands/operator/keyring.mdx +++ b/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 diff --git a/website/content/docs/commands/operator/secure-variables/keyring-install.mdx b/website/content/docs/commands/operator/secure-variables/keyring-install.mdx new file mode 100644 index 000000000..b2e11fabb --- /dev/null +++ b/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] +``` + +## 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 +``` diff --git a/website/content/docs/commands/operator/secure-variables/keyring-list.mdx b/website/content/docs/commands/operator/secure-variables/keyring-list.mdx new file mode 100644 index 000000000..be2b63c19 --- /dev/null +++ b/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 +``` diff --git a/website/content/docs/commands/operator/secure-variables/keyring-remove.mdx b/website/content/docs/commands/operator/secure-variables/keyring-remove.mdx new file mode 100644 index 000000000..1a3dc6f21 --- /dev/null +++ b/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] +``` + +## 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 +``` diff --git a/website/content/docs/commands/operator/secure-variables/keyring-rotate.mdx b/website/content/docs/commands/operator/secure-variables/keyring-rotate.mdx new file mode 100644 index 000000000..6e0f4bd33 --- /dev/null +++ b/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 +``` diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 16793bef5..591884f5d 100644 --- a/website/data/docs-nav-data.json +++ b/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": [