nomad/website/content/docs/configuration/consul.mdx

---
layout: docs
page_title: consul Block in Agent Configuration
description: |-
  Configure Nomad server and client integration with Consul in the `consul` block of a Nomad agent configuration for service discovery and key-value integration. Configure cluster name, the Consul namespace, whether Nomad should advertize its services, certificates, tokens, security, health checks, auto join, and workload service and task identity.
---

# `consul` Block in Agent Configuration

<Placement groups={['consul']} />

This page provides reference information for configuring Nomad server and client
integration with [Consul][consul] in the `consul` block of a Nomad agent
configuration for service discovery and key-value integration. Configure cluster
name, the Consul namespace, whether Nomad should advertize its services,
certificates, tokens, security, health checks, auto join, and workload service
and task identity.

When configured, tasks can register themselves with Consul, and the Nomad
cluster can [automatically bootstrap][bootstrap] itself.

Refer to the [Service Discovery on Nomad
tutorial](/nomad/tutorials/service-discovery) for how to use Consul's service
discovery.

```hcl
consul {
  address = "127.0.0.1:8500"
  auth    = "admin:password"
  token   = "abcd1234"
}
```

A default `consul` block is automatically merged with all Nomad agent
configurations. These sensible defaults automatically enable Consul integration
if Consul is detected on the system. This allows for seamless bootstrapping of
the 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 be able to automatically connect to the rest of the
Nomad cluster.

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
multiple Nomad agents talking to the same Consul agent. As such avoid
configuring Nomad to talk to Consul via DNS such as consul.service.consul

In Nomad Enterprise, you may specify multiple `consul` blocks to configure
access to multiple Consul clusters. Each Consul cluster must have a different
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].

- `auth` `(string: "")` - Specifies the HTTP Basic Authentication information to
  use for access to the Consul Agent, given in the format `username:password`.

- `auto_advertise` `(bool: true)` - Specifies if Nomad should advertise its
  services in Consul. The services are named according to `server_service_name`
  and `client_service_name`. Nomad servers and clients advertise their
  respective services, each tagged appropriately with either `http` or `rpc`
  tag. Nomad servers also advertise a `serf` tagged service.

- `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.

- `cert_file` `(string: "")` - Specifies the path to the certificate used for
  Consul communication. If this is set then you need to also set `key_file`.

- `checks_use_advertise` `(bool: false)` - Specifies if Consul health checks
  should bind to the advertise address. By default, this is the first [HTTP
  address](/nomad/docs/configuration#http). If no
  [HTTP address](/nomad/docs/configuration#http) is
  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")` <EnterpriseAlert inline/> - 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: "")` <EnterpriseAlert inline/> - 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. In Nomad Community Edition, only the `"default"`
  namespace is used, so you should omit this 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<string>: [])` - Specifies optional Consul tags to be
  registered with the Nomad server and client 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 defaults to Consul's anonymous policy,
  which may or may not allow writes. Defaults to the `CONSUL_HTTP_TOKEN`
  environment variable if set. Nomad cannot refresh this token; if the token is
  deleted, Nomad is not able to communicate with Consul.

  In Nomad Enterprise, if the Consul agent running alongside Nomad is in a
  Consul Enterprise admin partition, you must create the Consul token provided
  to the Nomad client in the same partition.

