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

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

263 lines
5.6 KiB
Plaintext
Raw Normal View History

2019-09-05 18:08:31 +00:00
---
2020-02-06 23:45:31 +00:00
layout: docs
page_title: connect Block - Job Specification
description: The "connect" block allows specifying options for Consul Connect integration
2019-09-05 18:08:31 +00:00
---
# `connect` Block
2019-09-05 18:08:31 +00:00
2020-02-06 23:45:31 +00:00
<Placement groups={['job', 'group', 'service', 'connect']} />
2019-09-05 18:08:31 +00:00
The `connect` block allows configuring various options for
[Consul Connect](/nomad/docs/integrations/consul-connect). It is
2019-09-05 18:08:31 +00:00
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](/nomad/tutorials/integrate-consul/consul-service-mesh)
guide.
2019-09-05 18:08:31 +00:00
```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"
}
}
}
}
2019-09-05 18:08:31 +00:00
```
## `connect` Parameters
2020-12-17 17:08:48 +00:00
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](/consul/docs/connect/native) applications.
2020-12-17 17:08:48 +00:00
- `sidecar_service` - <code>([sidecar_service][]: nil)</code> - This is used to
configure the sidecar service created by Nomad for Consul Connect.
2020-12-17 17:08:48 +00:00
- `sidecar_task` - <code>([sidecar_task][]:nil)</code> - This modifies the
task configuration of the Envoy proxy created as a sidecar or gateway.
2019-09-05 18:08:31 +00:00
2020-12-17 17:08:48 +00:00
- `gateway` - <code>([gateway][]:nil)</code> - This is used to configure the
gateway service created by Nomad for Consul Connect.
2019-09-05 18:08:31 +00:00
## `connect` Examples
2020-12-17 17:08:48 +00:00
### Using Connect Native
The following example is a minimal service block for a
[Consul Connect Native](/consul/docs/connect/native)
2020-12-17 17:08:48 +00:00
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 block with defaults and is
sufficient to start an Envoy proxy sidecar for allowing incoming connections
via Consul Connect.
2019-09-05 18:08:31 +00:00
```hcl
connect {
sidecar_service {}
}
```
The following example includes specifying [`upstreams`][upstreams].
2019-09-05 18:08:31 +00:00
```hcl
connect {
sidecar_service {
proxy {
upstreams {
destination_name = "count-api"
local_bind_port = 8080
}
}
}
}
2020-02-06 23:45:31 +00:00
```
2019-09-05 18:08:31 +00:00
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"
}
}
}
}
```
2020-12-17 17:08:48 +00:00
### Using a Gateway
The following is an example service block for creating and using a connect ingress
2020-12-17 17:08:48 +00:00
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
2020-12-17 17:08:48 +00:00
job "ingress-demo" {
2020-12-17 17:08:48 +00:00
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
2019-09-05 18:08:31 +00:00
[gateway]: /nomad/docs/job-specification/gateway
[gh-7221]: https://github.com/hashicorp/nomad/issues/7221
[group]: /nomad/docs/job-specification/group "Nomad group Job Specification"
[interpolation]: /nomad/docs/runtime/interpolation "Nomad interpolation"
[job]: /nomad/docs/job-specification/job "Nomad job Job Specification"
[native]: /consul/docs/connect/native
[service_task]: /nomad/docs/job-specification/service#task-1 "Nomad service task"
[sidecar_service]: /nomad/docs/job-specification/sidecar_service "Nomad sidecar service Specification"
[sidecar_task]: /nomad/docs/job-specification/sidecar_task "Nomad sidecar task config Specification"
[task]: /nomad/docs/job-specification/task "Nomad task Job Specification"
[upstreams]: /nomad/docs/job-specification/upstreams "Nomad sidecar service upstreams Specification"