consul block in the job specification

The jobspec consul block specifies Consul configuration options in a job that uses Consul for service discovery or tasks that need Consul tokens.

Workloads can have two different identities for Consul. A task identity is used for template blocks or providing your application with a Consul token. A service identity is used for service blocks with the Consul provider and connect blocks.

The jobspec consul block does not generate a service identity for Consul. Nomad uses a service's provider field to determine whether to generate a Consul identity for a service.

Configuration

The consul jobspec block tells Nomad which Consul cluster and namespace to register the group or task services in and, if the client is configured with a consul.task_identity, which cluster and namespace to generate a task identity token. In addition, it provides the admin partition to be used with service mesh gateway workloads.

The cluster to use for Nomad services can be overridden via the service.cluster parameter, and the task identity can be overridden by manually configuring the task with an identity{} block. Examples are provided below.

Parameters

• cluster (string: "default")

  Enterprise
  - Specifies the Consul cluster to use. The Nomad client retrieves a Consul token from the cluster configured in the agent configuration with the same consul.name.

• namespace (string: "")

  Enterprise
  - The Consul namespace in which group and task-level services within the group are registered. Use of template to access Consul KV reads from the specified Consul namespace. Specifying namespace takes precedence over the -consul-namespace command line argument in job run.

• partition (string: "")

  Enterprise
  - When this field is set, a constraint is 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. Using this field requires the following:
  • Consul Enterprise because Consul admin partitions are an Enterprise-only feature.
  • Workload identity integration. The partition field does not work with a legacy Consul token. Refer to Nomad workload identities for more information on integrating Nomad's workload identity with Consul authentication.

Consul token

Nomad generates a JSON Web Token (JWT) task identity using the server agent configuration's consul.task_identity block values. Nomad uses this JWT identity to create a token for Consul.

• When you declare the consul block at the group level, Nomad generates a Consul token for each task.
• When you declare the consul block at the task level, Nomad generates a Consul token only for that specific task.

The Nomad client makes 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 you configured your Nomad cluster to use Consul namespaces, Nomad injects a CONSUL_NAMESPACE environment variable whenever CONSUL_TOKEN is set.

You may access a Consul token in the jobspec template block as well. Refer to the Consul token for templates example for more information.

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

Nomad does not decipher the template to see if it is making requests to Consul, so you must configure one of the following:

• An identity block in the jobspec that specifies a Consul identity. Refer to Workload identities for Consul section for how to use the jobspec identity block.
• A consul block that tells Nomad to create a Consul token that the template can use. In order to use this, the Nomad client must be configured with a consul.task_identity block.

This example tells the Nomad client to obtain a Consul token using the task's configured 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 uses the same Consul token. Note that the identity.name value 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"
      }
    }
  }
}

This example tells Nomad to use the default identity specified by the server's consul.task_identity parameter configuration.

job "example" {
  group "app" {
    task "web" {
      consul {}

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

Consul namespace

Enterprise

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

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

Enterprise

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 referencefor more information.

In the following example, the web and app tasks use the default Consul cluster and obtain a token that allows access to the prod admin partition in Consul. The Consul configuration occurs at the group level because tasks are placed together on the same Allocation. If you configure tasks with separate consul blocks, the partition field must be the same in both blocks.

job "docs" {
  group "example" {

    consul {
      cluster   = "default"
      namespace = "default"
      partition = "prod"
    }

    task "web" {

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

    task "app" {

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

  }
}