diff --git a/.changelog/16068.txt b/.changelog/16068.txt new file mode 100644 index 000000000..8056e9bc9 --- /dev/null +++ b/.changelog/16068.txt @@ -0,0 +1,3 @@ +```release-note:breaking-change +cli: The deprecated gossip keyring commands `nomad operator keyring`, `nomad keyring`, `nomad operator keygen`, and `nomad keygen` have been removed. Use the `nomad operator gossip keyring` commands to manage the gossip keyring +``` diff --git a/command/commands.go b/command/commands.go index 1eac75833..976f0ab0d 100644 --- a/command/commands.go +++ b/command/commands.go @@ -630,18 +630,6 @@ func Commands(metaPtr *Meta, agentUi cli.Ui) map[string]cli.CommandFactory { Meta: meta, }, nil }, - - // COMPAT(1.4.0): deprecated, remove in Nomad 1.5.0 - // Note: we can't just put this in the DeprecatedCommand list - // because the flags have changed too. So we've provided the - // deprecation warning in the original command and when it's - // time to remove it we can remove the entire command - "operator keyring": func() (cli.Command, error) { - return &OperatorKeyringCommand{ - Meta: meta, - }, nil - }, - "operator gossip keyring": func() (cli.Command, error) { return &OperatorGossipKeyringCommand{ Meta: meta, @@ -1152,39 +1140,6 @@ func Commands(metaPtr *Meta, agentUi cli.Ui) map[string]cli.CommandFactory { }, nil }, - "keygen": func() (cli.Command, error) { - return &DeprecatedCommand{ - Old: "keygen", - New: "operator gossip keyring generate", - Meta: meta, - Command: &OperatorGossipKeyringGenerateCommand{ - Meta: meta, - }, - }, nil - }, - - "operator keygen": func() (cli.Command, error) { - return &DeprecatedCommand{ - Old: "operator keygen", - New: "operator gossip keyring generate", - Meta: meta, - Command: &OperatorGossipKeyringGenerateCommand{ - Meta: meta, - }, - }, nil - }, - - "keyring": func() (cli.Command, error) { - return &DeprecatedCommand{ - Old: "keyring", - New: "operator gossip keyring", - Meta: meta, - Command: &OperatorKeyringCommand{ - Meta: meta, - }, - }, nil - }, - "server-force-leave": func() (cli.Command, error) { return &DeprecatedCommand{ Old: "server-force-leave", diff --git a/command/operator_gossip_keyring_generate.go b/command/operator_gossip_keyring_generate.go index ab4016201..ca78fdfc5 100644 --- a/command/operator_gossip_keyring_generate.go +++ b/command/operator_gossip_keyring_generate.go @@ -20,7 +20,6 @@ func (c *OperatorGossipKeyringGenerateCommand) Synopsis() string { func (c *OperatorGossipKeyringGenerateCommand) Help() string { helpText := ` Usage: nomad operator gossip keying generate -Alias: nomad operator keygen Generates a new 32-byte encryption key that can be used to configure the agent to encrypt traffic. The output of this command is already diff --git a/command/operator_keyring.go b/command/operator_keyring.go deleted file mode 100644 index dfdc60244..000000000 --- a/command/operator_keyring.go +++ /dev/null @@ -1,182 +0,0 @@ -package command - -import ( - "fmt" - "strings" - - "github.com/hashicorp/nomad/api" - "github.com/mitchellh/cli" - "github.com/posener/complete" -) - -// OperatorKeyringCommand is a Command implementation that handles querying, installing, -// and removing gossip encryption keys from a keyring. -type OperatorKeyringCommand struct { - Meta -} - -func (c *OperatorKeyringCommand) Help() string { - helpText := ` -Usage: nomad operator keyring [options] - - Manages encryption keys used for gossip messages between Nomad servers. Gossip - encryption is optional. When enabled, this command may be used to examine - active encryption keys in the cluster, add new keys, and remove old ones. When - combined, this functionality provides the ability to perform key rotation - cluster-wide, without disrupting the cluster. - - All operations performed by this command can only be run against server nodes. - - All variations of the keyring command return 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. - -General Options: - - ` + generalOptionsUsage(usageOptsDefault|usageOptsNoNamespace) + ` - -Keyring Options: - - -install= Install a new encryption key. This will broadcast - the new key to all members in the cluster. - -list List all keys currently in use within the cluster. - -remove= Remove the given key from the cluster. This - operation may only be performed on keys which are - not currently the primary key. - -use= Change the primary encryption key, which is used to - encrypt messages. The key must already be installed - before this operation can succeed. -` - return strings.TrimSpace(helpText) -} - -func (c *OperatorKeyringCommand) Synopsis() string { - return "Manages gossip layer encryption keys" -} - -func (c *OperatorKeyringCommand) AutocompleteFlags() complete.Flags { - return mergeAutocompleteFlags(c.Meta.AutocompleteFlags(FlagSetClient), - complete.Flags{ - "-install": complete.PredictAnything, - "-list": complete.PredictNothing, - "-remove": complete.PredictAnything, - "-use": complete.PredictAnything, - }) -} -func (c *OperatorKeyringCommand) AutocompleteArgs() complete.Predictor { - return complete.PredictNothing -} - -func (c *OperatorKeyringCommand) Name() string { return "operator keyring" } - -func (c *OperatorKeyringCommand) Run(args []string) int { - var installKey, useKey, removeKey string - var listKeys bool - - flags := c.Meta.FlagSet("operator-keyring", FlagSetClient) - flags.Usage = func() { c.Ui.Output(c.Help()) } - - flags.StringVar(&installKey, "install", "", "install key") - flags.StringVar(&useKey, "use", "", "use key") - flags.StringVar(&removeKey, "remove", "", "remove key") - flags.BoolVar(&listKeys, "list", false, "list keys") - - if err := flags.Parse(args); err != nil { - return 1 - } - - c.Ui.Warn(wrapAtLength("WARNING! The \"nomad operator keyring\" command " + - "is deprecated. Please use \"nomad operator gossip keyring\" instead. " + - "This command will be removed in Nomad 1.5.0.")) - c.Ui.Warn("") - c.Ui = &cli.PrefixedUi{ - OutputPrefix: "", - InfoPrefix: "==> ", - ErrorPrefix: "", - Ui: c.Ui, - } - - // Only accept a single argument - found := listKeys - for _, arg := range []string{installKey, useKey, removeKey} { - if found && len(arg) > 0 { - c.Ui.Error("Only a single action is allowed") - c.Ui.Error(commandErrorText(c)) - return 1 - } - found = found || len(arg) > 0 - } - - // Fail fast if no actionable args were passed - if !found { - c.Ui.Error("No actionable argument was passed") - c.Ui.Error("Either the '-install', '-use', '-remove' or '-list' flag must be set") - c.Ui.Error(commandErrorText(c)) - return 1 - } - - // All other operations will require a client connection - client, err := c.Meta.Client() - if err != nil { - c.Ui.Error(fmt.Sprintf("Error creating nomad cli client: %s", err)) - return 1 - } - - if listKeys { - c.Ui.Output("Gathering installed encryption keys...") - r, err := client.Agent().ListKeys() - if err != nil { - c.Ui.Error(fmt.Sprintf("error: %s", err)) - return 1 - } - c.handleKeyResponse(r) - return 0 - } - - if installKey != "" { - c.Ui.Output("Installing new gossip encryption key...") - _, err := client.Agent().InstallKey(installKey) - if err != nil { - c.Ui.Error(fmt.Sprintf("error: %s", err)) - return 1 - } - return 0 - } - - if useKey != "" { - c.Ui.Output("Changing primary gossip encryption key...") - _, err := client.Agent().UseKey(useKey) - if err != nil { - c.Ui.Error(fmt.Sprintf("error: %s", err)) - return 1 - } - return 0 - } - - if removeKey != "" { - c.Ui.Output("Removing gossip encryption key...") - _, err := client.Agent().RemoveKey(removeKey) - if err != nil { - c.Ui.Error(fmt.Sprintf("error: %s", err)) - return 1 - } - return 0 - } - - // Should never make it here - return 0 -} - -func (c *OperatorKeyringCommand) handleKeyResponse(resp *api.KeyringResponse) { - out := make([]string, len(resp.Keys)+1) - out[0] = "Key" - i := 1 - for k := range resp.Keys { - out[i] = k - i = i + 1 - } - c.Ui.Output(formatList(out)) -} diff --git a/main.go b/main.go index 9102b0366..1950b6a15 100644 --- a/main.go +++ b/main.go @@ -37,8 +37,6 @@ var ( "debug", "eval-status", "executor", - "keygen", - "keyring", "logmon", "node-drain", "node-status", diff --git a/website/content/docs/commands/operator/index.mdx b/website/content/docs/commands/operator/index.mdx index 4a084dc86..fd097a007 100644 --- a/website/content/docs/commands/operator/index.mdx +++ b/website/content/docs/commands/operator/index.mdx @@ -32,9 +32,15 @@ The following subcommands are available: - [`operator debug`][debug] - Build an archive of debug data -- [`operator keygen`][keygen] - Generates a new encryption key +- [`operator gossip keyring generate`][gossip_keyring_generate] - Generates a gossip encryption key -- [`operator keyring`][keyring] - Manages gossip layer encryption keys +- [`operator gossip keyring install`][gossip_keyring_install] - Install a gossip encryption key + +- [`operator gossip keyring list`][gossip_keyring_list] - List available gossip encryption keys + +- [`operator gossip keyring remove`][gossip_keyring_remove] - Deletes a gossip encryption key + +- [`operator gossip keyring use`][gossip_keyring_use] - Sets a gossip encryption key as the active key - [`operator raft list-peers`][list] - Display the current Raft peer configuration @@ -42,6 +48,12 @@ The following subcommands are available: - [`operator raft remove-peer`][remove] - Remove a Nomad server from the Raft configuration +- [`operator root keyring list`][root_keyring_list] - List available root encryption keys + +- [`operator root keyring remove`][root_keyring_remove] - Deletes a root encryption key + +- [`operator root keyring rotate`][root_keyring_rotate] - Rotates the root encryption key + - [`operator scheduler get-config`][scheduler-get-config] - Display the current scheduler configuration @@ -58,12 +70,18 @@ The following subcommands are available: [debug]: /nomad/docs/commands/operator/debug 'Builds an archive of configuration and state' [get-config]: /nomad/docs/commands/operator/autopilot/get-config 'Autopilot Get Config command' -[keygen]: /nomad/docs/commands/operator/keygen 'Generates a new encryption key' -[keyring]: /nomad/docs/commands/operator/keyring 'Manages gossip layer encryption keys' +[gossip_keyring_generate]: /nomad/docs/commands/operator/gossip/keyring-generate 'Generates a gossip encryption key' +[gossip_keyring_install]: /nomad/docs/commands/operator/gossip/keyring-install 'Install a gossip encryption key' +[gossip_keyring_list]: /nomad/docs/commands/operator/gossip/keyring-list 'List available gossip encryption keys' +[gossip_keyring_remove]: /nomad/docs/commands/operator/gossip/keyring-remove 'Deletes a gossip encryption key' +[gossip_keyring_use]: /nomad/docs/commands/operator/gossip/keyring-use 'Sets a gossip encryption key as the active key' [list]: /nomad/docs/commands/operator/raft/list-peers 'Raft List Peers command' [operator]: /nomad/api-docs/operator 'Operator API documentation' [outage recovery guide]: /nomad/tutorials/manage-clusters/outage-recovery [remove]: /nomad/docs/commands/operator/raft/remove-peer 'Raft Remove Peer command' +[root_keyring_list]: /nomad/docs/commands/operator/root/keyring-list 'List available root encryption keys' +[root_keyring_remove]: /nomad/docs/commands/operator/root/keyring-remove 'Deletes a root encryption key' +[root_keyring_rotate]: /nomad/docs/commands/operator/root/keyring-rotate 'Rotates the root encryption key' [set-config]: /nomad/docs/commands/operator/autopilot/set-config 'Autopilot Set Config command' [snapshot-save]: /nomad/docs/commands/operator/snapshot/save 'Snapshot Save command' [snapshot-restore]: /nomad/docs/commands/operator/snapshot/restore 'Snapshot Restore command' diff --git a/website/content/docs/commands/operator/keygen.mdx b/website/content/docs/commands/operator/keygen.mdx deleted file mode 100644 index 35347abda..000000000 --- a/website/content/docs/commands/operator/keygen.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: docs -page_title: 'Commands: operator keygen' -description: > - 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. ---- - -# 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. - -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 keygen -``` - -## Example - -```shell-session -$ nomad operator keygen -6RhfKFZ5uYEaU6RgWzx69ssLcpiIkvnEZs5KBOQxvxA= -``` - -[rfc4648]: https://tools.ietf.org/html/rfc4648#section-5 diff --git a/website/content/docs/commands/operator/keyring.mdx b/website/content/docs/commands/operator/keyring.mdx deleted file mode 100644 index ae637d471..000000000 --- a/website/content/docs/commands/operator/keyring.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -layout: docs -page_title: 'Commands: operator keyring' -description: |- - The `operator keyring` command is used to examine and - modify the encryption keys used in Nomad server. It can - also distribute new keys and retire old ones. ---- - -# 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 -to encrypt messages. - -Nomad allows multiple encryption keys to be in use simultaneously. This is -intended to provide a transition state while the cluster converges. It is the -responsibility of the operator to ensure that only the required encryption keys -are installed on the cluster. You can review the installed keys using the -`-list` argument, and remove unneeded keys with `-remove`. - -All operations performed by this command can only be run against server nodes -and will effect the entire cluster. - -All variations of the `keyring` command return 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 keyring [options] -``` - -Only one actionable argument may be specified per run, including `-list`, -`-install`, `-remove`, and `-use`. - -## General Options - -@include 'general_options_no_namespace.mdx' - -The list of available flags are: - -- `-list` - List all keys currently in use within the cluster. - -- `-install` - Install a new encryption key. This will broadcast the new key to - all members in the cluster. - -- `-use` - Change the primary encryption key, which is used to encrypt messages. - The key must already be installed before this operation can succeed. - -- `-remove` - Remove the given key from the cluster. This operation may only be - performed on keys which are not currently the primary key. - -## Output - -The output of the `nomad operator keyring -list` command consolidates -information from all the Nomad servers from all datacenters and regions to -provide a simple and easy to understand view of the cluster. - -```shell-session -$ nomad operator keyring -list -==> Gathering installed encryption keys... -Key -PGm64/neoebUBqYR/lZTbA== -``` diff --git a/website/content/docs/configuration/server.mdx b/website/content/docs/configuration/server.mdx index 5b87695d2..515549ccc 100644 --- a/website/content/docs/configuration/server.mdx +++ b/website/content/docs/configuration/server.mdx @@ -59,13 +59,13 @@ server { - `encrypt` `(string: "")` - Specifies the secret key to use for encryption of Nomad server's gossip network traffic. This key must be 32 bytes that are [RFC4648] "URL and filename safe" base64-encoded. You can generate an - appropriately-formatted key with the [`nomad operator keygen`] command. The - provided key is automatically persisted to the data directory and loaded - automatically whenever the agent is restarted. This means that to encrypt - Nomad server's gossip protocol, this option only needs to be provided once - on each agent's initial startup sequence. If it is provided after Nomad has - been initialized with an encryption key, then the provided key is ignored - and a warning will be displayed. See the [encryption + appropriately-formatted key with the [`nomad operator gossip keyring + generate`] command. The provided key is automatically persisted to the data + directory and loaded automatically whenever the agent is restarted. This means + that to encrypt Nomad server's gossip protocol, this option only needs to be + provided once on each agent's initial startup sequence. If it is provided + after Nomad has been initialized with an encryption key, then the provided key + is ignored and a warning will be displayed. See the [encryption documentation][encryption] for more details on this option and its impact on the cluster. @@ -479,7 +479,7 @@ work. [bootstrapping a cluster]: /nomad/docs/faq#bootstrapping [rfc4648]: https://tools.ietf.org/html/rfc4648#section-5 [monitoring_nomad_progress]: /nomad/docs/operations/monitoring-nomad#progress -[`nomad operator keygen`]: /nomad/docs/commands/operator/keygen +[`nomad operator gossip keyring generate`]: /nomad/docs/commands/operator/gossip/keyring-generate [search]: /nomad/docs/configuration/search [encryption key]: /nomad/docs/operations/key-management [max_client_disconnect]: /nomad/docs/job-specification/group#max-client-disconnect diff --git a/website/content/docs/upgrade/upgrade-specific.mdx b/website/content/docs/upgrade/upgrade-specific.mdx index 0626874ac..6d8e0ec7c 100644 --- a/website/content/docs/upgrade/upgrade-specific.mdx +++ b/website/content/docs/upgrade/upgrade-specific.mdx @@ -98,6 +98,13 @@ The metric `nomad.nomad.broker.total_blocked` has been changed to leader's broker, and this is easily confused with the unrelated evaluation status `"blocked"` in the Nomad API. +#### Deprecated gossip keyring commands removed + +The commands `nomad operator keyring`, `nomad keyring`, `nomad operator keygen`, +and `nomad keygen` used to manage the gossip keyring were marked as deprecated +in Nomad 1.4.0. In Nomad 1.5.0, these commands have been removed. Use the `nomad +operator gossip keyring` commands to manage the gossip keyring. + #### Garbage collection of evaluations and allocations for batch job Versions prior to 1.5.0 only delete evaluations and allocations of batch jobs diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index d68078535..a9f2c7d4d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -700,14 +700,6 @@ } ] }, - { - "title": "keygen", - "path": "commands/operator/keygen" - }, - { - "title": "keyring", - "path": "commands/operator/keyring" - }, { "title": "metrics", "path": "commands/operator/metrics"