From 569cf68daa98cd5b9c4e3271c0832b9e720e4182 Mon Sep 17 00:00:00 2001 From: Chris Thain Date: Mon, 20 Jun 2022 09:07:44 -0700 Subject: [PATCH] Add mesh gateway configuration examples. --- .../content/docs/ecs/terraform/install.mdx | 134 +++++++++++++++++- 1 file changed, 133 insertions(+), 1 deletion(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index 0e690e560..122601912 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -79,7 +79,139 @@ The following fields are required. Refer to the [module reference documentation] | `container_definitions` | list | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. | | `essential` | boolean | Must be `true` to ensure the health of your application container affects the health status of the task. | | `port` | integer | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`. | -| `retry_join` | list | The is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul agent, which specifies the locations of your Consul servers. | +| `retry_join` | list | This is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul agent, which specifies the locations of your Consul servers. | + +## Configuring a Mesh Gateway + +The `gateway-task` Terraform module can be used to deploy mesh gateways to enable service to service communication across the WAN. +Mesh gateways can also be used to federate service mesh traffic across Consul admin partitions and Consul datacenters over the WAN. + +~> This topic requires familiarity with [mesh gateways](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters). + +Using the `gateway-task` module to deploy mesh gateways requires that all Consul server and client agents in all datacenters have TLS and gossip encryption enabled. +Mesh gateways operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested. + +The following example shows a Terraform configuration that creates a mesh gateway task called `my-gateway` in a file called `mesh-gateway.tf`: + + + +```hcl +module "my_mesh_gateway" { + source = "hashicorp/consul-ecs/aws//modules/gateway-task" + version = "" + kind = "mesh-gateway" + + family = "my-gateway" + ecs_cluster_arn = "" + subnets = [""] + retry_join = ["
"] + tls = true + consul_server_ca_cert_arn = "" + gossip_key_secret_arn = "" +} +``` + + + +The following fields are required. Refer to the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task?tab=inputs) for a complete reference. + +| Input Variable | Type | Description | +| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `source` | string | Must be set to the source location of the `gateway-task` module, `hashicorp/consul-ecs/aws//modules/gateway-task`. | +| `version` | string | Must be set to the version of the `gateway-task` module. | +| `kind` | string | The kind of gateway to create. Must be set to `"mesh-gateway"` to create a mesh-gateway. | +| `family` | string | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default. | +| `ecs_cluster_arn` | string | ARN of the ECS cluster to deploy the mesh gateway task to. | +| `subnets` | list | The list of subnet IDs associated with the mesh gateway task. | +| `retry_join` | list | This is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul client agent, which specifies the locations of the Consul servers in the local datacenter. | +| `consul_server_ca_cert_arn` | string | ARN of the Secrets Manager secret that contains the Consul CA certificate. | +| `gossip_key_secret_arn` | string | ARN of the Secrets Manager secret that contains the Consul gossip encryption key. | + + +### Mesh Gateway Ingress + +To route traffic between datacenters, mesh gateways need to be reachable over the WAN. +Providing the `lb_enabled = true` flag will cause the `gateway-task` module to automatically deploy and configure a Network Load Balancer for ingress to the mesh-gateway. +You also need to provide the VPC identifier and at least one public subnet to associate with the load balancer. + + + +```hcl +module "my_mesh_gateway" { + ... + + lb_enabled = true + lb_vpc_id = "" + lb_subnets = [""] +} +``` + + + +Alternatively, you can manually configure ingress to the mesh gateway and provide the `wan_address` and `wan_port` inputs to the +`gateway-task` module. + +~> Mesh gateways route L4 TCP connections and do not terminate mTLS sessions. If you manually configure an Elastic Load Balancer for ingress to a mesh gateway you must use a Network Load Balancer or a Classic Load Balancer. + + + + +```hcl +module "my_mesh_gateway" { + ... + + wan_address = "" + wan_port = +} +``` + + + +The `wan_port` field is optional. If it is not provided, port `8443` is used by default. + +### ACLs + +The following example shows how to configure the `gateway-task` when ACLs are enabled. + + + +```hcl +module "my_mesh_gateway" { + ... + + acls = true + consul_http_addr = "" + consul_https_ca_cert_arn = "" +} +``` + + + +The `consul_http_addr` input is the HTTP `address:port` of the Consul server and is required for the mesh gateway task to log in to Consul via the IAM Auth Method to obtain its client and service tokens. +The `consul_https_ca_cert_arn` input is the ARN of the Secrets Manager secret that contains the certificate for the Consul HTTPS API. + + +### WAN Federation with Mesh Gateways + +The following example shows how to configure the `gateway-task` module to enable [WAN federation via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). + + + +```hcl +module "my_mesh_gateway" { + ... + + consul_datacenter = "" + consul_primary_datacenter = "" + enable_mesh_gateway_wan_federation = true + enable_acl_token_replication = true +} +``` + + + +~> When federating Consul datacenters over the WAN with ACLs enabled, [ACL Token replication](/docs/security/acl/acl-federated-datacenters) must be enabled on all server and client agents in all datacenters. + ### Running Terraform