»connect Stanza

Placementjob -> group -> service -> connect

The connect stanza allows configuring various options for Consul Connect. It is valid only within the context of a service definition at the task group level. For using connect when Consul ACLs are enabled, be sure to read through the Secure Nomad Jobs with Consul Connect guide.

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

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

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

      connect {
        sidecar_service {}
      }
    }

    task "web" {
      driver = "docker"

      config {
        image = "hashicorpnomad/counter-api:v2"
      }
    }
  }
}

»connect Parameters

  • native - (bool: false) - This is used to configure the service as supporting Connect Native applications. If set, the service definition must provide the name of the implementing task in the task field. Incompatible with sidecar_service and sidecar_task.

  • sidecar_service - (sidecar_service: nil) - This is used to configure the sidecar service injected by Nomad for Consul Connect. Incompatible with native.

  • sidecar_task - (sidecar_task:nil) - This modifies the configuration of the Envoy proxy task. Incompatible with native.

»connect Examples

»Using Sidecar Service

The following example is a minimal connect stanza with defaults and is sufficient to start an Envoy proxy sidecar for allowing incoming connections via Consul Connect.

  connect {
    sidecar_service {}
  }

The following example includes specifying upstreams.

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

The following is the complete countdash example. It includes an API service and a frontend Dashboard service which connects to the API service as a Connect upstream. Once running, the dashboard is accessible at localhost:9002.

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

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

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

      connect {
        sidecar_service {}
      }

      check {
        expose   = true
        type     = "http"
        name     = "api-health"
        path     = "/health"
        interval = "10s"
        timeout  = "3s"
      }
    }

    task "web" {
      driver = "docker"

      config {
        image = "hashicorpnomad/counter-api:v2"
      }
    }
  }

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

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

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

      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 = "hashicorpnomad/counter-dashboard:v2"
      }
    }
  }
}

»Using Connect Native

The following example is a minimal service stanza for a Consul Connect Native application implemented by a task named generate.

service {
  name = "uuid-api"
  port = "${NOMAD_PORT_api}"
  task = "generate"

  connect {
    native = true
  }
}

»Limitations

Nomad variable interpolation is not yet supported (gh-7221).