consul Block

Placement	`job -> group -> consul` `job -> group -> task -> consul`

The consul block specifies Consul configuration options specific to a task. If specified at the group level, the configuration will apply to all tasks and services within the group unless a task has its own consul block. A task-level consul block will entirely override a group-level consul block.

job "docs" {
  group "example" {
    task "server" {
      consul {
        cluster   = "default"
        namespace = "default"
        partition = "default"
      }
    }
  }
}

Workload Identity

Starting in Nomad 1.7, Nomad clients will use a task or service's Workload Identity to authenticate to Consul and obtain a Consul token specific to the service or task when the following conditions are met:

For services, if either the consul.service_identity is configured on the Nomad servers or the service includes an identity block.
For tasks, if the consul.task_identity is configured on the Nomad servers, or the task includes an identity block with the name field set to consul_default (or consul_$clusterName for non-default Consul clusters in Nomad Enterprise).

As a fallback if none of these conditions are met, the Nomad client will instead use, in order of preference:

The token provided by the -consul-token flag for the nomad job run command.
The Consul token as configured in the agent's consul.token configuration.
The Consul token as configured by the agent's CONSUL_HTTP_TOKEN environment variable.

To avoid failed deployments, you should first set up an authentication method and binding rules in Consul before configuring the Nomad servers with consul.task_identity and consul.service_identity. Refer to Configuring Consul Authentication for more details.

Warning

Starting in Nomad 1.10, the fallback options to use the -consul-token flag when submitting a job, the agent's consul.token configuration, or the CONSUL_HTTP_TOKEN environment variable, will be removed. This means service and template blocks will not be able to use the agent's Consul token or one provided by the job submitter. You should be prepared to migrate to the Workload Identity workflow for Consul and Vault before upgrading to Nomad 1.10. Refer to Migrating to Using Workload Identity with Consul

Access to Token

The Nomad client will make the Consul token available to the task by writing it to the secret directory at secrets/consul_token and by injecting a CONSUL_TOKEN environment variable in the task.

If the Nomad cluster is configured to use Consul Namespaces, a CONSUL_NAMESPACE environment variable will be injected whenever CONSUL_TOKEN is set.

The template block can use the Consul token as well.

`consul` Parameters

cluster (string: "default") Enterprise - Specifies the Consul cluster to use. The Nomad client will retrieve a Consul token from the cluster configured in the agent configuration with the same consul.name. In Nomad Community Edition, this field is ignored.
namespace (string: "") Enterprise - The Consul namespace in which group and task-level services within the group will be registered. Use of template to access Consul KV will read from the specified Consul namespace. Specifying namespace takes precedence over the -consul-namespace command line argument in job run.
partition (string: "") - When this field is set, a constraint will be added to the group or task to ensure that the allocation is placed on a Nomad client that has a Consul Enterprise agent in the specified Consul admin partition. Note that Consul Community Edition agents are not assigned to any admin partition, so this field should not be used without Consul Enterprise.

`consul` Examples

The following examples only show the consul blocks or other relevant blocks. Remember that the consul block is only valid in the placements listed above.

Consul Token for Templates

This example tells the Nomad client to obtain a Consul token using the task's Workload Identity. The token is available to the task via the canonical environment variable CONSUL_TOKEN and written to disk at secrets/consul_token. The template block will use the same Consul token. Note that the identity.name is set to "consul_default", which tells the Nomad client to use this identity when making requests to the default Consul cluster.

job "example" {
  group "app" {
    task "web" {
      identity {
        name = "consul_default"
      }

      template {
        data        = "APP_NAME={{key \"app/name\"}}"
        destination = "local/config.txt"
      }
    }
  }
}

The following example has the same behavior as the example above, but assumes that the server has a consul.task_identity block configured. Note that both the consul and identity blocks can be omitted in this case.

job "example" {
  group "app" {
    task "web" {
      template {
        data        = "APP_NAME={{key \"app/name\"}}"
        destination = "local/config.txt"
      }
    }
  }
}

Consul Token for Group Services

This example tells the Nomad client to obtain a Consul Service Identity token using the service's Workload Identity. The Consul token will be used to register the service with Consul and configure any Connect sidecar tasks for that service.

job "example" {
  group "web" {
    service {
      port = "www"
      identity {}
    }
  }
}

The following example has the same behavior as the example above, but assumes that the server has a consul.service_identity block configured. Note that both the consul and identity blocks can be omitted for the service in this case.

job "example" {
  group "web" {
    service {
      port = "www"
    }
  }
}

Consul Namespace

This example shows specifying a particular Consul namespace or Consul cluster for different tasks within a group.

This feature requires Nomad Enterprise(opens in new tab).

The template block in the web task will use the default Consul cluster, and will obtain a token that allows it access to the engineering/frontend Consul namespace. The template block in the app task will use the Consul cluster named prod-apps, and will obtain a token that allows it access to the engineering/apps Consul namespace.

job "docs" {
  group "example" {

    task "web" {

      consul {
        namespace = "engineering/frontend"
      }

      template {
        data        = "FRONTEND_NAME={{key \"fe/name\"}}"
        destination = "local/config.txt"
      }
    }

    task "app" {

      consul {
        namespace = "engineering/apps"
        cluster   = "prod-apps"
      }

      template {
        data        = "APP_NAME={{key \"app/name\"}}"
        destination = "local/config.txt"
      }
    }

  }
}

Consul Admin Partition

This example demonstrates how to configure Consul admin partitions for different tasks within a group. The Consul client agent must separately specify the admin partition in the agent configuration. Refer to the Consul documentation's agent configuration reference for more information.