CLI and API SDK Configuration Files

[schmichael]

Proposal

As of Nomad v1.9 the CLI is only configurable via environment variables: https://developer.hashicorp.com/nomad/docs/commands#environment-variables

Allowing configuration of the CLI via a config file would not only allow for more expressive config parameters, but also be easier for generating and distributing.

Since the CLI uses the api package SDK, the api package should honor all non-CLI-flag configuration files listed below.

Parameters

• address - Same as NOMAD_ADDR/-address
• region - Same as NOMAD_REGION/-region
• namespace - Same as NOMAD_NAMESPACE/-namespace
• tls{} - Same as agent's for relevant settings
• unsafe_skip_verify - Same as NOMAD_SKIP_VERIFY
• cli{}
  • no_color - Same as NOMAD_CLI_NO_COLOR

Note there are no tokens or other secrets in the config file.

Mixing CLI and Agent configuration in a single file is not supported. This would encourage sharing the tls{} block between the CLI and Agent, and the CLI should not use the same certificates as the Agent.

The CLI should output a warning when encountering a config file with client{} or server{} blocks in it.

Agents should log a warning when encountering a config file with a cli{} block as this may indicate a misunderstanding or misconfiguration.

File Resolution Order

As with Nomad Agent configuration file parsing, the CLI should parse and combine multiple config files. The precedence is (so parsing should be done in reverse order):

1. Specific CLI flags (e.g. -address)
2. Specific environment variables (e.g. NOMAD_ADDR)
3. -config CLI flag
4. NOMAD_CLI_CONF environment variable
5. .nomad.{json,hcl} in the current directory
6. $HOME/.config/nomad/config.{json,hcl} on Unix or %APPDATA%\nomad\config.{json,hcl} on Windows

Prior Art

@jrasell did a hackweek project on CLI contexts: main...jrasell/hack-context

See also internal RFC NMD-156

External

1. Terraform - https://developer.hashicorp.com/terraform/cli/config/config-file
2. Packer - https://developer.hashicorp.com/packer/docs/configure
3. kubectl - https://kubernetes.io/docs/reference/kubectl/generated/kubectl_config/

Use-cases

• Configuring UI hints in [cli] UI URL hints for common CLI commands #24454