Consul service mesh provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh configuration to automatically establish TLS connections for inbound and outbound connections without being aware of the service mesh at all.

Nomad with Consul Service Mesh Integration

Nomad integrates with Consul to provide secure service-to-service communication between Nomad jobs and task groups. To support Consul service mesh, Nomad adds a new networking mode for jobs that enables tasks in the same task group to share their networking stack. With a few changes to the job specification, job authors can opt into service mesh integration. When service mesh is enabled, Nomad will launch a proxy alongside the application in the job file. The proxy (Envoy) provides secure communication with other applications in the cluster.

Nomad job specification authors can use Nomad's Consul service mesh integration to implement service segmentation in a microservice architecture running in public clouds without having to directly manage TLS certificates. This is transparent to job specification authors as security features in service mesh continue to work even as the application scales up or down or gets rescheduled by Nomad.

For using the Consul service mesh integration with Consul ACLs enabled, see the Secure Nomad Jobs with Consul Service Mesh guide.

Nomad Consul Service Mesh Example

The following section walks through an example to enable secure communication between a web dashboard and a backend counting service. The web dashboard and the counting service are managed by Nomad. Nomad additionally configures Envoy proxies to run along side these applications. The dashboard is configured to connect to the counting service via localhost on port 9001. The proxy is managed by Nomad, and handles mTLS communication to the counting service.

Prerequisites

Consul

The Consul service mesh integration with Nomad requires Consul 1.6 or later. The Consul agent can be run in dev mode with the following command:

$ consul agent -dev

To use service mesh on a non-dev Consul agent, you will minimally need to enable the GRPC port and set connect to enabled by adding some additional information to your Consul client configurations, depending on format. Consul agents running TLS and a version greater than 1.14.0 should set the grpc_tls configuration parameter instead of grpc. Please see the Consul port documentation for further reference material.

For HCL configurations:

# ...

ports {
  grpc = 8502
}

connect {
  enabled = true
}

For JSON configurations:

{
  // ...
  "ports": {
    "grpc": 8502
  },
  "connect": {
     "enabled": true
  }
}

Consul TLS

consul {
  grpc_ca_file = "/etc/tls/consul-agent-ca.pem"
  grpc_address = "127.0.0.1:8503"
  ca_file      = "/etc/tls/consul-agent-ca.pem"
  cert_file    = "/etc/tls/dc1-client-consul-0.pem"
  key_file     = "/etc/tls/dc1-client-consul-0-key.pem"
  ssl          = true
  address      = "127.0.0.1:8501"
}

Consul ACLs

To facilitate cross-Consul datacenter requests of Connect services registered by Nomad, Consul agents will need to be configured with default anonymous ACL tokens with ACL policies of sufficient permissions to read service and node metadata pertaining to those requests. This mechanism is described in Consul #7414. A typical Consul agent anonymous token may contain an ACL policy such as:

service_prefix "" { policy = "read" }
node_prefix    "" { policy = "read" }

Nomad

Nomad must schedule onto a routable interface in order for the proxies to connect to each other. The following steps show how to start a Nomad dev agent configured for Consul service mesh.

$ sudo nomad agent -dev-connect

CNI Plugins

Nomad uses CNI reference plugins to configure the network namespace used to secure the Consul service mesh sidecar proxy. All Nomad client nodes using network namespaces must have these CNI plugins installed.

To use transparent_proxy mode, Nomad client nodes will also need the consul-cni plugin installed. See the Linux post-installation steps for more detail on how to install CNI plugins.

Run the Service Mesh-enabled Services

Once Nomad and Consul are running, submit the following service mesh-enabled services to Nomad by copying the HCL into a file named servicemesh.nomad.hcl and running: nomad job run servicemesh.nomad.hcl

