HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Nomad
Nomad Home

You are viewing documentation for version v1.0.x. View latest version.

Command: operator keyring

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

nomad operator keyring [options]

Only one actionable argument may be specified per run, including -list, -install, -remove, and -use.

General Options

  • -address=<addr>: The address of the Nomad server. Overrides the NOMAD_ADDR environment variable if set. Defaults to http://127.0.0.1:4646.

  • -region=<region>: The region of the Nomad server to forward commands to. Overrides the NOMAD_REGION environment variable if set. Defaults to the Agent's local region.

  • -no-color: Disables colored command output. Alternatively, NOMAD_CLI_NO_COLOR may be set.

  • -ca-cert=<path>: Path to a PEM encoded CA cert file to use to verify the Nomad server SSL certificate. Overrides the NOMAD_CACERT environment variable if set.

  • -ca-path=<path>: Path to a directory of PEM encoded CA cert files to verify the Nomad server SSL certificate. If both -ca-cert and -ca-path are specified, -ca-cert is used. Overrides the NOMAD_CAPATH environment variable if set.

  • -client-cert=<path>: Path to a PEM encoded client certificate for TLS authentication to the Nomad server. Must also specify -client-key. Overrides the NOMAD_CLIENT_CERT environment variable if set.

  • -client-key=<path>: Path to an unencrypted PEM encoded private key matching the client certificate from -client-cert. Overrides the NOMAD_CLIENT_KEY environment variable if set.

  • -tls-server-name=<value>: The server name to use as the SNI host when connecting via TLS. Overrides the NOMAD_TLS_SERVER_NAME environment variable if set.

  • -tls-skip-verify: Do not verify TLS certificate. This is highly not recommended. Verification will also be skipped if NOMAD_SKIP_VERIFY is set.

  • -token: The SecretID of an ACL token to use to authenticate API requests with. Overrides the NOMAD_TOKEN environment variable if set.

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.

$ nomad operator keyring -list
==> Gathering installed encryption keys...
Key
PGm64/neoebUBqYR/lZTbA==