luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-nomad/website/pages/docs/job-specification/gateway.mdx
Seth Hoenig 5b072029f2 consul/connect: add initial support for ingress gateways 
This PR adds initial support for running Consul Connect Ingress Gateways (CIGs) in Nomad. These gateways are declared as part of a task group level service definition within the connect stanza.

```hcl
service {
  connect {
    gateway {
      proxy {
        // envoy proxy configuration
      }
      ingress {
        // ingress-gateway configuration entry
      }
    }
  }
}
```

A gateway can be run in `bridge` or `host` networking mode, with the caveat that host networking necessitates manually specifying the Envoy admin listener (which cannot be disabled) via the service port value.

Currently Envoy is the only supported gateway implementation in Consul, and Nomad only supports running Envoy as a gateway using the docker driver.

Aims to address #8294 and tangentially #8647
2020-08-21 16:21:54 -05:00

208 lines
8.3 KiB
Plaintext
Raw Blame History

---
layout: docs
page_title: gateway Stanza - Job Specification
sidebar_title: gateway
description: |-
The "gateway" stanza allows specifying options for configuring Consul Gateways
used in the Consul Connect integration
---
# `gateway` Stanza
<Placement
groups={[
'job',
'group',
'service',
'connect',
'gateway',
]}
/>
The `gateway` stanza allows configuration of [Consul Connect Gateways](https://www.consul.io/docs/connect/gateways). Nomad will
automatically create the necessary Gateway [Configuration Entry](https://www.consul.io/docs/agent/config-entries)
as well as inject an Envoy proxy task into the Nomad job to serve as the Gateway.
The `gateway` configuration is valid within the context of a `connect` stanza.
Additional information about Gateway configurations can be found in Consul's
[Connect Gateways](https://www.consul.io/docs/connect/gateways) documentation.
~> **Note:** [Ingress Gateways](https://www.consul.io/docs/connect/gateways/ingress-gateway)
are generally intended for enabling access into a Consul service mesh from within the
same network. For public ingress products like [NGINX](https://learn.hashicorp.com/tutorials/nomad/load-balancing-nginx?in=nomad/load-balancing)
provide more suitable features.
```hcl
job "ingress-example" {
datacenters = ["dc1"]
group "ingress-group" {
network {
mode = "bridge"
port "inbound" {
static = 8080
}
}
service {
name = "ingress-service"
port = "8080"
connect {
gateway {
proxy {
// Consul Gateway Proxy configuration options
connect_timeout = "500ms"
}
ingress {
// Consul Ingress Gateway Configuration Entry
tls {
enabled = false
}
listener {
port = 8080
protocol = "http"
service {
name = "web"
hosts = ["example.com", "example.com:8080"]
}
}
listener {
port = 3306
protocol = "tcp"
service {
name = "database"
}
}
}
}
}
}
}
}
```
## `gateway` Parameters
- `proxy` <code>([proxy]: nil)</code> - Configuration of the Envoy proxy that will
be injected into the task group.
- `ingress` <code>([ingress]: nil)</code> - Configuration Entry of type `ingress-gateway`
that will be associated with the service.
### `proxy` Parameters
- `connect_timeout` `(string: "5s")` - The amount of time to allow when making upstream
connections before timing out. Defaults to 5 seconds. If the upstream service has
the configuration option <code>[connect_timeout_ms]</code> set for the `service-resolver`, that
timeout value will take precedence over this gateway proxy option.
- `envoy_gateway_bind_tagged_addresses` `(bool: false)` - Indicates that the gateway
services tagged addresses should be bound to listeners in addition to the default
listener address.
- `envoy_gateway_bind_addresses` <code>(map<string|[address]>: nil)</code> - A map of additional addresses to be bound.
The keys to this map are the same of the listeners to be created and the values are
a map with two keys - address and port, that combined make the address to bind the
listener to. These are bound in addition to the default address.
If `bridge` networking is in use, this map is automatically populated with additional
listeners enabling the Envoy proxy to work from inside the network namespace.
```
envoy_gateway_bind_addresses "<service>" {
address = "0.0.0.0"
port = <port>
}
```
- `envoy_gateway_no_default_bind` `(bool: false)` - Prevents binding to the default
address of the gateway service. This should be used with one of the other options
to configure the gateway's bind addresses. If `bridge` networking is in use, this
value will default to `true` since the Envoy proxy does not need to bind to the
service address from inside the network namespace.
- `config` `(map: nil)` - Escape hatch for [Advanced Configuration] of Envoy.
#### `address` Parameters
- `address` `(string: required)` - The address to bind to when combined with `port`.
- `port` `(int: required)` - The port to listen to.
### `ingress` Parameters
- `tls` <code>([tls]: nil)</code> - TLS configuration for this gateway.
- `listener` <code>(array<[listener]> : required)</code> - One or more listeners that the
ingress gateway should setup, uniquely identified by their port number.
#### `tls` Parameters
- `enabled` `(bool: false)` - Set this configuration to enable TLS for every listener
on the gateway. If TLS is enabled, then each host defined in the `host` field will
be added as a DNSSAN to the gateway's x509 certificate.
#### `listener` Parameters
- `port` `(int: required)` - The port that the listener should receive traffic on.
- `protocol` `(string: "tcp")` - The protocol associated with the listener. Either
`tcp` or `http`.
~> **Note:** If using `http`, preconfiguring a [service-default] in Consul to
set the [Protocol](https://www.consul.io/docs/agent/config-entries/service-defaults#protocol)
of the service to `http` is recommended.
- `service` <code>(array<[service]>: required)</code> - One or more services to be
exposed via this listener. For `tcp` listeners, only a single service is allowed.
#### `service` Parameters
- `name` `(string: required)` - The name of the service that should be exposed through
this listener. This can be either a service registered in the catalog, or a
service defined by other config entries, or a service that is going to be configured
by Nomad. If the wildcard specifier `*` is provided, then ALL services will be
exposed through this listener. This is not supported for a listener with protocol `tcp`.
- `hosts` `(array<string>: nil)` - A list of hosts that specify what requests will
match this service. This cannot be used with a `tcp` listener, and cannot be
specified alongside a wildcard (`*`) service name. If not specified, the default
domain `<service-name>.ingress.*` will be used to match services. Requests *must*
send the correct host to be routed to the defined service.
The wildcard specifier `*` can be used by itself to match all traffic coming to
the ingress gateway, if TLS is not enabled. This allows a user to route all traffic
to a single service without specifying a host, allowing simpler tests and demos.
Otherwise, the wildcard specifier can be used as part of the host to match
multiple hosts, but only in the leftmost DNS label. This ensures that all defined
hosts are valid DNS records. For example, `*.example.com` is valid while `example.*`
and `*-suffix.example.com` are not.
~> **Note:** If a well-known port is not used, i.e. a port other than 80 (http) or 443 (https),
then the port must be appended to the host to correctly match traffic. This is
defined in the [HTTP/1.1 RFC](https://tools.ietf.org/html/rfc2616#section-14.23).
If TLS is enabled, then the host **without** the port must be added to the `hosts`
field as well. TLS verification only matches against the hostname of the incoming
connection, and does not take into account the port.
### Gateway with host networking
Nomad supports running gateways using host networking. A static port must be allocated
for use by the [Envoy admin interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin)
and assigned to the proxy service definition.
!> **Warning:** There is no way to disable the Envoy admin interface, which will be
accessible to any workload running on the same Nomad client. The admin interface exposes
information about the proxy, including a Consul Service Identity token if Consul ACLs
are enabled.
[proxy]: /docs/job-specification/gateway#proxy-parameters
[ingress]: /docs/job-specification/gateway#ingress-parameters
[tls]: /docs/job-specification/gateway#tlsconfig-parameters
[listener]: /docs/job-specification/gateway#listener-parameters
[service]: /docs/job-specification/gateway#service-parameters
[service-default]: https://www.consul.io/docs/agent/config-entries/service-defaults
[connect_timeout_ms]: https://www.consul.io/docs/agent/config-entries/service-resolver#connecttimeout
[address]: /docs/job-specification/gateway#address-parameters
[Advanced Configuration]: https://www.consul.io/docs/connect/proxies/envoy#advanced-configuration
Reference in a new issue View git blame Copy permalink