From 7f4f28b6d74a19c3f8db2cf543f204f3058e57e1 Mon Sep 17 00:00:00 2001 From: Chris Piraino Date: Wed, 13 May 2020 16:29:40 -0500 Subject: [PATCH] Ingress and Terminating Gateway docs (#7710) This PR contains documentation additions for ingress and terminating gateways. New pages for the config-entries and overall feature description were added, as well as various additions to related pages. Co-authored-by: Jono Sosulska <42216911+jsosulska@users.noreply.github.com> Co-authored-by: freddygv Co-authored-by: Freddy Co-authored-by: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> --- website/data/docs-navigation.js | 10 +- website/pages/api-docs/agent/service.mdx | 11 +- website/pages/api-docs/catalog.mdx | 2 +- .../pages/docs/agent/config-entries/index.mdx | 24 ++- .../agent/config-entries/ingress-gateway.mdx | 159 ++++++++++++++++++ .../config-entries/terminating-gateway.mdx | 158 +++++++++++++++++ website/pages/docs/agent/dns.mdx | 16 ++ website/pages/docs/agent/services.mdx | 11 +- website/pages/docs/commands/connect/envoy.mdx | 23 +-- .../pages/docs/commands/intention/index.mdx | 7 + .../pages/docs/connect/ingress_gateway.mdx | 83 +++++++++ website/pages/docs/connect/mesh_gateway.mdx | 13 +- .../docs/connect/terminating_gateway.mdx | 134 +++++++++++++++ website/public/img/ingress-gateways.png | 3 + website/public/img/mesh-gateways.png | 4 +- website/public/img/terminating-gateways.png | 3 + 16 files changed, 624 insertions(+), 37 deletions(-) create mode 100644 website/pages/docs/agent/config-entries/ingress-gateway.mdx create mode 100644 website/pages/docs/agent/config-entries/terminating-gateway.mdx create mode 100644 website/pages/docs/connect/ingress_gateway.mdx create mode 100644 website/pages/docs/connect/terminating_gateway.mdx create mode 100644 website/public/img/ingress-gateways.png create mode 100644 website/public/img/terminating-gateways.png diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index b383332b8..d81c51c45 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -115,11 +115,13 @@ export default [ { category: 'config-entries', content: [ + 'ingress-gateway', + 'proxy-defaults', + 'service-defaults', + 'service-resolver', 'service-router', 'service-splitter', - 'service-resolver', - 'service-defaults', - 'proxy-defaults', + 'terminating-gateway', ], }, 'cloud-auto-join', @@ -156,6 +158,8 @@ export default [ }, 'mesh_gateway', 'wan-federation-via-mesh-gateways', + 'ingress_gateway', + 'terminating_gateway', { category: 'registration', content: ['service-registration', 'sidecar-service'], diff --git a/website/pages/api-docs/agent/service.mdx b/website/pages/api-docs/agent/service.mdx index 852c6df36..a28685cbf 100644 --- a/website/pages/api-docs/agent/service.mdx +++ b/website/pages/api-docs/agent/service.mdx @@ -513,13 +513,14 @@ service definition keys for compatibility with the config file format. - `Kind` `(string: "")` - The kind of service. Defaults to "" which is a typical Consul service. This value may also be "connect-proxy" for - services that are [Connect-capable](/docs/connect) - proxies representing another service or "mesh-gateway" for instances of - a [mesh gateway](/docs/connect/mesh_gateway) + [Connect](/docs/connect) proxies representing another service, + "mesh-gateway" for instances of a [mesh gateway](/docs/connect/mesh_gateway), + "terminating-gateway" for instances of a [terminating gateway](/docs/connect/terminating_gateway), + or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/ingress_gateway). - `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a - Connect proxy instance. This is only valid if `Kind == "connect-proxy"` or - `Kind == "mesh-gateway"`. See the [Proxy documentation](/docs/connect/registration/service-registration) + Connect service proxy instance. This is only valid if `Kind` defines a proxy or gateway. + See the [Proxy documentation](/docs/connect/registration/service-registration) for full details. - `Connect` `(Connect: nil)` - Specifies the diff --git a/website/pages/api-docs/catalog.mdx b/website/pages/api-docs/catalog.mdx index 1a320a3b5..88f7ceb7c 100644 --- a/website/pages/api-docs/catalog.mdx +++ b/website/pages/api-docs/catalog.mdx @@ -575,7 +575,7 @@ $ curl \ service instance. This includes both the address as well as the port. - `ServiceKind` is the kind of service, usually "". See the Agent - registration API for more information. + [service registration API](/api/agent/service#kind) for more information. - `ServiceProxy` is the proxy config as specified in [Connect Proxies](/docs/connect/proxies). diff --git a/website/pages/docs/agent/config-entries/index.mdx b/website/pages/docs/agent/config-entries/index.mdx index 074111ce5..cbcfc10d8 100644 --- a/website/pages/docs/agent/config-entries/index.mdx +++ b/website/pages/docs/agent/config-entries/index.mdx @@ -25,20 +25,26 @@ Name = "" The supported `Kind` names for configuration entries are: +- [`ingress-gateway`](/docs/agent/config-entries/ingress-gateway) - defines the + configuration for an ingress gateway + +- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - controls + proxy configuration + +- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures + defaults for all the instances of a given service + +- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches + service instances with a specific Connect upstream discovery requests + - [`service-router`](/docs/agent/config-entries/service-router) - defines where to send layer 7 traffic based on the HTTP route - [`service-splitter`](/docs/agent/config-entries/service-splitter) - defines how to divide requests for a single HTTP route based on percentages - -- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches - service instances with a specific Connect upstream discovery requests - -- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures - defaults for all the instances of a given service - -- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - controls - proxy configuration + +- [`terminating-gateway`](/docs/agent/config-entries/terminating-gateway) - defines the + services associated with terminating gateway ## Managing Configuration Entries diff --git a/website/pages/docs/agent/config-entries/ingress-gateway.mdx b/website/pages/docs/agent/config-entries/ingress-gateway.mdx new file mode 100644 index 000000000..ff34d3d20 --- /dev/null +++ b/website/pages/docs/agent/config-entries/ingress-gateway.mdx @@ -0,0 +1,159 @@ +--- +layout: docs +page_title: 'Configuration Entry Kind: Ingress Gateway' +sidebar_title: ingress-gateway +description: >- + The `ingress-gateway` config entry kind allows for configuring Ingress gateways + with listeners that expose a set of services outside the Consul service mesh. +--- + +# Ingress Gateway + +-> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer. + + The `ingress-gateway` config entry kind allows you to configure ingress gateways + with listeners that expose a set of services outside the Consul service mesh. + See [Ingress Gateway](/docs/connect/ingress_gateway) for more information. + +~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies + across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different + sets of services within their datacenter then the ingress gateways **must** be registered with different names. + + See [Ingress Gateway](/docs/connect/ingress_gateway) for more information. + +## Wildcard service specification + + Ingress gateways can optionally target all services within a Consul namespace by + specifying a wildcard `*` as the service name. A wildcard specifier allows + for a single listener to route traffic to all available services on the + Consul service mesh, differentiating between the services by their host/authority + header. + + A wildcard specifier provides the following properties for an ingress + gateway: + - All services with the same + [protocol](/docs/agent/config-entries/ingress-gateway#protocol) as the + listener will be routable. + - The ingress gateway will route traffic based on the host/authority header, + expecting a value matching `.*`, or if using namespaces, + `.ingress..*`. + + A wildcard specifier cannot be set on a listener of protocol `tcp`. + +## Sample Config Entries + +Set up a TCP listener for a single service: + +```hcl +Kind = "ingress-gateway" +Name = "ingress-service" + +Listeners = [ + { + Port = 3456 + Protocol = "tcp" + Services = [ + { + Name = "db" + } + ] + } +] +``` + +Set up a wildcard HTTP listener to proxy traffic to all available services, +make two services available over a custom port with user-provided hosts, and +enable TLS on every listener: + +```hcl +Kind = "ingress-gateway" +Name = "ingress-service" + +TLS { + Enabled = true +} + +Listeners = [ + { + Port = 8080 + Protocol = "http" + Services = [ + { + Name = "*" + } + ] + }, + { + Port = 4567 + Protocol = "http" + Services = [ + { + Name = "api" + Hosts = ["foo.example.com"] + }, + { + Name = "web" + Hosts = ["website.example.com"] + } + ] + } +] +``` + +## Available Fields + +- `Kind` - Must be set to `ingress-gateway` + +- `Name` `(string: )` - Set to the name of the gateway being configured. + +- `Namespace` `(string: "default")` - Specifies + the namespace the config entry will apply to. This must be the namespace + the gateway is registered in. If omitted, the namespace will be inherited + from [the request](/api/config#ns) or will default to the `default` namespace. + +- `TLS` `(TLSConfig: )` - TLS configuration for this gateway. + + - `Enabled` `(bool: false)` - Set this configuration to enable TLS for + every listener on the gateway. + +- `Listeners` `(array: )` - A list of listeners that + the ingress gateway should setup, uniquely identified by their port number. + + - `Port` `(int: 0)` - The port that the listener should receive traffic on. + + - `Protocol` `(string: "tcp")` - The protocol associated with the listener. + This can be any protocol supported by + [service-defaults](/docs/agent/config-entries/service-defaults#protocol). + + - `Services` `(array: )` - A list of services to be + exposed via this listener. For "tcp" listeners, only a single service is + allowed. + + - `Name` `(string: "")` - 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 only by [other config + entries](/docs/connect/l7-traffic-management). If the wildcard specifier, + `*`, is provided, then ALL services will be exposed through the listener. + This is not supported for listener's with protocol "tcp". + + - `Namespace` `(string: "")` - The namespace to resolve the service from + instead of the current namespace. If empty the current namespace is + assumed. + + - `Hosts` `(array: )` - A list of hosts that specify what + requests will match to this service. This cannot be used with a `tcp` + listener, and cannot be specified alongside a `*` service name. + + If TLS is enabled, then each host will be added as a DNSSAN to the + gateway's x509 certificate. + +## ACLs + +Configuration entries may be protected by +[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls). + +Reading an `ingress-gateway` config entry requires `service:read` on the `Name` +field of the config entry. + +Creating, updating, or deleting an `ingress-gateway` config entry requires +`operator:write`. diff --git a/website/pages/docs/agent/config-entries/terminating-gateway.mdx b/website/pages/docs/agent/config-entries/terminating-gateway.mdx new file mode 100644 index 000000000..70166aadb --- /dev/null +++ b/website/pages/docs/agent/config-entries/terminating-gateway.mdx @@ -0,0 +1,158 @@ +--- +layout: docs +page_title: 'Configuration Entry Kind: Terminating Gateway' +sidebar_title: terminating-gateway +description: >- + The `terminating-gateway` config entry kind allows for configuring terminating gateways + to proxy traffic from services in the Consul service mesh to services outside the mesh. +--- + +# Terminating Gateway + +-> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer. + + The `terminating-gateway` config entry kind you to configure terminating gateways + to proxy traffic from services in the Consul service mesh to services registered with Consul that do not have a + [Connect service sidecar proxy](/docs/connect/proxies). The configuration is associated with the name of a gateway service + and will apply to all instances of the gateway with that name. + +~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies + across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different + sets of services within their datacenter then the ingress gateways **must** be registered with different names. + + See [Terminating Gateway](/docs/connect/terminating_gateway) for more information. + +## TLS Origination + By specifying a path to a [CA file](/docs/agent/config-entries/terminating-gateway#cafile) connections + from the terminating gateway will be encrypted using one-way TLS authentication. If a path to a + [client certificate](/docs/agent/config-entries/terminating-gateway#certfile) + and [private key](/docs/agent/config-entries/terminating-gateway#keyfile) are also specified connections + from the terminating gateway will be encrypted using mutual TLS authentication. + + If none of these are provided, Consul will **only** encrypt connections to the gateway and not + from the gateway to the destination service. + +## Wildcard service specification + + Terminating gateways can optionally target all services within a Consul namespace by specifying a wildcard "*" + as the service name. Configuration options set on the wildcard act as defaults that can be overridden + by options set on a specific service name. + + Note that if the wildcard specifier is used, and some services in that namespace have a Connect sidecar proxy, + traffic from the mesh to those services will be evenly load-balanced between the gateway and their sidecars. + +## Sample Config Entries + +Link gateway "us-west-gateway" with the billing service: + +```hcl +Kind = "terminating-gateway" +Name = "us-west-gateway" +Services = [ + { + Name = "billing" + } +] +``` + +Link gateway "us-west-gateway" with the api service and specify a CA file for one-way TLS authentication: + +```hcl +Kind = "terminating-gateway" +Name = "us-west-gateway" +Services = [ + { + Name = "api" + CAFile = "/etc/certs/ca-chain.cert.pem" + } +] +``` + +Link gateway "us-west-gateway" with the payments service and specify a CA file, key file, and cert file for mutual TLS authentication: + +```hcl +Kind = "terminating-gateway" +Name = "us-west-gateway" +Services = [ + { + Name = "payments" + CAFile = "/etc/certs/ca-chain.cert.pem" + KeyFile = "/etc/certs/gateway.key.pem" + CertFile = "/etc/certs/gateway.cert.pem" + } +] +``` + +Link gateway "us-west-gateway" with all services in the finance namespace, and configure default certificates for mutual TLS. +Also override the SNI and CA file used for connections to the billing service: + +```hcl +Kind = "terminating-gateway" +Name = "us-west-gateway" +Namespace = "default" +Services = [ + { + Namespace = "finance" + Name = "*" + CAFile = "/etc/common-certs/ca-chain.cert.pem" + KeyFile = "/etc/common-certs/gateway.key.pem" + CertFile = "/etc/common-certs/gateway.cert.pem" + }, + { + Namespace = "finance" + Name = "billing" + CAFile = "/etc/billing-ca/ca-chain.cert.pem" + SNI = "billing.service.com" + } +] +``` + +## Available Fields + +- `Kind` - Must be set to `terminating-gateway` + +- `Name` `(string: )` - Set to the name of the gateway being configured. + +- `Namespace` `(string: "default")` - Specifies the namespace + the config entry will apply to. This must be the namespace the gateway is registered in. + If omitted, the namespace will be inherited from [the request](/api/config#ns) + or will default to the `default` namespace. + +- `Services` `(array: )` - A list of services to link + with the gateway. The gateway will proxy traffic to these services. These linked services + must be registered with Consul for the gateway to discover their addresses. They must also + be registered in the same Consul datacenter as the terminating gateway. + + - `Name` `(string: "")` - The name of the service to link with the gateway. + If the wildcard specifier, `*`, is provided, then ALL services within the namespace + will be linked with the gateway. + + - `Namespace` `(string: "")` - The namespace of the service. + If omitted, the namespace will be inherited from the config entry. + + - `CAFile` `(string: "")` - A file path to a PEM-encoded certificate authority. + The file must be present on the proxy's filesystem. + The certificate authority is used to verify the authenticity of the service linked with the gateway. + It can be provided along with a CertFile and KeyFile for mutual TLS authentication, or on its own + for one-way TLS authentication. If none is provided the gateway **will not** encrypt the traffic to the destination. + + - `CertFile` `(string: "")` - A file path to a PEM-encoded certificate. + The file must be present on the proxy's filesystem. + The certificate is provided servers to verify the gateway's authenticity. It must be provided if a KeyFile was specified. + + - `KeyFile` `(string: "")` - A file path to a PEM-encoded private key. + The file must be present on the proxy's filesystem. + The key is used with the certificate to verify the gateway's authenticity. It must be provided along if a CertFile was specified. + + - `SNI` `(string: "")` - An optional hostname or domain name to specify during the TLS handshake. + +## ACLs + +Configuration entries may be protected by +[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls). + +Reading a `terminating-gateway` config entry requires `service:read` on the `Name` +field of the config entry. + +Creating, updating, or deleting a `terminating-gateway` config entry requires +`operator:write`. diff --git a/website/pages/docs/agent/dns.mdx b/website/pages/docs/agent/dns.mdx index 82d599d5c..315e08e49 100644 --- a/website/pages/docs/agent/dns.mdx +++ b/website/pages/docs/agent/dns.mdx @@ -256,6 +256,22 @@ and doesn't support tags. This DNS interface will be expanded over time. If you need more complex behavior, please use the [catalog API](/api/catalog). +### Ingress Service Lookups + +To find ingress-enabled services: + +```text +.ingress. +``` + +This will find all [ingress gateway](/docs/connect/ingress_gateway) +endpoints for the given `service`. + +This endpoint currently only finds services within the same datacenter +and doesn't support tags. This DNS interface will be expanded over time. +If you need more complex behavior, please use the +[catalog API](/api/catalog). + ### UDP Based DNS Queries When the DNS query is performed using UDP, Consul will truncate the results diff --git a/website/pages/docs/agent/services.mdx b/website/pages/docs/agent/services.mdx index d0cc7d588..1e898c20f 100644 --- a/website/pages/docs/agent/services.mdx +++ b/website/pages/docs/agent/services.mdx @@ -189,11 +189,14 @@ for the available configuration options. ### Connect The `kind` field is used to optionally identify the service as a [Connect -proxy](/docs/connect/proxies) instance with the value `connect-proxy` or -a [Mesh Gateway](/docs/connect/mesh_gateway) instance with the value `mesh-gateway`. For -typical non-proxy instances the `kind` field must be omitted. The `proxy` field +proxy](/docs/connect/proxies) instance. This value may be "connect-proxy" for +[Connect-capable](/docs/connect) proxies representing another service, +"mesh-gateway" for instances of a [mesh gateway](/docs/connect/mesh_gateway), +"terminating-gateway" for instances of a [terminating gateway](/docs/connect/terminating_gateway), +or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/ingress_gateway). +For typical non-proxy instances the `kind` field must be omitted. The `proxy` field is also required for Connect proxy registrations and is only valid if `kind` is -`connect-proxy`. The only required `proxy` field is `destination_service_name`. +`connect-proxy`. The only required `proxy` field for a `connect-proxy` is `destination_service_name`. For more detail please see [complete proxy configuration example](/docs/connect/registration/service-registration#complete-configuration-example) diff --git a/website/pages/docs/commands/connect/envoy.mdx b/website/pages/docs/commands/connect/envoy.mdx index f59555e18..4af63b129 100644 --- a/website/pages/docs/commands/connect/envoy.mdx +++ b/website/pages/docs/commands/connect/envoy.mdx @@ -103,7 +103,7 @@ proxy configuration needed. #### Envoy Gateway Options - `-gateway` - Flag to indicate that Envoy should be configured as a Gateway. - Must be one of: `terminating` or `mesh`. + Must be one of: `terminating`, `ingress`, or `mesh`. If multiple gateways are managed by the same local agent then `-proxy-id` should be used as well to specify the instance this represents. @@ -127,12 +127,6 @@ proxy configuration needed. - `-deregister-after-critical` - The amount of time the gateway services health check can be failing before being deregistered. This flag is used in combination with `-register` --> **Note:** If ACLs are enabled, a token granting `service:write` for the -gateway's service name must be passed using the `-token` option or -`CONSUL_HTTP_TOKEN` environment variable. This token authorizes the proxy -to obtain receive and route communications for other Connect services but -does not allow decrypting any of their communications. - ## Examples Assume a local service instance is registered on the local agent with a @@ -180,7 +174,7 @@ $ consul connect envoy -sidecar-for db -admin-bind localhost:19001 ### Mesh Gateways -The mesh gateway Envoy process can be started with. +The mesh gateway Envoy process can be auto-registered and started with the following command. ```shell $ consul connect envoy -gateway=mesh -register \ @@ -190,13 +184,22 @@ $ consul connect envoy -gateway=mesh -register \ ### Terminating Gateways -The terminating gateway Envoy process can be started with. +The terminating gateway Envoy process can be auto-registered and started with the following command. ```shell -$ consul connect envoy -gateway=terminating -register \ +$ consul connect envoy -gateway=terminating -register -service my-gateway \ -address '{{ GetInterfaceIP "eth0" }}:8443' ``` +### Ingress Gateways + +The ingress gateway Envoy process can be auto-registered and started with the following command. + +```shell +$ consul connect envoy -gateway=ingress -register -service ingress-service \ + -address '{{ GetInterfaceIP "eth0" }}:8888' +``` + ## Exec Security Details The command needs to pass the bootstrap config through to Envoy. Envoy currently diff --git a/website/pages/docs/commands/intention/index.mdx b/website/pages/docs/commands/intention/index.mdx index eba4ea911..d549c3db2 100644 --- a/website/pages/docs/commands/intention/index.mdx +++ b/website/pages/docs/commands/intention/index.mdx @@ -46,6 +46,13 @@ Create an intention to allow "web" to talk to "db": $ consul intention create web db ``` +Create an intention to deny "db" from initiating connections to _any_ service: + +```shell +$ consul intention create -deny db '*' +Created: db => * (deny) +``` + Test whether a "web" is allowed to connect to "db": ```shell diff --git a/website/pages/docs/connect/ingress_gateway.mdx b/website/pages/docs/connect/ingress_gateway.mdx new file mode 100644 index 000000000..fd4b2d65b --- /dev/null +++ b/website/pages/docs/connect/ingress_gateway.mdx @@ -0,0 +1,83 @@ +--- +layout: docs +page_title: Connect - Ingress Gateways +sidebar_title: Ingress Gateways +description: >- + An ingress gateway enables ingress traffic from services outside the Consul + service mesh to services inside the Consul service mesh. This section details + how to use Envoy and describes how you can plug in a gateway of your choice. +--- + +# Ingress Gateways + +-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer. + +Ingress gateways enable ingress traffic from services outside the Consul +service mesh to services inside the Consul service mesh. An ingress gateway is +a type of proxy and must be registered as a service in Consul, with the +[kind](/api/agent/service#kind) set to "ingress-gateway". They are an +entrypoint for outside traffic and allow you to define what services should be +exposed and on what port. You configure an ingress gateway by defining a set of +[listeners](/docs/agent/config-entries/ingress-gateway#listeners) that each map +to a set of backing +[services](/docs/agent/config-entries/ingress-gateway#services). + +Depending on the +[protocol](/docs/agent/config-entries/ingress-gateway#protocol) defined for a +listener, multiple services can be specified for a single listener. In this +case, the ingress gateway relies on host/authority headers to decide the +service that should receive the traffic. + +To enable easier service discovery, a new Consul [DNS +subdomain](/docs/agent/dns#ingress-service-lookups) is provided, on +`.ingress.`. + +![Ingress Gateway Architecture](/img/ingress-gateways.png) + +## Prerequisites + +Ingress gateways also require that your Consul datacenters are configured correctly: + +- You'll need to use Consul version 1.8.0. +- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers. +- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents. + +Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul. + +## Running and Using an Ingress Gateway + +You must complete the following steps to configure an ingress gateway to proxy traffic to services in the Consul service mesh: + +1. On a host with a Consul client agent, start an Envoy proxy using the [envoy +subcommand](/docs/commands/connect/envoy), specifying the `ingress` gateway +type: + ```shell + $ consul connect envoy -gateway=ingress -register -service ingress-service \ + -address '{{ GetInterfaceIP "eth0" }}:8888' + ``` + +2. Create and apply an `ingress-gateway` [configuration entry](/docs/agent/config-entries/ingress-gateway) that defines +a set of listeners that expose the desired backing services. The config entry can be applied via the +[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration). + +3. Ensure that [Consul intentions](/docs/commands/intention) are setup to allow connections from the ingress gateway to the backing services. + +4. **Optionally** use the `.ingress.` [DNS subdomain](/docs/agent/dns#ingress-service-lookups) to discover the ingress +gateways for a service. + +## Ingress Gateway Configuration + +Ingress gateways are configured in service definitions and registered with Consul like other services, with two exceptions. +The first is that the [kind](/api/agent/service#kind) must be "ingress-gateway". Second, +the ingress gateway service definition may contain a `Proxy.Config` entry just like a +Connect proxy service, to define opaque configuration parameters useful for the actual proxy software. +For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as +[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides). + +-> **Note:** If ACLs are enabled, a token granting `service:write` for the gateway's service name +and `service:read` for all services in the datacenter. These permissions authorize the token to route +communications for other Connect services. + +~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies + across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different + sets of services within their datacenter then the ingress gateways **must** be registered with different names. diff --git a/website/pages/docs/connect/mesh_gateway.mdx b/website/pages/docs/connect/mesh_gateway.mdx index 2bdc9f62d..c05652e01 100644 --- a/website/pages/docs/connect/mesh_gateway.mdx +++ b/website/pages/docs/connect/mesh_gateway.mdx @@ -77,9 +77,16 @@ your network, the proxy's connection to the gateway can happen in one of the fol ## Mesh Gateway Configuration -Mesh gateways are defined very similarly to other typical services. The one exception is that a mesh gateway -service definition may contain a `Proxy.Config` entry just like a Connect proxy service to define opaque -configuration parameters useful for the actual proxy software. +Mesh gateways are defined similarly to other services registered with Consul, with two exceptions. +The first is that the [service kind](/api/agent/service#kind) must be "mesh-gateway". Second, +the mesh gateway service definition may contain a `Proxy.Config` entry just like a +Connect proxy service, to define opaque configuration parameters useful for the actual proxy software. +For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as +[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides). + +-> **Note:** If ACLs are enabled, a token granting `service:write` for the gateways service name +and `service:read` for all services in the datacenter. These permissions authorize the token to route +communications for other Connect services but does not allow decrypting any of their communications. ## Connect Proxy Configuration diff --git a/website/pages/docs/connect/terminating_gateway.mdx b/website/pages/docs/connect/terminating_gateway.mdx new file mode 100644 index 000000000..d229b41eb --- /dev/null +++ b/website/pages/docs/connect/terminating_gateway.mdx @@ -0,0 +1,134 @@ +--- +layout: docs +page_title: Connect - Terminating Gateways +sidebar_title: Terminating Gateways +description: >- + A terminating gateway enables traffic from services in the Consul + service mesh to services outside the mesh. This section details + how to configure and run a terminating gateway. +--- + +# Terminating Gateways + +-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer. + +Terminating gateways enable connections from services in the Consul service mesh to +services outside the mesh. These gateways effectively act as Connect proxies that can +represent more than one service. They terminate Connect mTLS connections, enforce intentions, +and forward requests to the appropriate destination. + +![Terminating Gateway Architecture](/img/terminating-gateways.png) + +~> **Beta limitations:** Terminating Gateways currently do not support targeting service subsets with +[L7 configuration](/docs/connect/l7-traffic-management). They route to all instances of a service with no capabilities +for filtering by instance. Terminating Gateways also currently do not support routing to services with a hostname +defined as a their address. The service address registered with Consul, that the gateway will route traffic to, **must** be a resolved IP address. + +## Security Considerations + +~> We recommend that terminating gateways are not exposed to the WAN or open internet. This is because terminating gateways +hold certificates to decrypt Consul Connect traffic directed at them and may be configured with credentials to connect +to linked services. Connections over the WAN or open internet should flow through [mesh gateways](/docs/connect/mesh_gateway) +whenever possible since they are not capable of decrypting traffic or connecting directly to services. + +By specifying a path to a [CA file](/docs/agent/config-entries/terminating-gateway#cafile) connections +from the terminating gateway will be encrypted using one-way TLS authentication. If a path to a +[client certificate](/docs/agent/config-entries/terminating-gateway#certfile) +and [private key](/docs/agent/config-entries/terminating-gateway#keyfile) are also specified connections +from the terminating gateway will be encrypted using mutual TLS authentication. + +If none of these are provided, Consul will **only** encrypt connections to the gateway and not +from the gateway to the destination service. + +-> **Note:** If certificates and keys are configured the terminating gateway will upgrade HTTP connections to TLS. +Client applications can issue plain HTTP requests even when connecting to servers that require HTTPS. + +## Prerequisites + +Each terminating gateway needs: + +1. A local Consul client agent to manage its configuration. +2. General network connectivity to services within its local Consul datacenter. + +Terminating gateways also require that your Consul datacenters are configured correctly: + +- You'll need to use Consul version 1.8.0. +- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers. +- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents. + +Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with terminating gateway capabilities in Consul. + +- Terminating gateway proxies receive their configuration through Consul, which + automatically generates it based on the gateway's registration. Currently Consul + can only translate terminating gateway registration information into Envoy + configuration, therefore the proxies acting as terminating gateways must be Envoy. + +Connect proxies that send upstream traffic through a gateway aren't +affected when you deploy terminating gateways. If you are using non-Envoy proxies as +Connect proxies they will continue to work for traffic directed at services linked to +a terminating gateway as long as they discover upstreams with the +[/health/connect](/api/health#list-nodes-for-connect-capable-service) endpoint. + +## Running and Using a Terminating Gateway + +You must complete the following steps to configure a terminating gateway to proxy traffic from services in the Consul service mesh: + +1. On a host with a Consul client agent, start an Envoy proxy using the [envoy subcommand](/docs/commands/connect/envoy#terminating-gateways) and +specifying the `terminating` gateway type: + ```shell + $ consul connect envoy -gateway=terminating -register -service us-west-gateway \ + -address '{{ GetInterfaceIP "eth0" }}:8443' + ``` + +2. Create and apply a `terminating-gateway` [configuration entry](/docs/agent/config-entries/terminating-gateway) that defines +a set of services that the gateway will proxy traffic to. The config entry can be applied via the +[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration). + +3. Ensure that [Consul intentions](/docs/commands/intention) are set up to allow connections from the source services in the mesh +to the gateway's linked services. The intentions must reference the destination service's name and not the gateway itself. + +4. Ensure necessary [upstreams](/docs/connect/registration/service-registration#upstream-configuration-reference) +have been added to service definitions of the source services in the Consul service mesh. Each source service that needs +to connect to a service proxied by a terminating gateway will need to add the external service as an upstream destination. + +## Terminating Gateway Configuration + +Terminating gateways are configured in service definitions and registered with Consul like other services, with two exceptions. +The first is that the [kind](/api/agent/service#kind) must be "terminating-gateway". Second, +the terminating gateway service definition may contain a `Proxy.Config` entry just like a +Connect proxy service, to define opaque configuration parameters useful for the actual proxy software. +For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as +[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides). + +-> **Note:** If ACLs are enabled, the terminating gateways must be registered with a token granting `service:write` +for the gateway's service name **and** all linked services. These privileges will authorize the gateway +to terminate mTLS connections on behalf of the linked services. + +Linking services to a terminating gateway is done with a `terminating-gateway` +[configuration entry](/docs/agent/config-entries/terminating-gateway). This config entry can be applied via the +[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration). + +Gateways with the same name in Consul's service catalog are configured with a single configuration entry. +This means that additional gateway instances registered with the same name will determine their routing based on the existing configuration entry. +Adding replicas of a gateway that routes to a particular set of services requires running the +[envoy subcommand](/docs/commands/connect/envoy#terminating-gateways) on additional hosts and specifying +the same gateway name with the `service` flag. + +~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies + across all federated Consul datacenters. If terminating gateways in different Consul datacenters need to route to different + sets of services within their datacenter then the terminating gateways **must** be registered with different names. + +The services that the terminating gateway will proxy for must be registered with Consul, even the services outside the mesh. They must also be registered +in the same Consul datacenter as the terminating gateway. Otherwise the terminating gateway will not be able to +discover the services' addresses. These services can be registered with a local Consul agent. +If there is no agent present, the services can be registered [directly in the catalog](/api/catalog#register-entity) +by sending the registration request to a client or server agent on a different host. + +All services registered in the Consul catalog must be associated with a node, even when their node is +not managed by a Consul client agent. All agent-less services with the same address can be registered under the same node name and address. +However, ensure that the [node name](/api/catalog.html#node) for external services registered directly in the catalog +does not match the node name of any Consul client agent node. If the node name overlaps with the node name of a Consul client agent, +Consul's [anti-entropy sync](/docs/internals/anti-entropy) will delete the services registered via the `/catalog/register` HTTP API endpoint. + +For a complete example of how to register external services review the +[external services guide](https://learn.hashicorp.com/consul/developer-discovery/external). diff --git a/website/public/img/ingress-gateways.png b/website/public/img/ingress-gateways.png new file mode 100644 index 000000000..d792c951e --- /dev/null +++ b/website/public/img/ingress-gateways.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:81a56a08651e87bb8dd33fd1b2753559cea3beef34dadf998cea050901d623d4 +size 116596 diff --git a/website/public/img/mesh-gateways.png b/website/public/img/mesh-gateways.png index 4bb67d135..5ffbf8d73 100644 --- a/website/public/img/mesh-gateways.png +++ b/website/public/img/mesh-gateways.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:fbc2aadb022808c0a73036941c06ed15f0e159c26243aaed748f5d762dd1b99a -size 79522 +oid sha256:0765ea160880320001f125525ef2a20da8abd0e5ee71f4ff582662bfdd68798e +size 180698 diff --git a/website/public/img/terminating-gateways.png b/website/public/img/terminating-gateways.png new file mode 100644 index 000000000..f4f97a64b --- /dev/null +++ b/website/public/img/terminating-gateways.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f6ebdfe4909e27adaacb295775ab064647aa37709c5a1e51da025ce7520c5b62 +size 121090