open-nomad/website/content/docs/integrations/consul-integration.mdx

---
layout: docs
page_title: Consul Integration
description: Learn how to integrate Nomad with Consul and add service discovery to jobs
---

# 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 currently run Consul for you.

To enable Consul integration, please see the
[Nomad agent Consul integration](/docs/configuration/consul)
configuration.

## 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 see the [Automatic Clustering with
Consul](https://learn.hashicorp.com/tutorials/nomad/clustering) 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 see the
[`service` job specification documentation][service].

## Dynamic Configuration

Nomad's job specification includes a [`template` stanza](/docs/job-specification/template)
that utilizes a Consul ecosystem tool called [Consul Template](https://github.com/hashicorp/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 stanza and how it leverages Consul Template,
please see the [`template` job specification documentation](/docs/job-specification/template).

## Consul Namespaces

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 at the [group level][consul_group_namespace] 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 lowest to highest precedence:

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

- agent configuration: If the [`namespace`][consul_agent_namespace] Nomad agent
  Consul configuration parameter is set, this namespace will be used instead of
  the Consul default.

- job run command: <EnterpriseAlert inline/> If the [`-consul-namespace`][consul_run_namespace]
  command line argument is specified on job submission, this namespace will take
  precedence over the namespace set in Nomad agent configuration.

- group configuration: <EnterpriseAlert inline/> If the [group level][consul_group_namespace]
  Consul namespace is configured, this namespace will take precedence over all other
  options.

If [Consul ACLs][consul_acls] are enabled, the [allow_unauthenticated] configuration parameter
will control whether a Consul token will be required when submitting a job with
Consul namespace configured. The provided Consul token must belong to the correct
namespace, and must be backed by a Consul ACL Policy with sufficient `service:write`
`kv:read` permissions. An example policy might look like,

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

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

## Assumptions

- Consul 0.7.2 or later is needed for `tls_skip_verify` in HTTP checks.

- Consul 0.6.4 or later is needed for using the Script checks.

- Consul 0.6.0 or later is needed for using the TCP checks.

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

[allow_unauthenticated]: /docs/configuration/consul#allow_unauthenticated
[consul]: https://www.consul.io/ 'Consul by HashiCorp'
[consul_acls]: https://www.consul.io/docs/security/acl
[consul_namespaces]: https://www.consul.io/docs/enterprise/namespaces
[consul_agent_namespace]: /docs/configuration/consul#namespace
[consul_group_namespace]: /docs/job-specification/group#namespace
[consul_run_namespace]: /docs/commands/job/run#consul-namespace
[service]: /docs/job-specification/service 'Nomad service Job Specification'