- `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
  the client is not registered with any servers or it is unable to heartbeat to
  the leader of the region, in which case it may be partitioned and searches for
  other servers.

- `client_service_name` `(string: "nomad-client")` - Specifies the name of the
  service in Consul for the Nomad clients.

- `client_http_check_name` `(string: "Nomad Client HTTP Check")` - Specifies the
  HTTP health check name in Consul for the Nomad clients.

- `client_failures_before_critical` `(int: 0)` - Specifies the number of
  consecutive failures before the Nomad client Consul health check is critical.

- `client_failures_before_warning` `(int: 0)` - Specifies the number of
  consecutive failures before the Nomad client Consul health check shows a warning.

- `grpc_address` `(string: "127.0.0.1:8502")` - Specifies the address to the local
  Consul agent for `gRPC` requests, given in the format `host:port`. Note that
  Consul does not enable the [`grpc`][grpc_port] or [`grpc_tls`][grpctls_port]
  listeners by default.

- `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.

  <Warning>

    Consul does not support incoming TLS verification of Envoy
    sidecars. You should set `tls.grpc.verify_incoming = false` in your
    Consul configuration when using Connect. Refer to
    [Consul/#13088](https://github.com/hashicorp/consul/issues/13088) for
    more details.

  </Warning>

- `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.

- `service_auth_method` `(string: "nomad-workloads")` - Specifies the name of the
  Consul [authentication method][auth-method] that will be used to login with a
  Nomad JWT for services.

- `task_auth_method` `(string: "nomad-workloads")` - Specifies the name of the
  Consul [authentication method][auth-method] that will be used to login with a
  Nomad JWT for tasks.

### Parameters for Nomad Servers

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.

- `server_http_check_name` `(string: "Nomad Server HTTP Check")` - Specifies the
  HTTP health check name in Consul for the Nomad servers.

- `server_serf_check_name` `(string: "Nomad Server Serf Check")` - Specifies
  the Serf health check name in Consul for the Nomad servers.

- `server_rpc_check_name` `(string: "Nomad Server RPC Check")` - Specifies
  the RPC health check name in Consul for the Nomad servers.

- `server_auto_join` `(bool: true)` - Specifies if the Nomad servers should
  automatically discover and join other Nomad servers by searching for the
  Consul service name defined in the `server_service_name` option. This search
  only happens if the server does not have a leader.

- `server_failures_before_critical` `(int: 0)` - Specifies the number of
  consecutive failures before the Nomad server Consul health check is critical.

- `server_failures_before_warning` `(int: 0)` - Specifies the number of
  consecutive failures before the Nomad server Consul health check shows a warning.

- `service_identity` <code>([Identity](#service_identity-parameters): nil)</code> - Specifies
  a default Workload Identity to use when obtaining Service Identity tokens from
  Consul to register services. Refer to [Workload Identity](#workload-identity)
  for a recommended configuration.

- `task_identity` <code>([Identity](#task_identity-parameters): nil)</code> - Specifies a
  default Workload Identity to use when obtaining Consul tokens from Consul to
  support [`template`][] blocks. Refer to [Workload
  Identity](#workload-identity) for a recommended configuration.

## 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
`service_identity` ignores the `env` and `file` fields). By ensuring these
blocks are set on the Nomad servers, you can automatically migrate your existing
jobs to use Workload Identity without modifying the job specification and
resubmitting them.

The recommended configuration for `service_identity` and `task_identity` is as
follows. Refer to [Migrating to Using Workload Identity with Consul][] for
details on how to configure Consul to accept these identities. Note that the
`ttl` field here refers to the TTL of the Nomad identity and not the Consul
token.

```hcl
consul {
  service_identity {
    aud = ["consul.io"]
    ttl = "1h"
  }

  task_identity {
    aud = ["consul.io"]
    ttl = "1h"
  }
}
```

### `service_identity` Parameters

- `aud` `(array<string>: [])` - 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<string>: [])` - 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_default` (or `NOMAD_TOKEN_consul_<name>` depending
  on the [`name`](#name) field) environment variable.

- `file` `(bool: false)` - If true the workload identity will be available in
  the task's filesystem via the path `secrets/nomad_consul_default.jwt` (or
  `secrets/nomad_consul_<name>.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
that you should **never** point directly at a Consul server; always point to a
local client. In this example, the Consul server is bound and listening on the
node's private IP address instead of localhost, so we use that:

```hcl
consul {
  address = "10.0.2.4:8500"
}
```

### Custom SSL

This example shows configuring custom SSL certificates to communicate with
the Consul agent. The Consul agent should be configured to accept certificates
similarly, but that is not discussed here:

```hcl
consul {
  ssl       = true
  ca_file   = "/var/ssl/bundle/ca.bundle"
  cert_file = "/etc/ssl/consul.crt"
  key_file  = "/etc/ssl/consul.key"
}
```

### Consul ACL policy for Nomad

Nomad agents need access to Consul in order to register themselves in the
service catalog and discover other Nomad agents via service discovery for
automatic clustering. Nomad clients use Consul tokens from Workload Identity to
register services and checks but need permissions on their own token to
deregister. Nomad servers also create [configuration
entries][consul_config_entry] for Consul Service Mesh, so the specific
permissions vary slightly between Nomad servers and clients. The following
Consul ACL policies represent the minimal permissions Nomad servers and clients
need.

<Tabs>
<Tab heading="Nomad Servers">

```hcl
agent_prefix "" {
  policy = "read"
}

node_prefix "" {
  policy = "write"
}

service_prefix "" {
  policy = "write"
}

acl  = "write"
mesh = "write"
```

</Tab>
<Tab heading="Nomad Clients">

```hcl
agent_prefix "" {
  policy = "read"
}

node_prefix "" {
  policy = "write"
}

service_prefix "" {
  policy = "write"
}
```

</Tab>
</Tabs>

### Consul Namespace <EnterpriseAlert inline/>

Consul does not allow ACL policies associated with namespaces to use agent
permissions. Nomad requires `agent:read` permissions. In order to use the
`consul_namespace` feature, Nomad will need a token generated in Consul's
default namespace. That token should be created with `agent:read` as well
as a `namespace` block with the other relevant permissions for running Nomad
in the intended namespace.

This Consul policy shows an example policy configuration for a Nomad server.

```hcl
agent_prefix "" {
  policy = "read"
}

namespace "nomad-ns" {
  acl = "write"

  key_prefix "" {
    policy = "read"
  }

  node_prefix "" {
    policy = "read"
  }

  service_prefix "" {
    policy = "write"
  }
}
```

### Consul Admin Partition <EnterpriseAlert inline/>

In Nomad Enterprise, if the Consul agent running alongside Nomad is in a Consul
Enterprise admin partition, you must create the Consul ACL token and ACL policy
for Nomad clients in the same partition.


[consul]: https://www.consul.io/ 'Consul by HashiCorp'
[bootstrap]: /nomad/tutorials/manage-clusters/clustering 'Automatic Bootstrapping'
[go-sockaddr/template]: https://pkg.go.dev/github.com/hashicorp/go-sockaddr/template
[grpc_port]: /consul/docs/agent/config/config-files#grpc_port
[grpctls_port]: /consul/docs/agent/config/config-files#grpc_tls_port
[`consul.cluster`]: /nomad/docs/job-specification/consul#cluster
[`service.cluster`]: /nomad/docs/job-specification/service#cluster
[identity_block]: /nomad/docs/job-specification/identity
[`template`]: /nomad/docs/job-specification/template
[Migrating to Using Workload Identity with Consul]: /nomad/docs/v1.8.x/integrations/consul/acl#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
[consul_config_entry]: /consul/docs/connect/config-entries