---
layout: docs
page_title: Consul integration
description: |-
  Integrate Consul with Nomad to use Consul features such as automatic clustering, service discovery, service mesh, Consul Template, Consul DNS, Consul ACL, and Consul namespaces with your Nomad clusters and workloads.
---

# Consul integration

[Consul][] is a tool for discovering and configuring services in your
infrastructure. Consul's key features include service discovery, health checking,
a KV store, and robust support for multi-datacenter deployments. Nomad's integration
with Consul enables automatic clustering, built-in service registration, and
dynamic rendering of configuration files and environment variables. The sections
below describe the integration in more detail.

## Configuration

In order to use Consul with Nomad, you will need to configure and install Consul
on your nodes alongside Nomad, or schedule it as a system job. Nomad does not
run Consul for you.

To enable Consul integration, please refer to the [Nomad agent Consul
configuration][] documentation.

## Automatic clustering with Consul

Nomad servers and clients will be automatically informed of each other's
existence when a running Consul cluster already exists and the Consul agent is
installed and configured on each host. Please refer to the [Automatic Clustering
with Consul][] guide for more information.

## Service discovery

Nomad schedules workloads of various types across a cluster of generic hosts.
Because of this, placement is not known in advance and you will need to use
service discovery to connect tasks to other services deployed across your
cluster. Nomad integrates with Consul to provide service discovery and
monitoring.

To configure a job to register with service discovery, please refer to the
[`service` job specification documentation][service].

## Service mesh

Consul service mesh provides service-to-service connection authorization and
encryption using mutual Transport Layer Security (TLS). Nomad can automatically
provision the components necessary to securely connect your tasks to Consul's
service mesh.

Refer to the [Consul Service Mesh integration page][int_consul_mesh] for more
information.

## Dynamic configuration

Nomad's job specification includes a [`template`][] block that uses a Consul
ecosystem tool called [Consul Template][]. This mechanism creates a convenient
way to ship configuration files that are populated from environment variables,
Consul data, Vault secrets, or just general configurations within a Nomad task.

For more information on Nomad's template block and how it leverages Consul
Template, please see the [`template` job specification documentation][].

## DNS

To provide Consul DNS to Nomad workloads using [bridge or CNI networking
mode][], you will need to configure Consul's DNS listener to be exposed to the
workload network namespace, or configure `systemd-resolved`, `dnsmasq`, or
similar DNS stub resolvers to forward DNS. See [Forward DNS for Consul service
discovery][] for details.

You can avoid exposing the Consul agent on a public IP by setting the Consul
`bind_addr` to bind on a private IP address (the default is to use the
`client_addr`). You will also need to either have Consul bind to port 53 for
DNS if you are not using DNS forwarding.

You will also need to set the [nameserver][] to the address. This address is
exposed as the `consul.dns.addr` node attribute or the `DNSStubListener`
configuration value for `systemd-resolved`.

An simpler solution is to use Consul Connect [transparent proxy][] mode to
automatically configure tasks to use Consul DNS.

## Consul access control list (ACL)

The Consul ACL system protects the cluster from unauthorized access. When
enabled, both Consul and Nomad must be properly configured in order for their
integrations to work.

Refer to the [Consul ACL integration page][int_consul_acl] for more
information.

## Consul namespaces <EnterpriseAlert inline/>

Nomad provides integration with [Consul Namespaces][consul_namespaces] for
service registrations specified in `service` blocks and Consul KV reads in
`template` blocks.

By default, Nomad will not specify a Consul namespace on service registrations
or KV store reads, which Consul then implicitly resolves to the `"default"`
namespace.  This default namespace behavior can be modified by setting the
[`namespace`][consul_agent_namespace] field in the Nomad agent Consul
configuration block.

For more control over Consul namespaces, Nomad Enterprise supports configuring
the Consul [namespace][consul_jobspec_namespace] at the group or task level in
the Nomad job spec as well as the [`-consul-namespace`][consul_run_namespace]
command line argument for `job run`.

The Consul namespace used for a set of group or task service registrations
within a group, as well as `template` KV store access is determined from the
following hierarchy from highest to lowest precedence:

