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

---
layout: docs
page_title: connect Stanza - Job Specification
sidebar_title: connect
description: The "connect" stanza allows specifying options for Consul Connect integration
---

# `connect` Stanza

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

The `connect` stanza allows configuring various options for
[Consul Connect](/docs/integrations/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](https://learn.hashicorp.com/tutorials/nomad/consul-service-mesh)
guide.

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

## `connect` 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
  [Connect Native](https://www.consul.io/docs/connect/native) applications.

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

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

## `connect` Examples

### Using Connect Native

The following example is a minimal service stanza for a
[Consul Connect Native](https://www.consul.io/docs/connect/native)
application implemented by a task named `generate`.

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

  connect {
    native = true
  }
}
```

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

```hcl
  connect {
    sidecar_service {}
  }
```

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

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

### Using a Gateway

The following is an example service stanza for creating and using a connect 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, e.g.

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

### Limitations

[gateway]: /docs/job-specification/gateway
[gh-7221]: https://github.com/hashicorp/nomad/issues/7221
[group]: /docs/job-specification/group 'Nomad group Job Specification'
[interpolation]: /docs/runtime/interpolation 'Nomad interpolation'
[job]: /docs/job-specification/job 'Nomad job Job Specification'
[native]: https://www.consul.io/docs/connect/native
[service_task]: /docs/job-specification/service#task-1 'Nomad service task'
[sidecar_service]: /docs/job-specification/sidecar_service 'Nomad sidecar service Specification'
[sidecar_task]: /docs/job-specification/sidecar_task 'Nomad sidecar task config Specification'
[task]: /docs/job-specification/task 'Nomad task Job Specification'
[upstreams]: /docs/job-specification/upstreams 'Nomad sidecar service upstreams Specification'