From c214d7c62fc6e39d48539d917776b6c6012cfc10 Mon Sep 17 00:00:00 2001 From: hc-github-team-nomad-core <82989552+hc-github-team-nomad-core@users.noreply.github.com> Date: Fri, 1 Dec 2023 12:45:39 -0600 Subject: [PATCH] Backport of docs: split consul config params into client vs server sections into release/1.7.x #19274 Co-authored-by: Tim Gross --- website/content/docs/configuration/consul.mdx | 194 ++++++++++++------ 1 file changed, 128 insertions(+), 66 deletions(-) diff --git a/website/content/docs/configuration/consul.mdx b/website/content/docs/configuration/consul.mdx index cdb2a8795b0e..4ef6c5b689d0 100644 --- a/website/content/docs/configuration/consul.mdx +++ b/website/content/docs/configuration/consul.mdx @@ -32,6 +32,11 @@ cluster with zero configuration. To put it another way: if you have a Consul agent running on the same host as the Nomad agent with the default configuration, Nomad will automatically connect and configure with Consul. +If the local Consul agent is configured and accessible by the Nomad agents, the +Nomad cluster will [automatically bootstrap][bootstrap] provided +`server_auto_join`, `client_auto_join`, and `auto_advertise` are all enabled +(which is the default). + ~> An important requirement is that each Nomad agent talks to a unique Consul agent. Nomad agents should be configured to talk to Consul agents and not Consul servers. If you are observing flapping services, you may have @@ -44,18 +49,22 @@ value for the [`name`](#name) field. ## `consul` Parameters +Some parameters are expected to be specified in the configuration file of Nomad +agents running as clients, servers, or in all agents. Parameters are safely +ignored if placed in a configuration file where they are not expected to be +defined. + +### Parameters for Nomad Clients and Servers + +These parameters should be defined in the configuration file of all Nomad +agents. + - `address` `(string: "127.0.0.1:8500")` - Specifies the address to the local Consul agent, given in the format `host:port`. Supports Unix sockets with the format: `unix:///tmp/consul/consul.sock`. Will default to the `CONSUL_HTTP_ADDR` environment variable if set. The value supports [go-sockaddr/template format][go-sockaddr/template]. -- `allow_unauthenticated` `(bool: true)` - Specifies if users submitting jobs to - the Nomad server should be required to provide their own Consul token, proving - they have access to the service identity policies required by the Consul Connect - enabled services listed in the job. This option should be - disabled in an untrusted environment. - - `auth` `(string: "")` - Specifies the HTTP Basic Authentication information to use for access to the Consul Agent, given in the format `username:password`. @@ -65,10 +74,6 @@ value for the [`name`](#name) field. respective services, each tagged appropriately with either `http` or `rpc` tag. Nomad servers also advertise a `serf` tagged service. -- `grpc_ca_file` `(string: "")` - Specifies an optional path to the GRPC CA - certificate used for communication between Connect sidecar proxies and Consul - agents. Will default to the `CONSUL_GRPC_CACERT` environment variable if set. - - `ca_file` `(string: "")` - Specifies an optional path to the CA certificate used for Consul communication. This defaults to the system bundle if unspecified. Will default to the `CONSUL_CACERT` environment variable if set. @@ -83,6 +88,46 @@ value for the [`name`](#name) field. specified, it will fall back to the [bind_addr](/nomad/docs/configuration#bind_addr). +- `key_file` `(string: "")` - Specifies the path to the private key used for + Consul communication. If this is set then you need to also set `cert_file`. + +- `name` `(string: "default")` - Specifies a name for + the cluster so it can be referred to by job submitters in the job + specification's [`consul.cluster`][] or [`service.cluster`][] fields. In Nomad + Community Edition, only the `"default"` cluster will be used, so this field + should be omitted. + +- `namespace` `(string: "")` - Specifies the [Consul + namespace](/consul/docs/enterprise/namespaces) used by the Consul + integration. If non-empty, this namespace will be used on all Consul API calls + and for Consul Connect configurations, unless overridden by the job's + [`consul.namespace`][] field. + +- `ssl` `(bool: false)` - Specifies if the transport scheme should use HTTPS to + communicate with the Consul agent. Will default to the `CONSUL_HTTP_SSL` + environment variable if set. + +- `tags` `(array: [])` - Specifies optional Consul tags to be + registered with the Nomad server and agent services. + +- `timeout` `(string: "5s")` - Specifies a time limit for requests made against + Consul. This is specified using a label suffix like "10s". + +- `token` `(string: "")` - Specifies the token used to provide a per-request ACL + token. This option overrides the Consul Agent's default token. If the token is + not set here or on the Consul agent, it will default to Consul's anonymous policy, + which may or may not allow writes. Will default to the `CONSUL_HTTP_TOKEN` + environment variable if set. + +- `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used + when communicating to the Consul API client over HTTPS. Will default to the + `CONSUL_HTTP_SSL_VERIFY` environment variable if set. + +### Parameters for Nomad Clients + +These parameters should only be defined in the configuration file of Nomad +agents with [`client.enabled`][] set to `true`. + - `client_auto_join` `(bool: true)` - Specifies if the Nomad clients should automatically discover servers in the same region by searching for the Consul service name defined in the `server_service_name` option. The search occurs if @@ -101,18 +146,20 @@ value for the [`name`](#name) field. Consul does not enable the [`grpc`][grpc_port] or [`grpc_tls`][grpctls_port] listeners by default. -- `key_file` `(string: "")` - Specifies the path to the private key used for - Consul communication. If this is set then you need to also set `cert_file`. +- `grpc_ca_file` `(string: "")` - Specifies an optional path to the GRPC CA + certificate used for communication between Connect sidecar proxies and Consul + agents. Will default to the `CONSUL_GRPC_CACERT` environment variable if set. -- `name` `(string: "default")` - Specifies a name for - the cluster so it can be referred to by job submitters in the job - specification's [`consul.cluster`][] or [`service.cluster`][] fields. In Nomad - Community Edition, only the `"default"` cluster will be used, so this field - should be omitted. +- `share_ssl` `(bool: true)` - Specifies whether the Nomad client should share + its Consul SSL configuration with Connect Native applications. Includes values + of `ca_file`, `cert_file`, `key_file`, `ssl`, and `verify_ssl`. Does not + include the values for the ACL `token` or `auth`. This option should be + disabled in environments where Consul ACLs are not enabled. + +### Parameters for Nomad Servers -- `namespace` `(string: "")` - Specifies the [Consul namespace](/consul/docs/enterprise/namespaces) - used by the Consul integration. If non-empty, this namespace will be used on - all Consul API calls and for Consul Connect configurations. +These parameters should only be defined in the configuration file of Nomad +agents with [`server.enabled`] set to `true`. - `server_service_name` `(string: "nomad")` - Specifies the name of the service in Consul for the Nomad servers. @@ -140,19 +187,6 @@ value for the [`name`](#name) field. Consul to register services. Refer to [Workload Identity](#workload-identity) for a recommended configuration. -- `share_ssl` `(bool: true)` - Specifies whether the Nomad client should share - its Consul SSL configuration with Connect Native applications. Includes values - of `ca_file`, `cert_file`, `key_file`, `ssl`, and `verify_ssl`. Does not include - the values for the ACL `token` or `auth`. This option should be disabled in - environments where Consul ACLs are not enabled. - -- `ssl` `(bool: false)` - Specifies if the transport scheme should use HTTPS to - communicate with the Consul agent. Will default to the `CONSUL_HTTP_SSL` - environment variable if set. - -- `tags` `(array: [])` - Specifies optional Consul tags to be - registered with the Nomad server and agent services. - - `task_auth_method` `(string: "nomad-tasks")` - Specifies the name of the Consul [authentication method][auth-method] that will be used to login with a Nomad JWT for tasks. @@ -162,42 +196,18 @@ value for the [`name`](#name) field. support [`template`][] blocks. Refer to [Workload Identity](#workload-identity) for a recommended configuration. -- `timeout` `(string: "5s")` - Specifies a time limit for requests made against - Consul. This is specified using a label suffix like "10s". - -- `token` `(string: "")` - Specifies the token used to provide a per-request ACL - token. This option overrides the Consul Agent's default token. If the token is - not set here or on the Consul agent, it will default to Consul's anonymous policy, - which may or may not allow writes. Will default to the `CONSUL_HTTP_TOKEN` - environment variable if set. +### Deprecated Parameters -- `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used - when communicating to the Consul API client over HTTPS. Will default to the - `CONSUL_HTTP_SSL_VERIFY` environment variable if set. +These parameters are used by the deprecated token-based authentication flow and +will be removed in a future release. -If the local Consul agent is configured and accessible by the Nomad agents, the -Nomad cluster will [automatically bootstrap][bootstrap] provided -`server_auto_join`, `client_auto_join`, and `auto_advertise` are all enabled -(which is the default). - -## `consul` Examples - -### Default - -This example shows the default Consul integration: - -```hcl -consul { - address = "127.0.0.1:8500" - server_service_name = "nomad" - client_service_name = "nomad-client" - auto_advertise = true - server_auto_join = true - client_auto_join = true -} -``` +- `allow_unauthenticated` `(bool: true)` - Specifies if users submitting jobs to + the Nomad server should be required to provide their own Consul token, proving + they have access to the service identity policies required by the Consul + Connect enabled services listed in the job. This option should be disabled in + an untrusted environment. -### Workload Identity +## Workload Identity The `service_identity` and `task_identity` blocks accept all the same values as the job specification's [`identity`][identity_block] (except that the @@ -225,6 +235,53 @@ consul { } ``` +### `service_identity` Parameters + +- `aud` `(array: [])` - List of valid recipients for this workload + identity. This value must match the [`BoundAudiences`][consul_bound_aud] + configuration in the Consul JWT auth method. It is recommended to provide one, + and only one, audience to minimize where the identity may be used. + +- `ttl` `(string: "")` - Specifies for how long the workload identity should be + considered as valid before expiring. + +### `task_identity` Parameters + +- `aud` `(array: [])` - List of valid recipients for this workload + identity. This value must match the [`BoundAudiences`][consul_bound_aud] + configuration in the Consul JWT auth method. It is recommended to provide one, + and only one, audience to minimize where the identity may be used. + +- `env` `(bool: false)` - If true the workload identity will be available in the + task's `NOMAD_TOKEN_consul` environment variable. + +- `file` `(bool: false)` - If true the workload identity will be available in + the task's filesystem via the path `secrets/nomad_default_consul.jwt` (or + `secrets/nomad_$name_consul.jwt` depending on the [`name`](#name) field). If + the [`task.user`][taskuser] parameter is set, the token file will only be + readable by that user. Otherwise the file is readable by everyone but is + protected by parent directory permissions. + +- `ttl` `(string: "")` - Specifies for how long the workload identity should be + considered as valid before expiring. + +## `consul` Examples + +### Default + +This example shows the default Consul integration: + +```hcl +consul { + address = "127.0.0.1:8500" + server_service_name = "nomad" + client_service_name = "nomad-client" + auto_advertise = true + server_auto_join = true + client_auto_join = true +} +``` + ### Custom Address and Port This example shows pointing the Nomad agent at a different Consul address. Note @@ -297,3 +354,8 @@ namespace "nomad-ns" { [`template`]: /nomad/docs/job-specification/template [Migrating to Using Workload Identity with Consul]: /nomad/docs/integrations/consul-integration#migrating-to-using-workload-identity-with-consul [auth-method]: /consul/docs/security/acl/auth-methods/jwt +[`client.enabled`]: /nomad/docs/configuration/client#enabled +[`server.enabled`]: /nomad/docs/configuration/server#enabled +[taskuser]: /nomad/docs/job-specification/task#user "Nomad task Block" +[consul_bound_aud]: /consul/docs/security/acl/auth-methods/jwt#boundaudiences +[`consul.namespace`]: /nomad/docs/job-specification/consul#namespace