* group and task configuration: Consul
  [namespace field][consul_jobspec_namespace] defined in the job at the task or
  group level.

* job run command option: Consul namespace defined in the
  [`-consul-namespace`][consul_run_namespace] command line option on job
  submission.

* job run command environment various: Consul namespace defined as the
  [`CONSUL_NAMESPACE`][consul_env_namespace] environment variable on job
  submission.

* agent configuration: Consul namespace defined in the
  [`namespace`][consul_agent_namespace] Nomad agent Consul configuration
  parameter.

* Consul default: If no Consul namespace options are configured, Consul will
  automatically make use of the `"default"` namespace.

## Multiple Consul clusters <EnterpriseAlert inline />

Nomad Enterprise supports access to multiple Consul clusters. They can be
configured using multiple [`consul`][nomad_config_consul] blocks with different
`name` values. If a `name` is not provided, the cluster configuration is called
`default`. Nomad automatic clustering uses the `default` cluster for service
discovery.

Jobs that need access to Consul may specify which Consul cluster to use with
the [`consul.cluster`][] parameter.

## Assumptions

* Each Nomad client should have a local Consul agent running on the same host,
  reachable by Nomad. Nomad clients should never share a Consul agent or talk
  directly to the Consul servers. Nomad is not compatible with [Consul Data
  Plane][CDP].

* The service discovery feature in Nomad depends on operators making sure that
  the Nomad client can reach the Consul agent.

* Tasks running inside Nomad also need to reach out to the Consul agent if
  they want to use any of the Consul APIs. Ex: A task running inside a docker
  container in the bridge mode won't be able to talk to a Consul Agent running
  on the loopback interface of the host since the container in the bridge mode
  has its own network interface and doesn't see interfaces on the global
  network namespace of the host. There are a couple of ways to solve this, one
  way is to run the container in the host networking mode, or make the Consul
  agent listen on an interface in the network namespace of the container.

* The `consul` binary must be present in Nomad's `$PATH` to run the Envoy
  proxy sidecar on client nodes.

* Consul service mesh using network namespaces is only supported on Linux.

## Compatibility

All currently supported versions of Nomad are compatible with recent versions of
Consul, with some exceptions.

* Nomad is not compatible with Consul Data Plane.

|                   | Consul 1.17.0+ | Consul 1.18.0+ | Consul 1.19.0+ |
|-------------------|----------------|----------------|----------------|
| Nomad 1.8.0+      | ✅             | ✅             | ✅            |
| Nomad 1.7.0+      | ✅             | ✅             | ✅            |
| Nomad 1.6.0+      | ✅             | ✅             | ✅            |

[Automatic Clustering with Consul]: /nomad/tutorials/manage-clusters/clustering
[CDP]: /consul/docs/connect/dataplane
[Consul Template]: https://github.com/hashicorp/consul-template
[Consul]: https://www.consul.io/ "Consul by HashiCorp"
[Nomad agent Consul configuration]: /nomad/docs/configuration/consul
[`consul.cluster`]: /nomad/docs/job-specification/consul#cluster
[`template` job specification documentation]: /nomad/docs/job-specification/template#consul-integration
[`template`]: /nomad/docs/job-specification/template
[consul_agent_namespace]: /nomad/docs/configuration/consul#namespace
[consul_jobspec_namespace]: /nomad/docs/job-specification/consul#namespace
[consul_namespaces]: /consul/docs/enterprise/namespaces
[consul_run_namespace]: /nomad/docs/commands/job/run#consul-namespace
[consul_env_namespace]: /consul/commands#consul_namespace
[int_consul_acl]: /nomad/docs/integrations/consul/acl
[int_consul_mesh]: /nomad/docs/integrations/consul/service-mesh
[nomad_config_consul]: /nomad/docs/configuration/consul
[service]: /nomad/docs/job-specification/service "Nomad service Job Specification"
[bridge or CNI networking mode]: /nomad/docs/job-specification/network#mode
[nameserver]: /nomad/docs/job-specification/network#servers
[transparent proxy]: /nomad/docs/job-specification/transparent_proxy
[Forward DNS for Consul service discovery]: https://developer.hashicorp.com/consul/tutorials/networking/dns-forwarding
