nomad/website/content/docs/job-specification/connect.mdx

---
layout: docs
page_title: connect block in the job specification
description: |-
  Configure the `connect` block of the Nomad job specification for Consul service mesh native application integration. Configure sidecar service, sidecar task, and gateway.
---

# `connect` block in the job specification

<Placement groups={['job', 'group', 'service', 'connect']} />

Use the `connect` block to configure various options for Consul service mesh
(formerly Consul Connect). The `connect` block is valid only within the context
of a service definition at the task group level.

Refer to the following resources for details on using Consul service mesh with Nomad:

- The [Consul service mesh](/nomad/docs/networking/consul/service-mesh) overview
  for an introduction and how to configure Consul service mesh in your job.
- [Secure Nomad jobs with Consul service
  mesh](/nomad/tutorials/integrate-consul/consul-service-mesh) for using
  `connect` when Consul ACLs are enabled.

All the examples on this page assume Consul and Nomad are in the same
datacenter.

```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"
      }
    }
  }
}
```

## Parameters

Used to configure a connect service. Only one of `native`, `sidecar_service`,
or `gateway` may be realized per `connect` block.

- `native` - `(bool: false)` - This is used to configure the service as
  supporting [Consul service mesh native][consul-service-mesh-native]
  applications.

- `sidecar_service` - <code>([sidecar_service][]: nil)</code> - This is used to
  configure the sidecar service created by Nomad for Consul service mesh.

- `sidecar_task` - <code>([sidecar_task][]:nil)</code> - This modifies the
  task configuration of the Envoy proxy created as a sidecar or gateway.

- `gateway` - <code>([gateway][]:nil)</code> - This is used to configure the
  gateway service created by Nomad for Consul service mesh.

## Examples

### Using Consul service mesh native

The following example is a minimal service block for a
[Consul service mesh native][consul-service-mesh-native]
application implemented by a task named `generate`. Make sure to include the
[service `name`](/nomad/docs/job-specification/service#name) and [service
`port`](/nomad/docs/job-specification/service##port) fields so that Consul
advertizes the service with your desired values.

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

  connect {
    native = true
  }
}
```

### Using sidecar service

The following example is a minimal connect block with defaults and is
sufficient to start an Envoy proxy sidecar for allowing incoming connections
via Consul service mesh.  Make sure to include the
[service `name`](/nomad/docs/job-specification/service#name) and [service
`port`](/nomad/docs/job-specification/service##port) fields so that Consul
advertizes the service with your desired values.

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

  connect {
    sidecar_service {}
  }
}
```

The following example includes specifying [`upstreams`][upstreams].

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

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

```hcl
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 = "hashicorpdev/counter-api:v3"
      }
    }
  }

  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 = "hashicorpdev/counter-dashboard:v3"
      }
    }
  }
}
```

### Using a gateway

The following is an example service block for creating and using a Consul
service mesh ingress
gateway. It includes a gateway service definition and an API service fronted by
the gateway. Once running, the gateway can be used to reach the API service by first
looking up the gateway Consul DNS address with `curl`.

```
curl $(dig +short @127.0.0.1 -p 8600 uuid-api.ingress.dc1.consul. ANY):8080
```

```hcl
job "ingress-demo" {

  datacenters = ["dc1"]

  group "ingress-group" {

    network {
      mode = "bridge"
      port "inbound" {
        static = 8080
        to     = 8080
      }
    }

    service {
      name = "my-ingress-service"
      port = "8080"

      connect {
        gateway {
          ingress {
            listener {
              port     = 8080
              protocol = "tcp"
              service {
                name = "uuid-api"
              }
            }
          }
        }
      }
    }
  }
}
```



[gateway]: /nomad/docs/job-specification/gateway
[gh-7221]: https://github.com/hashicorp/nomad/issues/7221
[group]: /nomad/docs/job-specification/group
[interpolation]: /nomad/docs/reference/runtime-variable-interpolation
[job]: /nomad/docs/job-specification/job
[service_task]: /nomad/docs/job-specification/service#task-1
[sidecar_service]: /nomad/docs/job-specification/sidecar_service
[sidecar_task]: /nomad/docs/job-specification/sidecar_task
[task]: /nomad/docs/job-specification/task
[upstreams]: /nomad/docs/job-specification/upstreams
[consul-service-mesh-native]: /consul/docs/automate/native