From 28f22c8a907681ef616db5b1fbdab82acac271c4 Mon Sep 17 00:00:00 2001 From: Freddy Date: Thu, 18 Jun 2020 15:27:06 -0600 Subject: [PATCH] Finalize gateway documentation for 1.8.0 GA (#8121) Co-authored-by: Derek Strickland <1111455+DerekStrickland@users.noreply.github.com> --- website/data/docs-navigation.js | 2 +- .../agent/config-entries/ingress-gateway.mdx | 4 +- .../config-entries/terminating-gateway.mdx | 4 +- .../pages/docs/connect/ingress-gateway.mdx | 26 +++---------- .../docs/connect/terminating-gateway.mdx | 39 +++++++------------ .../wan-federation-via-mesh-gateways.mdx | 2 +- 6 files changed, 24 insertions(+), 53 deletions(-) diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 8e0931d4a6..f59b4e4e9c 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -221,7 +221,7 @@ export default [ }, { category: 'multi-cluster', - name: 'Multi-Cluster Federation Beta ', + name: 'Multi-Cluster Federation', content: ['overview', 'kubernetes', 'vms-and-kubernetes'], }, ], diff --git a/website/pages/docs/agent/config-entries/ingress-gateway.mdx b/website/pages/docs/agent/config-entries/ingress-gateway.mdx index 0e978abcd6..44c55bc9f1 100644 --- a/website/pages/docs/agent/config-entries/ingress-gateway.mdx +++ b/website/pages/docs/agent/config-entries/ingress-gateway.mdx @@ -1,13 +1,13 @@ --- layout: docs page_title: 'Configuration Entry Kind: Ingress Gateway' -sidebar_title: ingress-gateway Beta +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 Beta +# Ingress Gateway -> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer. diff --git a/website/pages/docs/agent/config-entries/terminating-gateway.mdx b/website/pages/docs/agent/config-entries/terminating-gateway.mdx index d19575573b..523da96814 100644 --- a/website/pages/docs/agent/config-entries/terminating-gateway.mdx +++ b/website/pages/docs/agent/config-entries/terminating-gateway.mdx @@ -1,13 +1,13 @@ --- layout: docs page_title: 'Configuration Entry Kind: Terminating Gateway' -sidebar_title: terminating-gateway Beta +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 Beta +# Terminating Gateway -> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer. diff --git a/website/pages/docs/connect/ingress-gateway.mdx b/website/pages/docs/connect/ingress-gateway.mdx index 1dcee7034c..81f9da2d3e 100644 --- a/website/pages/docs/connect/ingress-gateway.mdx +++ b/website/pages/docs/connect/ingress-gateway.mdx @@ -1,14 +1,14 @@ --- layout: docs page_title: Connect - Ingress Gateways -sidebar_title: Ingress Gateways Beta +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 Beta +# Ingress Gateways -> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer. @@ -41,7 +41,7 @@ the [hosts](/docs/agent/config-entries/ingress-gateway#hosts) field. Ingress gateways also require that your Consul datacenters are configured correctly: -- You'll need to use Consul version 1.8.0. +- You'll need to use Consul version 1.8.0 or newer. - 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. @@ -49,24 +49,8 @@ Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress ga ## 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. +For a complete example of how to allow external traffic inside your Consul service mesh, +review the [ingress gateway guide](https://learn.hashicorp.com/consul/developer-mesh/ingress-gateways). 5. **Optionally** use the [Consul L7 traffic management](/docs/connect/l7-traffic-management) for exposed services to route traffic. diff --git a/website/pages/docs/connect/terminating-gateway.mdx b/website/pages/docs/connect/terminating-gateway.mdx index bb3b1ee908..013e88a8da 100644 --- a/website/pages/docs/connect/terminating-gateway.mdx +++ b/website/pages/docs/connect/terminating-gateway.mdx @@ -1,14 +1,14 @@ --- layout: docs page_title: Connect - Terminating Gateways -sidebar_title: Terminating Gateways Beta +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 Beta +# Terminating Gateways -> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer. @@ -19,10 +19,10 @@ and forward requests to the appropriate destination. ![Terminating Gateway Architecture](/img/terminating-gateways.png) -For a complete example of how to enable connections from services in the Consul service mesh to -services outside the mesh, review the [terminating gateway guide](https://learn.hashicorp.com/consul/developer-mesh/terminating-gateways). +For additional use cases and usage patterns, review the guide for +[understanding terminating gateways](https://learn.hashicorp.com/consul/developer-mesh/understand-terminating-gateways). -~> **Beta limitations:** Terminating Gateways currently do not support targeting service subsets with +~> **Known 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. @@ -42,6 +42,11 @@ 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. +When certificates for linked services are rotated, the gateway must be restarted to pick up the new certificates from disk. +To avoid downtime, perform a rolling restart to reload the certificates. Registering multiple terminating gateway instances +with the same [name](https://www.consul.io/docs/commands/connect/envoy#service) provides additional fault tolerance +as well as the ability to perform rolling restarts. + -> **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. @@ -54,7 +59,7 @@ Each terminating gateway needs: Terminating gateways also require that your Consul datacenters are configured correctly: -- You'll need to use Consul version 1.8.0. +- You'll need to use Consul version 1.8.0 or newer. - 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. @@ -73,26 +78,8 @@ a terminating gateway as long as they discover upstreams with the ## 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. +For a complete example of how to enable connections from services in the Consul service mesh to +services outside the mesh, review the [terminating gateway guide](https://learn.hashicorp.com/consul/developer-mesh/terminating-gateways). ## Terminating Gateway Configuration diff --git a/website/pages/docs/connect/wan-federation-via-mesh-gateways.mdx b/website/pages/docs/connect/wan-federation-via-mesh-gateways.mdx index 0e089f9a0e..1e6395f54f 100644 --- a/website/pages/docs/connect/wan-federation-via-mesh-gateways.mdx +++ b/website/pages/docs/connect/wan-federation-via-mesh-gateways.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: Connect - WAN Federation via Mesh Gateways -sidebar_title: WAN Federation via Mesh Gateways Beta +sidebar_title: WAN Federation via Mesh Gateways description: |- WAN federation via mesh gateways allows for Consul servers in different datacenters to be federated exclusively through mesh gateways. ---