job "countdash" {
  datacenters = ["dc1"]

  group "api" {
    network {
      mode = "bridge"
    }

    service {
      name = "count-api"
      port = "9001"

      connect {
        sidecar_service {}
      }
    }

    task "web" {
      driver = "docker"

      config {
        image = "hashicorpdev/counter-api:v3"
      }
    }
  }

  group "dashboard" {
    network {
      mode = "bridge"

      port "http" {
        static = 9002
        to     = 9002
      }
    }

    service {
      name = "count-dashboard"
      port = "http"

      connect {
        sidecar_service {
          proxy {
            upstreams {
              destination_name = "count-api"
              local_bind_port  = 8080
            }
          }
        }
      }
    }

    task "dashboard" {
      driver = "docker"

      env {
        COUNTING_SERVICE_URL = "http://${NOMAD_UPSTREAM_ADDR_count_api}"
      }

      config {
        image = "hashicorpdev/counter-dashboard:v3"
      }
    }
  }
}

The job contains two task groups: an API service and a web frontend.

API Service

The API service is defined as a task group with a bridge network:

  group "api" {
    network {
      mode = "bridge"
    }

    # ...
  }

Since the API service is only accessible via Consul service mesh, it does not define any ports in its network. The service block enables service mesh.

  group "api" {

    # ...

    service {
      name = "count-api"
      port = "9001"

      connect {
        sidecar_service {}
      }
    }

    # ...

  }

The port in the service block is the port the API service listens on. The Envoy proxy will automatically route traffic to that port inside the network namespace. Note that currently this cannot be a named port; it must be a hard-coded port value. See GH-9907.

Web Frontend

The web frontend is defined as a task group with a bridge network and a static forwarded port:

  group "dashboard" {
    network {
      mode = "bridge"

      port "http" {
        static = 9002
        to     = 9002
      }
    }

    # ...

  }

The static = 9002 parameter requests the Nomad scheduler reserve port 9002 on a host network interface. The to = 9002 parameter forwards that host port to port 9002 inside the network namespace.

This allows you to connect to the web frontend in a browser by visiting http://<host_ip>:9002 as show below:

The web frontend connects to the API service via Consul service mesh.

    service {
      name = "count-dashboard"
      port = "http"

      connect {
        sidecar_service {
          proxy {
            upstreams {
              destination_name = "count-api"
              local_bind_port  = 8080
            }
          }
        }
      }
    }

The upstreams block defines the remote service to access (count-api) and what port to expose that service on inside the network namespace (8080).

The web frontend is configured to communicate with the API service with an environment variable:

      env {
        COUNTING_SERVICE_URL = "http://${NOMAD_UPSTREAM_ADDR_count_api}"
      }

The web frontend is configured via the $COUNTING_SERVICE_URL, so you must interpolate the upstream's address into that environment variable. Note that dashes (-) are converted to underscores (_) in environment variables so count-api becomes count_api.

Limitations

• The minimum Consul version to use Connect with Nomad is Consul v1.8.0.
• 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.
• Prior to Consul 1.9, the Envoy sidecar proxy will drop and stop accepting connections while the Nomad agent is restarting.

Troubleshooting

If the sidecar service is not running correctly, you can investigate potential envoy failures in the following ways:

• Task logs in the associated connect-* task
• Task secrets (may contain sensitive information):
  • envoy CLI command: secrets/.envoy_bootstrap.cmd
  • environment variables: secrets/.envoy_bootstrap.env
• An extra Allocation log file: alloc/logs/envoy_bootstrap.stderr.0

For example, with an allocation ID starting with b36a:

nomad alloc status -short b36a  # to get the connect-* task name
nomad alloc logs -task connect-proxy-count-api -stderr b36a
nomad alloc exec -task connect-proxy-count-api b36a cat secrets/.envoy_bootstrap.cmd
nomad alloc exec -task connect-proxy-count-api b36a cat secrets/.envoy_bootstrap.env
nomad alloc fs b36a alloc/logs/envoy_bootstrap.stderr.0

Note: If the alloc is unable to start successfully, debugging files may only be accessible from the host filesystem. However, the sidecar task secrets directory may not be available in systems where it is mounted in a temporary filesystem.