From dfcd28048a273921b7b2ac772f93d4e31e188470 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Jun 2022 09:04:52 -0700 Subject: [PATCH 01/18] referred to mesh gateway functionality in ECS overview --- website/content/docs/ecs/index.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx index e5c1f2e42..73c1cbf81 100644 --- a/website/content/docs/ecs/index.mdx +++ b/website/content/docs/ecs/index.mdx @@ -8,15 +8,13 @@ description: >- # AWS ECS -Consul service mesh applications can be deployed on [AWS Elastic Container Service](https://aws.amazon.com/ecs/) (ECS) -using either our official [Terraform modules](/docs/ecs/terraform/install) or without Terraform by [manually configuring -the task definition](/docs/ecs/manual/install). +You can deploy Consul service mesh applications to [AWS Elastic Container Service](https://aws.amazon.com/ecs/) (ECS) using either our official [Terraform modules](/docs/ecs/terraform/install) or by [manually configuring the task definition](/docs/ecs/manual/install). ## Service Mesh Using Consul on AWS ECS enables you to add your ECS tasks to the service mesh and take advantage of features such as zero-trust-security, intentions, observability, -traffic policy, and more. +traffic policy, and more. You can also connect service meshes so that services deployed across your infrastructure environments can communicate. ## Architecture From e00c5c7554b8c4e651c0d5a447d374abf5c5ad02 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Jun 2022 12:58:47 -0700 Subject: [PATCH 02/18] updates to ECS Terraform install --- .../content/docs/ecs/terraform/install.mdx | 193 ++++++++++++------ 1 file changed, 136 insertions(+), 57 deletions(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index e810e141a..b48e1736f 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -7,34 +7,41 @@ description: >- # Installation with Terraform -This topic describes how to use the [`mesh-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) Terraform module to launch your application in AWS ECS as part of Consul service mesh. If you do not use Terraform, see the [Manual Installation](/docs/ecs/manual-installation) page to install Consul on ECS without Terraform. +This topic describes how to use HashiCorp’s Terraform modules to launch your application in AWS ECS as part of Consul service mesh. If you do not use Terraform, refer to the [Manual Installation](/docs/ecs/manual-installation) page to install Consul on ECS without Terraform. -This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples. +This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples. ## Overview -This topic describes the following procedure: +The following procedure describes the general workflow: 1. Create Terraform configuration files for the necessary components: - * [ECS task definition](#using-the-mesh-task-module): Use the `mesh-task` module to create an ECS task definition for Consul on ECS - * [ECS service](#ecs-service): Use the `aws_ecs_service` resource to create an ECS service that schedules service mesh tasks to run on ECS + * [ECS task definition](#create-the-task-definition): Use the HashiCorp Terraform modules to create the ECS task definition. + * [ECS service](#ecs-service): Use the `aws_ecs_service` resource to create an ECS service that schedules service mesh tasks to run on ECS. 2. [Run Terraform](#running-terraform) to deploy the resources in AWS +If you want to operate Consul with ACLs enabled (recommended), follow the instructions in the [Secure Configuration](/docs/ecs/terraform/secure-configuration) documentation. ACLs provide network security for production-grade deployments. + ## Prerequisites * You should have some familiarity with using Terraform. Refer to the [Terraform documentation](https://www.terraform.io/docs) to learn about infrastructure as code and how to get started with Terraform. * You should also be familiar with AWS ECS before following these instructions. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details. -## Using the Mesh Task Module +## Create the task definition -To run an application in ECS with Consul service mesh, you must create an ECS task definition, which includes your application container(s) -and additional sidecar containers, such as the Consul agent container and the Envoy sidecar proxy container. +To run an application in ECS with Consul service mesh, you must create an ECS task definition. The task defintion includes your application container(s) and additional sidecar containers, such as the Consul agent container and the Envoy sidecar proxy container. -The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) will automatically include the necessary sidecar containers. +Create a Terraform configuration file and include the `mesh-task` module. The module automatically adds the necessary sidecar containers. -The following example shows a Terraform configuration file that creates a task definition with an application container called `example-client-app` in a file called `mesh-task.tf`: +If you intend to peer the service mesh to multiple Consul datacenters or partitions, you can also include the `gateway-task` module. The `gateway-task` enables connectivity between datacenters across service meshes. + +### Configure the mesh task module + +Create a Terraform configuration file (e.g., `mesh-task.tf`) and specify the `mesh-task` module in the `source` field. The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) will automatically include the necessary sidecar containers. + +In the following example, the a Terraform configuration file called `mesh-task.tf` creates a task definition with an application container called `example-client-app`: @@ -83,7 +90,124 @@ The following fields are required. Refer to the [module reference documentation] | `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. | | `consul_datacenter` | string | The name of your Consul datacenter. | -### Running Terraform +### Configure an ECS service for the mesh task module + +[ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common +ways to start tasks using a task definition. + +To define an ECS service, reference the `mesh-task` module's `task_definition_arn` output value +in your `aws_ecs_service` resource. The following example shows how to include the service in the `mesh-task.tf` file. + + + +```hcl +module "my_task" { + source = "hashicorp/consul-ecs/aws//modules/mesh-task" + ... +} + +resource "aws_ecs_service" "my_task" { + name = "my_task_service" + task_definition = module.my_task.task_definition_arn + launch_type = "FARGATE" + propagate_tags = "TASK_DEFINITION" + ... +} +``` + + + +This is a partial configuration to highlight some important fields. +See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) documentation for a complete reference. + +| Input Variable | Type | Description | +| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | +| `name` | string | The name of the ECS service. This is required by AWS but is not used by Consul service mesh. | +| `task_definition` | string | The task definition used to start tasks. Set this to the task definition ARN returned by the `mesh-task` module. | +| `launch_type` | string | The launch type. Consul on ECS supports the `FARGATE` and `EC2` launch types. | +| `propagate_tags` | string | This must be set to `TASK_DEFINITION` so that tags added by `mesh-task` to the task definition are copied to tasks. | + +After including the ECS service in your Terraform configuration, run `terraform apply` +from your project directory to create the ECS service resource. The ECS service will +soon start your application in a task. The task will automatically register itself +into the Consul service catalog during startup. + +-> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true` +in their [`network_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service#network_configuration) block so that ECS can pull the Docker images. + +### Configure the gateway task module + +Add the `gateway-task` to your Terraform configuration if you want to federate multiple service meshes across Consul datacenters over the WAN. Refer to [WAN Federation via Mesh Gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) to learn more about the federation deployment model. + +You must add and configure a `gateway-task` for each Consul datacenter in your network. The module creates an ECS service and a task definition that includes the following containers: + +* Consul client +* Envoy gateway proxy +* Mesh init + +You will need to provide inputs for the artifacts created by the `gateway-task` module. + +#### Task definition + +The `kind` parameter is the only required input. The value must be set to `mesh-gateway`. The following table describes optional inputs for the task definition. Refer to the [example gateway task configuration](#example-gateway-task-configuration) for a fully-configured task definition. + +| Input variable | Type | Description | +| --- | --- | --- | +| `kind` | string | Specifies the kind of gateway to create. The value must be set to `mesh-gateway`. | +| `lan_address` | string | Specifies the LAN address for the gateway. The address is also used as the service address. Defaults to the node address. | +| `lan_port` | integer | Specifies the LAN port for the gateway. Also used as the service port. Defaults to `8443`. | +| `wan_address` | string | Specifies the WAN address for the gateway. Defaults to the `lan_address`.
If the `assign_public_ip` is set to `true`, the WAN address will be set to the public IP address.
If the `load_balancer_target_group_arn` is specified but no value for `wan_address` is provided, then the WAN address will be set to the load balancer’s DNS name.
To set a static WAN address, specify an explicit value for `wan_address` and `wan_port`. | +| `wan_port` | integer | Specifies the WAN port for the gateway. Defaults to the `lan_port`. | +| `family` | string | Specifies the ECS task definition family. The family is also used as the Consul service name by default. | +| `requires_compatibilities` | list of strings | Specifies one or more launch types required by the task. Defaults to `[“FARGATE”, “EC2”]` | +| `cpu` | integer | Specifies the number of CPUs used by the task. Defaults to `256`. | +| `memory` | integer | Specifies the mount (in MiB) of memory used by the task. Default is `512`. | +| `task_role` | object | Specifies the ECS task role to include in the task definition. If not provided, a role is created. Defaults to `{ "arn": null, "id": null }` | +| `execution_role` | object | Specifies the ECS execution role to include in the task definition. If not provided, a role is created. Defaults to `{ "arn": null, "id": null }` | +| `additional_task_role_policies` | list of strings | Specifies additional policy ARNs to attach to the task role. Default is `[]`. | +| `addition_task_execution_role_policies` | | | +| `log_configuration` | object | Specifies configurations for the task definition log. See [LogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) in the AWS documentation. Default is `{}`.| +| `tags` | object | Defines tags to add to all resources. Default is `{}`.| +| `consul_agent_configuration` | string | Specifies the contents of a configuration file for the Consul agent in HCL format. Default is `""`. | +| `consul_datacenter` | string | Specifies the name of the Consul datacenter that the client belongs to. Default is `dc1`.| +| `consul_service_name` | string | Specifies the name for the service when it registers will Consul. Defaults to the task family name. | +| `consul_service_tags` | list of strings | Defines a list of tags to include in the Consul service registration. Default is `[]`.| +| `consul_service_meta` | object | Defines metadata to attach to the Consul service registration. | +| `consul_image` | string | Specifies the Consul Docker image to use. Default is `public.ecr.aws/hashicorp/consul:1.13.0` | +| `consul_ecs_image` | string | Specifies the Consul on ECS Docker image to use. Default is `public.ecr.aws/hashicorp/consul-ecs:0.6.0` | +| `consul_namespace` | string | Specifies which Consul namespace to register the service. Default is `default`.| +| `consul_partition` | | Specifies which Consul admin partition to register the service. Default is `default`. | +| `envoy_image` | string | Specifies the name of the Envoy Docker image to use. Default is `envoyproxy/envoy-alpine:v1.21.2` | +| `retry_join` | list of strings | Defines a set of arguments to pass to the Consul agent [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) flag. | +| `consul_server_ca_cert_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul server CA certificate for Consul's internal remote procedure calls (RPC). | +| `consul_client_token_secret_arn` | | | +| `gossip_key_secret_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul's gossip encryption key. | +| `acls` | Boolean | Set to `true` to enable Consul's [access control lists (ACLs)](/docs/security/acl/index). Default is `false`.| +| `acl_secret_name_prefix` | | | + +#### ECS service + +The ECS service is created as part of the `gateway-task` module configuration. The service can run one or more instances of the gateway. + +The following table describes the inputs for configuring the ECS service in your Terraform configuration file. All inputs are required. Refer to the [example gateway task configuration](#example-gateway-task-configuration) for a fully-configured task definition. + +| Input variable | Type | Description | +| --- | --- | --- | +| `ecs_cluster_arn` | string | Specifies the ECS cluster where tasks should be launched. | +| `launch_type` | string | Specifies the ECS service launch type. Can be either `fargate` or `ec2`. | +| `desired_count` | integer | Specifies the number instances for the service to create. Defaults to `0`. | +| `subnets` | string | Specifies the subnet IDs where the tasks will launch. | +| `security_group_ids` | string | Specifies the security group IDs to assign to the task ENI. | +| `assign_public_ip` | Boolean | Set to `true` to create a task accessible at a public IP address. Default is `false`.
If set to `true` and `wan_address` is not configured, the WAN address will be set to the public IP of the task. | +| `load_balancer_target_group_arn` | string | Specifies the ARN of an existing load balancer target group. The load balancer target group allows ingress to the gateway task.
No additional load balancer configuration is necessary. Only NLBs and ALBs are supported. The container name and port will be automatically set based on other fields. | + +#### Mesh init + +The `mesh-init` container is a short-lived container that sets up the initial configurations for Consul and Envoy (refer to [Task Startup](/docs/ecs/architecture#task-startup) for additional information). The `gateway-task` module automatically configures the `mesh-init` container based on the inputs specified in the [task definition](#task-definition) and [ECS service](#ecs-service) configuration. + +### Example gateway task configuration + +## Run Terraform You will need to run Terraform to create the task definition. @@ -132,52 +256,7 @@ Terraform should be run in your project directory as follows. Terraform automatically reads all files in the current directory that have a `.tf` file extension. Refer to the [Terraform documentation](https://www.terraform.io/docs) for more information and Terraform best practices. -## ECS Service - -[ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common -ways to start tasks using a task definition. - -To define an ECS service, reference the `mesh-task` module's `task_definition_arn` output value -in your `aws_ecs_service` resource. The following example shows how to include the service in the `mesh-task.tf` file. - - - -```hcl -module "my_task" { - source = "hashicorp/consul-ecs/aws//modules/mesh-task" - ... -} - -resource "aws_ecs_service" "my_task" { - name = "my_task_service" - task_definition = module.my_task.task_definition_arn - launch_type = "FARGATE" - propagate_tags = "TASK_DEFINITION" - ... -} -``` - - - -This is a partial configuration to highlight some important fields. -See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) documentation for a complete reference. - -| Input Variable | Type | Description | -| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | -| `name` | string | The name of the ECS service. This is required by AWS but is not used by Consul service mesh. | -| `task_definition` | string | The task definition used to start tasks. Set this to the task definition ARN returned by the `mesh-task` module. | -| `launch_type` | string | The launch type. Consul on ECS supports the `FARGATE` and `EC2` launch types. | -| `propagate_tags` | string | This must be set to `TASK_DEFINITION` so that tags added by `mesh-task` to the task definition are copied to tasks. | - -After including the ECS service in your Terraform configuration, run `terraform apply` -from your project directory to create the ECS service resource. The ECS service will -soon start your application in a task. The task will automatically register itself -into the Consul service catalog during startup. - --> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true` -in their [`network_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service#network_configuration) block so that ECS can pull the Docker images. - -## Routing +## Configure routes Now that your tasks are registered in the mesh, you're able to use the service mesh to route between them. From 1b1cfa900ede63abc41a885d5393806567143215 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Jun 2022 14:15:29 -0700 Subject: [PATCH 03/18] minor tweaks to TF install --- .../content/docs/ecs/terraform/install.mdx | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index b48e1736f..cbf06aeaf 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -176,7 +176,7 @@ The `kind` parameter is the only required input. The value must be set to `mesh- | `consul_image` | string | Specifies the Consul Docker image to use. Default is `public.ecr.aws/hashicorp/consul:1.13.0` | | `consul_ecs_image` | string | Specifies the Consul on ECS Docker image to use. Default is `public.ecr.aws/hashicorp/consul-ecs:0.6.0` | | `consul_namespace` | string | Specifies which Consul namespace to register the service. Default is `default`.| -| `consul_partition` | | Specifies which Consul admin partition to register the service. Default is `default`. | +| `consul_partition` | string | Specifies which Consul admin partition to register the service. Default is `default`. | | `envoy_image` | string | Specifies the name of the Envoy Docker image to use. Default is `envoyproxy/envoy-alpine:v1.21.2` | | `retry_join` | list of strings | Defines a set of arguments to pass to the Consul agent [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) flag. | | `consul_server_ca_cert_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul server CA certificate for Consul's internal remote procedure calls (RPC). | @@ -318,21 +318,22 @@ module "web" { } ``` -## Bind Address +## Configure the bind address To ensure that your application only receives traffic through the service mesh, -you must change the address that your application is listening on to only the loopback address -(also known as `localhost`, `lo`, and `127.0.0.1`) -so that only the sidecar proxy running in the same task can make requests to it. +you must change the address that your application is listening on to only the loopback address. The loopback address is also called `localhost`, `lo`, and `127.0.0.1`. +Binding to the loopback address allows the sidecar proxy running in the same task to only make requests within the service mesh. -If your application is listening on all interfaces, e.g. `0.0.0.0`, then other +If your application is listening on all interfaces, e.g., `0.0.0.0`, then other applications can call it directly, bypassing its sidecar proxy. Changing the listening address is specific to the language and framework you're using in your application. Regardless of which language/framework you're using, -it's a good practice to make the address configurable via environment variable. +it is a good practice to make the address configurable via environment variable. -For example in Go, you would use: +The following examples demonstrate how to bind the loopback address in golang and Django (Python): + + ```go s := &http.Server{ @@ -342,13 +343,13 @@ s := &http.Server{ log.Fatal(s.ListenAndServe()) ``` -In Django you'd use: - ```bash python manage.py runserver "127.0.0.1:8080" ``` -## Next Steps + + +## Next steps - Follow the [Secure Configuration](/docs/ecs/terraform/secure-configuration) to get production-ready. - Now that your applications are running in the service mesh, read about From 4850a1d4c1c965d0fd0f9c0c6b44530a27fe27a0 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Jun 2022 14:42:51 -0700 Subject: [PATCH 04/18] tweaks to the secure TF install section --- .../ecs/terraform/secure-configuration.mdx | 47 ++++++++++++------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/website/content/docs/ecs/terraform/secure-configuration.mdx b/website/content/docs/ecs/terraform/secure-configuration.mdx index 6a932960e..9489ee14b 100644 --- a/website/content/docs/ecs/terraform/secure-configuration.mdx +++ b/website/content/docs/ecs/terraform/secure-configuration.mdx @@ -7,16 +7,22 @@ description: >- # Secure Configuration -For a production-ready installation of Consul on ECS, you will need to make sure that the cluster is secured. -A secure Consul cluster should include the following: +This topic describes how to enable Consul security features for your production workloads. The following overview describes the process: -1. [TLS Encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. -1. [Gossip Encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. -1. [Access Control (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. +1. Enable the security features on your Consul server cluster per the [Prerequisites](#prerequisites). +1. Deploy the ACL controller. +1. Deploy your services. --> **NOTE:** This page assumes that you have already configured your Consul server with the above features. +## Prerequisites -## Deploy ACL Controller +Implement the following configurations before proceeding: + +1. [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. +1. [Gossip encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. +1. [Access control lists (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. + + +## Deploy the ACL controller Before deploying your service, you will need to deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller) so that it can provision the necessary tokens for tasks on the service mesh. To learn more about the ACL Controller, please see [Automatic ACL Token Provisioning](/docs/ecs/architecture#automatic-acl-token-provisioning). @@ -60,18 +66,17 @@ module "acl_controller" { ``` The `name_prefix` parameter is used to prefix any secrets that the ACL controller will -update in AWS Secrets Manager. +update in AWS Secrets Manager. The `name_prefix` parameter value must be unique for each ECS cluster where you are deploying this controller. --> **NOTE:** Make sure that the `name_prefix` is unique for each ECS cluster where you are -deploying this controller. +## Deploy your services -## Deploy Services +Follow the instructions described in [Create a task definition](/docs/ecs/terraform/install#create-the-task-definition) to create the basic configuration for the task module. Add the following additional configurations to make the configuration production-ready. -Once the ACL controller is up and running, you will be able to deploy services on the mesh using the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). -Start with the basic configuration for the [Task Module](/docs/ecs/terraform/install#task-module) and specify additional settings to make the configuration production-ready. +### Create an AWS Secrets Manager secret -First, you will need to create an AWS Secrets Manager secret for the gossip encryption key that the Consul clients -should use. +The secret stores the gossip encryption key that the Consul clients will use. + + ```hcl resource "aws_secretsmanager_secret" "gossip_key" { @@ -83,8 +88,11 @@ resource "aws_secretsmanager_secret_version" "gossip_key" { secret_string = "" } ``` + -Next, add the following configurations to enable secure deployment. Note that the `acl_secret_name_prefix` +### Enable secure deployment + +Add the following configurations to enable secure deployment. The `acl_secret_name_prefix` should be the same as the `name_prefix` you provide to the ACL controller module. ```hcl @@ -104,5 +112,8 @@ module "my_task" { } ``` -Now you can deploy your services! Follow the rest of the steps in the [Installation instructions](/docs/ecs/terraform/install#task-module) -to deploy and connect your services. +Complete the following steps described in the Installation with Terraform chapter to deploy and connect your services: + +1. [Run Terraform](/docs/ecs/terraform/install#run-terraform) +1. [Configure routes](/docs/ecs/terraform/install#configure-routes) +1. [Configure the bind address](/docs/ecs/terraform/install#configure-the-bind-address) From 1cee20a6442e5a67c3c1eeea181dfb86802aefb1 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Jun 2022 14:57:37 -0700 Subject: [PATCH 05/18] Added note about manually creating mesh gw not being supported --- website/content/docs/ecs/manual/install.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/website/content/docs/ecs/manual/install.mdx b/website/content/docs/ecs/manual/install.mdx index 1046c69c6..7f671bb19 100644 --- a/website/content/docs/ecs/manual/install.mdx +++ b/website/content/docs/ecs/manual/install.mdx @@ -7,7 +7,9 @@ description: >- # Manual Installation -The following instructions describe how to manually create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) without Terraform. Refer to the [Consul ECS Terraform module](/docs/ecs/terraform/install) documentation for an alternative method for installing Consul on ECS. +The following instructions describe how to manually create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) without Terraform. Refer to the [Consul ECS Terraform module](/docs/ecs/terraform/install) documentation for an alternative method for installing Consul on ECS. + +If you intend to peer the service mesh to multiple Consul datacenters or partitions, you must use the Consul ECS Terraform module to install your service mesh on ECS. Manually configuring mesh gateways without using the `gateway-task` Terraform module is not supported. This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples. @@ -17,13 +19,13 @@ You should have some familiarity with AWS ECS. See [What is Amazon Elastic Conta ## Task Definition -You must create a task definition, which includes the following containers: +Create a task definition configured to create the containers: * Your application container * An Envoy sidecar-proxy container * A Consul client container * A `consul-ecs-mesh-init` container for service mesh setup -* Optionally, a `consul-ecs-health-sync` container to sync ECS health checks into Consul +* (Optional) A `consul-ecs-health-sync` container to sync ECS health checks into Consul ## Top-level fields From c5c5ef7845ad6bfd7108cfaebb892c94f601667a Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Jun 2022 15:13:48 -0700 Subject: [PATCH 06/18] tweaks to the secure configuration for manually installing consul ecs --- .../docs/ecs/manual/secure-configuration.mdx | 115 +++++++++++++----- 1 file changed, 84 insertions(+), 31 deletions(-) diff --git a/website/content/docs/ecs/manual/secure-configuration.mdx b/website/content/docs/ecs/manual/secure-configuration.mdx index c96d0afdf..fa96934be 100644 --- a/website/content/docs/ecs/manual/secure-configuration.mdx +++ b/website/content/docs/ecs/manual/secure-configuration.mdx @@ -7,41 +7,36 @@ description: >- # Secure Configuration -For a production-ready installation of Consul on ECS, you will need to make sure that the cluster is secured. -A secure Consul cluster should include the following: - -1. [TLS Encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. -1. [Gossip Encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. -1. [Access Control (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. - --> **NOTE:** In this topic, we assume that you have already configured your Consul server with the security-related features. +This topic describes how to enable Consul security features for your production workloads. ## Prerequisites -* You should already have followed the [installation instructions](/docs/ecs/manual/install) to understand how to define -the necessary components of the task definition for Consul on ECS. -* You should be familiar with [specifying sensitive data](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) on ECS. -* You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the following [Learn Guides](https://learn.hashicorp.com/collections/consul/security) for an introduction and the [ACL system](/docs/security/acl) documentation for more information. +The following features must be configured for your Consul server cluster: + +* [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. +* [Gossip encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. +* [Access control lists (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. + +You should already have followed the [installation instructions](/docs/ecs/manual/install) to understand how to define the necessary components of the task definition for Consul on ECS. + +You should be familiar with [specifying sensitive data](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) on ECS. + +You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the [ACL system documentation](/docs/security/acl) and [Day 1: Security tutorials](https://learn.hashicorp.com/collections/consul/security) for an introduction and additional information. ## ACL Tokens +Tokens are artifacts within the ACL system that authenticate users, services, and Consul agents. Tokens are linked to policies that specify the resources the token bearer has access to when making requests in the network. + You must create two types of ACL tokens for Consul on ECS: * **Client tokens:** used by the `consul-client` containers to join the Consul cluster * **Service tokens:** used by sidecar containers for service registration and health syncing -The following sections describe the ACL polices which must be associated with these token types. +This section describes how to manually create ACL tokens. You can install the ACL controller, however, to ease the burden of creating tokens. The ACL controller can automatically create ACL tokens for Consul on ECS. Refer to the [ACL Controller](/docs/manual/acl-controller) documentation for installation details. --> **NOTE:** This section describes how operators would create ACL tokens by hand. To ease operator -burden, the ACL Controller can automatically create ACL tokens for Consul on ECS. Refer to the -[ACL Controller](/docs/manual/acl-controller) page for installation details. +### Define policies -### Create Consul client token - -You must create a token for the Consul client. This is a shared token used by the `consul-client` -containers to join the Consul cluster. - -The following is the ACL policy needed for the Consul client token: +Confiture the following ACL policy for the Consul client token: ```hcl node_prefix "" { @@ -52,22 +47,80 @@ service_prefix "" { } ``` -This policy allows `node:write` for any node name, which is necessary because the Consul node -names on ECS are not known until runtime. +The policy allows `node:write` for any node name, which is necessary because the Consul node names on ECS are not known until runtime. + +You can add the policy in Consul using the [`consul acl policy create`](/commands/acl/policy/create) command or the [`[PUT] /v1/acl/policy`](/api-docs/acl/policies#create-a-policy) API endpoint. + +If you intend to create a gateway for connecting multiple Consul datacenters, you will need additional policies to specify the permission scope. + +#### Mesh gateway policy + +Mesh gateways must run in the default namespace. + +```hcl +namespace "default" { // If namespaces enabled + service "" { + policy = "write" + } +} +namespace_prefix "" { // If namespaces enabled + service_prefix "" { + policy = "read" + } + node_prefix "" { + policy = "read" + } +} +agent_prefix "" { + policy = "read" +} +``` +#### Terminating gateway policy + +```hcl +partition "" { // If partitions enabled + namespace "" { // If namespaces enabled + service "" { + policy = "write" + } + node_prefix "" { + policy = "read" + } + } +} +``` + +#### Ingress gateway policy + +```hcl +partition "" { // If partitions enabled + namespace "" { // If namespaces enabled + service "" { + policy = "write" + } + node_prefix "" { + policy = "read" + } + service_prefix "" { + policy = "read" + } + } +} +``` + ### Create service tokens -Service tokens should be associated with a [service identity](/docs/security/acl#service-identities). -The service identity includes `service:write` permissions for the service and sidecar proxy. +Create the Consul client token and the service tokens after adding the necessary policies. Service tokens should be associated with a service identity. The service identity includes `service:write` permissions for the service and sidecar proxy. -The following example shows how to use the Consul CLI to create a service token for a service named `example-client-app`: +You can create tokens using the [`consul acl token create`](/commands/acl/token/create) command or the [`[PUT] /v1/acl/token`](/api-docs/acl/tokens#create-a-token) API endpoint. +The following example shows how to use the Consul CLI to create a service token for a service named example-client-app: -```shell -consul acl token create -service-identity=example-client-app ... +```shell-session +$ consul acl token create -service-identity=example-client-app ... ``` +You will need to create one service token for each registered Consul service in ECS, including when new services are added to the service mesh. --> **NOTE**: You will need to create one service token for each registered Consul service in ECS, -including when new services are added to the service mesh. ## Secret storage From 7249a0326e8f476cf9ba28fe8ee96999cbc4bdf9 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 17 Jun 2022 15:17:48 -0700 Subject: [PATCH 07/18] tweaks to the enterprise section for ecs mesh gateways --- website/content/docs/ecs/enterprise.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/content/docs/ecs/enterprise.mdx b/website/content/docs/ecs/enterprise.mdx index 6ee42d5be..7a6a53545 100644 --- a/website/content/docs/ecs/enterprise.mdx +++ b/website/content/docs/ecs/enterprise.mdx @@ -7,20 +7,19 @@ description: >- # Consul Enterprise -Consul on ECS supports running Consul Enterprise by specifying the Consul Enterprise -Docker image in the Terraform module parameters. +You can run Consul Enterprise on ECS by specifying the Consul Enterprise Docker image in the Terraform module parameters. -## How To Use Consul Enterprise +## Specify the Consul image -When instantiating the [`mesh-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) module, -set the parameter `consul_image` to a Consul Enterprise image, e.g. `hashicorp/consul-enterprise:1.10.0-ent`: +When instantiating the [`mesh-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) or [`gateway-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task) module, +set the parameter `consul_image` to a Consul Enterprise image. The following example instructs the `mesh-task` module to import Consul Enterprise version 1.12.0: ```hcl module "my_task" { source = "hashicorp/consul-ecs/aws//modules/mesh-task" version = "" - consul_image = "hashicorp/consul-enterprise:-ent" + consul_image = "hashicorp/consul-enterprise:1.12.0-ent" ... } ``` @@ -62,11 +61,12 @@ If client support is required for any of the features, then you must use a Consu ### Admin Partitions and Namespaces -Consul on ECS supports [admin partitions](/docs/enterprise/admin-partitions) and [namespaces](/docs/enterprise/namespaces) when Consul Enterprise servers and clients are used. -These features have the following requirements: +Consul on ECS supports [admin partitions](/docs/enterprise/admin-partitions) and [namespaces](/docs/enterprise/namespaces) when Consul Enterprise servers and clients are used. These features have the following requirements: + * ACLs must be enabled. * ACL controller must run in the ECS cluster. * `mesh-tasks` must use a Consul Enterprise client image. +* `gateway-task`s must use a Consul Enterprise client image. The ACL controller automatically manages ACL policies and token provisioning for clients and services on the service mesh. It also creates admin partitions and namespaces if they do not already exist. From 569cf68daa98cd5b9c4e3271c0832b9e720e4182 Mon Sep 17 00:00:00 2001 From: Chris Thain Date: Mon, 20 Jun 2022 09:07:44 -0700 Subject: [PATCH 08/18] 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 From f6d0220af8848b9ca5fa9893efd8188272d54213 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 20 Jun 2022 12:38:21 -0700 Subject: [PATCH 09/18] incorporated examples from @cthain --- .../content/docs/ecs/terraform/install.mdx | 309 ++++++++---------- 1 file changed, 139 insertions(+), 170 deletions(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index 7118ae12a..3a072c8cc 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -24,10 +24,11 @@ The following procedure describes the general workflow: If you want to operate Consul with ACLs enabled (recommended), follow the instructions in the [Secure Configuration](/docs/ecs/terraform/secure-configuration) documentation. ACLs provide network security for production-grade deployments. -## Prerequisites +## Requirements * You should have some familiarity with using Terraform. Refer to the [Terraform documentation](https://www.terraform.io/docs) to learn about infrastructure as code and how to get started with Terraform. * You should also be familiar with AWS ECS before following these instructions. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details. +* If you intend to [use the `gateway-task` module to deploy mesh gateways](#configure-the-gateway-task-module), all Consul server and client agents in all datacenters must have TLS and gossip encryption enabled (refer to [Encryption](/docs/security/encryption) for instructions). ## Create the task definition @@ -88,138 +89,6 @@ The following fields are required. Refer to the [module reference documentation] | `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 | 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 = ["
"] - 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. - - ### Configure an ECS service for the mesh task module [ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common @@ -267,53 +136,55 @@ in their [`network_configuration`](https://registry.terraform.io/providers/hashi ### Configure the gateway task module -Add the `gateway-task` to your Terraform configuration if you want to federate multiple service meshes across Consul datacenters over the WAN. Refer to [WAN Federation via Mesh Gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) to learn more about the federation deployment model. +Add the `gateway-task` to your Terraform configuration if you want to deploy a mesh gateway. Mesh gateways enable service to service communication across the WAN, as well as federate service mesh traffic across Consul admin partitions and Consul datacenters over the WAN. Refer to the following documentation to learn more about mesh gateways: -You must add and configure a `gateway-task` for each Consul datacenter in your network. The module creates an ECS service and a task definition that includes the following containers: +* [WAN Federation via Mesh Gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) +* [Service-to-service Traffic Across Datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters). + +You must add and configure a `gateway-task` for each Consul datacenter in your network. You must also enable TLS and gossip encryption on all server and client agents in all data centers per the [Requirements](#requirements). 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 module creates an ECS service and a task definition that includes the following containers: * Consul client * Envoy gateway proxy * Mesh init -You will need to provide inputs for the artifacts created by the `gateway-task` module. +You will need to provide inputs for the artifacts created by the `gateway-task` module. The following example defines a mesh gateway task called `my-gateway` in a file called `mesh-gateway.tf`: -#### Task definition + -The `kind` parameter is the only required input. The value must be set to `mesh-gateway`. The following table describes optional inputs for the task definition. Refer to the [example gateway task configuration](#example-gateway-task-configuration) for a fully-configured task definition. +```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 = ["
"] + 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 | -| --- | --- | --- | -| `kind` | string | Specifies the kind of gateway to create. The value must be set to `mesh-gateway`. | -| `lan_address` | string | Specifies the LAN address for the gateway. The address is also used as the service address. Defaults to the node address. | -| `lan_port` | integer | Specifies the LAN port for the gateway. Also used as the service port. Defaults to `8443`. | -| `wan_address` | string | Specifies the WAN address for the gateway. Defaults to the `lan_address`.
If the `assign_public_ip` is set to `true`, the WAN address will be set to the public IP address.
If the `load_balancer_target_group_arn` is specified but no value for `wan_address` is provided, then the WAN address will be set to the load balancer’s DNS name.
To set a static WAN address, specify an explicit value for `wan_address` and `wan_port`. | -| `wan_port` | integer | Specifies the WAN port for the gateway. Defaults to the `lan_port`. | -| `family` | string | Specifies the ECS task definition family. The family is also used as the Consul service name by default. | -| `requires_compatibilities` | list of strings | Specifies one or more launch types required by the task. Defaults to `[“FARGATE”, “EC2”]` | -| `cpu` | integer | Specifies the number of CPUs used by the task. Defaults to `256`. | -| `memory` | integer | Specifies the mount (in MiB) of memory used by the task. Default is `512`. | -| `task_role` | object | Specifies the ECS task role to include in the task definition. If not provided, a role is created. Defaults to `{ "arn": null, "id": null }` | -| `execution_role` | object | Specifies the ECS execution role to include in the task definition. If not provided, a role is created. Defaults to `{ "arn": null, "id": null }` | -| `additional_task_role_policies` | list of strings | Specifies additional policy ARNs to attach to the task role. Default is `[]`. | -| `addition_task_execution_role_policies` | | | -| `log_configuration` | object | Specifies configurations for the task definition log. See [LogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) in the AWS documentation. Default is `{}`.| -| `tags` | object | Defines tags to add to all resources. Default is `{}`.| -| `consul_agent_configuration` | string | Specifies the contents of a configuration file for the Consul agent in HCL format. Default is `""`. | -| `consul_datacenter` | string | Specifies the name of the Consul datacenter that the client belongs to. Default is `dc1`.| -| `consul_service_name` | string | Specifies the name for the service when it registers will Consul. Defaults to the task family name. | -| `consul_service_tags` | list of strings | Defines a list of tags to include in the Consul service registration. Default is `[]`.| -| `consul_service_meta` | object | Defines metadata to attach to the Consul service registration. | -| `consul_image` | string | Specifies the Consul Docker image to use. Default is `public.ecr.aws/hashicorp/consul:1.13.0` | -| `consul_ecs_image` | string | Specifies the Consul on ECS Docker image to use. Default is `public.ecr.aws/hashicorp/consul-ecs:0.6.0` | -| `consul_namespace` | string | Specifies which Consul namespace to register the service. Default is `default`.| -| `consul_partition` | string | Specifies which Consul admin partition to register the service. Default is `default`. | -| `envoy_image` | string | Specifies the name of the Envoy Docker image to use. Default is `envoyproxy/envoy-alpine:v1.21.2` | -| `retry_join` | list of strings | Defines a set of arguments to pass to the Consul agent [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) flag. | -| `consul_server_ca_cert_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul server CA certificate for Consul's internal remote procedure calls (RPC). | -| `consul_client_token_secret_arn` | | | +| --- | --- | --- | +| `source` | string | Specifies the source location of the `gateway-task` module. Must be set to `hashicorp/consul-ecs/aws//modules/gateway-task`. | +| `version` | string | Specifies the version of the `gateway-task` module. | +| `kind` | string | Declares the kind of gateway to create. Must be set to `mesh-gateway` to create a mesh-gateway. | +| `family` | string | Specifies 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 | Specifies the ARN of the ECS cluster where the mesh gateway task should be launched. | +| `subnets` | list of strings | Specifies the subnet IDs where the task will be launched. | +| `retry_join` | list of strings | Defines a set of arguments to pass to the Consul agent [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) flag. The arguments specify locations of the Consul servers in the local datacenter that Consul client agents can connect to. | +| `consul_server_ca_cert_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul server CA certificate | | `gossip_key_secret_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul's gossip encryption key. | -| `acls` | Boolean | Set to `true` to enable Consul's [access control lists (ACLs)](/docs/security/acl/index). Default is `false`.| -| `acl_secret_name_prefix` | | | + +Refer to the [gateway task configuration examples](#gateway-task-configuration-examples) for additional example configurations. #### ECS service @@ -335,7 +206,105 @@ The following table describes the inputs for configuring the ECS service in your The `mesh-init` container is a short-lived container that sets up the initial configurations for Consul and Envoy (refer to [Task Startup](/docs/ecs/architecture#task-startup) for additional information). The `gateway-task` module automatically configures the `mesh-init` container based on the inputs specified in the [task definition](#task-definition) and [ECS service](#ecs-service) configuration. -### Example gateway task configuration +#### Gateway task configuration examples + +The following examples illustrate how to configure the `gateway-task` for different use cases. + +##### Ingress + +Mesh gateways need to be reachable over the WAN to route traffic between datacenters. Configure the following options in the `gateway-task` to enable ingress through the mesh gateway. + +| Option | Type | Description | +| --- | --- | --- | +| `lb_enabled` | Boolean | Set to `true` to automatically deploy and configure a network load balancer for ingress to the mesh gateway. | +| `lb_vpc_id` | string | Specifies the VPC in which to launch the load balancer. | +| `lb_subnets` | list of strings | Specifies one or more public subnets 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. The `wan_port` field is optional. Port `8443` is used by default. + + + +```hcl +module "my_mesh_gateway" { + ... + + wan_address = "" + wan_port = +} +``` + + + +Mesh gateways route L4 TCP connections and do not terminate mTLS sessions. If you manually configure [AWS Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) for ingress to a mesh gateway, you must use an AWS [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) or a [Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html). + + +#### ACLs + +Configure the following options in the `gateway-task` when ACLs are enabled. + +| Option | Type | Description | +| --- | --- | --- | +| `acl` | Boolean | Set to `true` if ACLs are enabled. | +| `consul_http_addr` | string | Specifies the HTTP `address:port` of the Consul server. Required for the mesh gateway task to log into Consul via the IAM Auth Method to obtain its client and service tokens. | +| `consul_https_ca_cert_arn` | string | Specifies ARN of the Secrets Manager secret that contains the certificate for the Consul HTTPS API. | + + + +```hcl +module "my_mesh_gateway" { + ... + + acls = true + consul_http_addr = "" + consul_https_ca_cert_arn = "" +} +``` + + + +#### WAN federation + +Configure the following options in the `gateway-task` to enable [WAN federation via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). + +| Option | Type | Description | +| --- | --- | --- | +| `consul_datacenter` | string | Specifies the name of the local Consul datacenter. | +| `consul_primary_datacenter` | string | Specifies the name of the primary Consul datacenter. | +| `enable_mesh_gateway_wan_federation` | Boolean | Set to `true` to enable WAN federation. | +| `enable_acl_token_replication` | Boolean | Set to `true` to enable ACL token replication and allow the creation of local tokens secondary datacenters. | + +The following example shows how to configure the `gateway-task` module. + + + +```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. ## Run Terraform From c779d224e23fdcdfa9f1cc58d289e9295af7ad2b Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Mon, 20 Jun 2022 13:53:48 -0700 Subject: [PATCH 10/18] Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- website/content/docs/ecs/enterprise.mdx | 10 +++---- website/content/docs/ecs/manual/install.mdx | 12 ++++----- .../docs/ecs/manual/secure-configuration.mdx | 26 +++++++++---------- .../ecs/terraform/secure-configuration.mdx | 4 +-- 4 files changed, 26 insertions(+), 26 deletions(-) diff --git a/website/content/docs/ecs/enterprise.mdx b/website/content/docs/ecs/enterprise.mdx index 7a6a53545..eaedba7e6 100644 --- a/website/content/docs/ecs/enterprise.mdx +++ b/website/content/docs/ecs/enterprise.mdx @@ -11,7 +11,7 @@ You can run Consul Enterprise on ECS by specifying the Consul Enterprise Docker ## Specify the Consul image -When instantiating the [`mesh-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) or [`gateway-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task) module, +When you set up an instance of the [`mesh-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) or [`gateway-task`](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task) module, set the parameter `consul_image` to a Consul Enterprise image. The following example instructs the `mesh-task` module to import Consul Enterprise version 1.12.0: ```hcl @@ -63,10 +63,10 @@ If client support is required for any of the features, then you must use a Consu Consul on ECS supports [admin partitions](/docs/enterprise/admin-partitions) and [namespaces](/docs/enterprise/namespaces) when Consul Enterprise servers and clients are used. These features have the following requirements: -* ACLs must be enabled. -* ACL controller must run in the ECS cluster. -* `mesh-tasks` must use a Consul Enterprise client image. -* `gateway-task`s must use a Consul Enterprise client image. +- ACLs must be enabled. +- ACL controller must run in the ECS cluster. +- `mesh-task` must use a Consul Enterprise client image. +- `gateway-task` must use a Consul Enterprise client image. The ACL controller automatically manages ACL policies and token provisioning for clients and services on the service mesh. It also creates admin partitions and namespaces if they do not already exist. diff --git a/website/content/docs/ecs/manual/install.mdx b/website/content/docs/ecs/manual/install.mdx index 7f671bb19..7e20b3ea0 100644 --- a/website/content/docs/ecs/manual/install.mdx +++ b/website/content/docs/ecs/manual/install.mdx @@ -7,7 +7,7 @@ description: >- # Manual Installation -The following instructions describe how to manually create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) without Terraform. Refer to the [Consul ECS Terraform module](/docs/ecs/terraform/install) documentation for an alternative method for installing Consul on ECS. +The following instructions describe how to use the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) to manually create the ECS task definition without Terraform. If you prefer to use Terraform, refer to [Consul ECS Terraform module](/docs/ecs/terraform/install). If you intend to peer the service mesh to multiple Consul datacenters or partitions, you must use the Consul ECS Terraform module to install your service mesh on ECS. Manually configuring mesh gateways without using the `gateway-task` Terraform module is not supported. @@ -19,12 +19,12 @@ You should have some familiarity with AWS ECS. See [What is Amazon Elastic Conta ## Task Definition -Create a task definition configured to create the containers: +Configure a task definition that creates the containers: -* Your application container -* An Envoy sidecar-proxy container -* A Consul client container -* A `consul-ecs-mesh-init` container for service mesh setup +- Your application container +- An Envoy sidecar-proxy container +- A Consul client container +- A `consul-ecs-mesh-init` container for service mesh setup * (Optional) A `consul-ecs-health-sync` container to sync ECS health checks into Consul ## Top-level fields diff --git a/website/content/docs/ecs/manual/secure-configuration.mdx b/website/content/docs/ecs/manual/secure-configuration.mdx index fa96934be..02a4bd4a8 100644 --- a/website/content/docs/ecs/manual/secure-configuration.mdx +++ b/website/content/docs/ecs/manual/secure-configuration.mdx @@ -13,11 +13,11 @@ This topic describes how to enable Consul security features for your production The following features must be configured for your Consul server cluster: -* [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. -* [Gossip encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. -* [Access control lists (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. +- [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. +- [Gossip encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. +- [Access control lists (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. -You should already have followed the [installation instructions](/docs/ecs/manual/install) to understand how to define the necessary components of the task definition for Consul on ECS. +You should already have followed the [manual installation instructions](/docs/ecs/manual/install) to define the necessary components of the task definition for Consul on ECS. You should be familiar with [specifying sensitive data](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) on ECS. @@ -36,7 +36,7 @@ This section describes how to manually create ACL tokens. You can install the AC ### Define policies -Confiture the following ACL policy for the Consul client token: +Configure the following ACL policy for the Consul client token: ```hcl node_prefix "" { @@ -58,12 +58,12 @@ If you intend to create a gateway for connecting multiple Consul datacenters, yo Mesh gateways must run in the default namespace. ```hcl -namespace "default" { // If namespaces enabled +namespace "default" { ## If namespaces enabled service "" { policy = "write" } } -namespace_prefix "" { // If namespaces enabled +namespace_prefix "" { ## If namespaces enabled service_prefix "" { policy = "read" } @@ -78,8 +78,8 @@ agent_prefix "" { #### Terminating gateway policy ```hcl -partition "" { // If partitions enabled - namespace "" { // If namespaces enabled +partition "" { ## If partitions enabled + namespace "" { ## If namespaces enabled service "" { policy = "write" } @@ -93,8 +93,8 @@ partition "" { // If partitions enabled #### Ingress gateway policy ```hcl -partition "" { // If partitions enabled - namespace "" { // If namespaces enabled +partition "" { ## If partitions enabled + namespace "" { ## If namespaces enabled service "" { policy = "write" } @@ -114,12 +114,12 @@ partition "" { // If partitions enabled Create the Consul client token and the service tokens after adding the necessary policies. Service tokens should be associated with a service identity. The service identity includes `service:write` permissions for the service and sidecar proxy. You can create tokens using the [`consul acl token create`](/commands/acl/token/create) command or the [`[PUT] /v1/acl/token`](/api-docs/acl/tokens#create-a-token) API endpoint. -The following example shows how to use the Consul CLI to create a service token for a service named example-client-app: +The following example shows how to use the Consul CLI to create a service token for a service named `example-client-app`: ```shell-session $ consul acl token create -service-identity=example-client-app ... ``` -You will need to create one service token for each registered Consul service in ECS, including when new services are added to the service mesh. +You need to create one service token for each registered Consul service in ECS. When you add new services to the service mesh, you must create new tokens for each service. ## Secret storage diff --git a/website/content/docs/ecs/terraform/secure-configuration.mdx b/website/content/docs/ecs/terraform/secure-configuration.mdx index 9489ee14b..521141da8 100644 --- a/website/content/docs/ecs/terraform/secure-configuration.mdx +++ b/website/content/docs/ecs/terraform/secure-configuration.mdx @@ -66,7 +66,7 @@ module "acl_controller" { ``` The `name_prefix` parameter is used to prefix any secrets that the ACL controller will -update in AWS Secrets Manager. The `name_prefix` parameter value must be unique for each ECS cluster where you are deploying this controller. +update in AWS Secrets Manager. The `name_prefix` parameter value must be unique for each ECS cluster where you deploy this controller. ## Deploy your services @@ -74,7 +74,7 @@ Follow the instructions described in [Create a task definition](/docs/ecs/terraf ### Create an AWS Secrets Manager secret -The secret stores the gossip encryption key that the Consul clients will use. +The secret stores the gossip encryption key that the Consul clients use. From 1bd3909a716e4a867b70a259892577a7c4661a4d Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Mon, 20 Jun 2022 14:11:05 -0700 Subject: [PATCH 11/18] Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../content/docs/ecs/terraform/install.mdx | 43 ++++++++++--------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index 3a072c8cc..10950eff9 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -9,7 +9,7 @@ description: >- This topic describes how to use HashiCorp’s Terraform modules to launch your application in AWS ECS as part of Consul service mesh. If you do not use Terraform, refer to the [Manual Installation](/docs/ecs/manual-installation) page to install Consul on ECS without Terraform. -This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples. +This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the guides in the [Getting Started](/docs/ecs#getting-started) section for complete and runnable examples. ## Overview @@ -17,8 +17,8 @@ The following procedure describes the general workflow: 1. Create Terraform configuration files for the necessary components: - * [ECS task definition](#create-the-task-definition): Use the HashiCorp Terraform modules to create the ECS task definition. - * [ECS service](#ecs-service): Use the `aws_ecs_service` resource to create an ECS service that schedules service mesh tasks to run on ECS. + - [ECS task definition](#create-the-task-definition): Use the HashiCorp Terraform modules to create the ECS task definition. + - [ECS service](#ecs-service): Use the `aws_ecs_service` resource to create an ECS service that schedules service mesh tasks to run on ECS. 2. [Run Terraform](#running-terraform) to deploy the resources in AWS @@ -32,17 +32,17 @@ If you want to operate Consul with ACLs enabled (recommended), follow the instru ## Create the task definition -To run an application in ECS with Consul service mesh, you must create an ECS task definition. The task defintion includes your application container(s) and additional sidecar containers, such as the Consul agent container and the Envoy sidecar proxy container. +To run an application in ECS with Consul service mesh, you must create an ECS task definition. The task definition includes your application containers and additional sidecar containers, such as the Consul agent container and the Envoy sidecar proxy container. Create a Terraform configuration file and include the `mesh-task` module. The module automatically adds the necessary sidecar containers. -If you intend to peer the service mesh to multiple Consul datacenters or partitions, you can also include the `gateway-task` module. The `gateway-task` enables connectivity between datacenters across service meshes. +If you intend to peer the service mesh to multiple Consul datacenters or partitions, you can also include the `gateway-task` module. The module enables connectivity between datacenters across service meshes. ### Configure the mesh task module -Create a Terraform configuration file (e.g., `mesh-task.tf`) and specify the `mesh-task` module in the `source` field. The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) will automatically include the necessary sidecar containers. +Create a Terraform configuration file and specify the `mesh-task` module in the `source` field. The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) automatically includes the necessary sidecar containers. -In the following example, the a Terraform configuration file called `mesh-task.tf` creates a task definition with an application container called `example-client-app`: +In the following example, the Terraform configuration file called `mesh-task.tf` creates a task definition with an application container called `example-client-app`: @@ -116,19 +116,18 @@ resource "aws_ecs_service" "my_task" { -This is a partial configuration to highlight some important fields. -See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) documentation for a complete reference. +The example shows a partially configured ECS service to highlight significant fields. Refer to [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) for a complete configuration reference. | Input Variable | Type | Description | | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | -| `name` | string | The name of the ECS service. This is required by AWS but is not used by Consul service mesh. | -| `task_definition` | string | The task definition used to start tasks. Set this to the task definition ARN returned by the `mesh-task` module. | +| `name` | string | The name of the ECS service. This name is required by AWS but is not used by Consul service mesh. | +| `task_definition` | string | The task definition used to start tasks. Set this option to the task definition ARN returned by the `mesh-task` module. | | `launch_type` | string | The launch type. Consul on ECS supports the `FARGATE` and `EC2` launch types. | -| `propagate_tags` | string | This must be set to `TASK_DEFINITION` so that tags added by `mesh-task` to the task definition are copied to tasks. | +| `propagate_tags` | string | This option must be set to `TASK_DEFINITION` so that tags added by `mesh-task` to the task definition are copied to tasks. | After including the ECS service in your Terraform configuration, run `terraform apply` -from your project directory to create the ECS service resource. The ECS service will -soon start your application in a task. The task will automatically register itself +from your project directory to create the ECS service resource. The ECS service +then starts your application in a task. The task automatically registers itself into the Consul service catalog during startup. -> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true` @@ -145,9 +144,9 @@ You must add and configure a `gateway-task` for each Consul datacenter in your n The module creates an ECS service and a task definition that includes the following containers: -* Consul client -* Envoy gateway proxy -* Mesh init +- Consul client +- Envoy gateway proxy +- Mesh init You will need to provide inputs for the artifacts created by the `gateway-task` module. The following example defines a mesh gateway task called `my-gateway` in a file called `mesh-gateway.tf`: @@ -197,14 +196,16 @@ The following table describes the inputs for configuring the ECS service in your | `ecs_cluster_arn` | string | Specifies the ECS cluster where tasks should be launched. | | `launch_type` | string | Specifies the ECS service launch type. Can be either `fargate` or `ec2`. | | `desired_count` | integer | Specifies the number instances for the service to create. Defaults to `0`. | -| `subnets` | string | Specifies the subnet IDs where the tasks will launch. | +| `subnets` | string | Specifies the subnet IDs where the tasks launch. | | `security_group_ids` | string | Specifies the security group IDs to assign to the task ENI. | | `assign_public_ip` | Boolean | Set to `true` to create a task accessible at a public IP address. Default is `false`.
If set to `true` and `wan_address` is not configured, the WAN address will be set to the public IP of the task. | -| `load_balancer_target_group_arn` | string | Specifies the ARN of an existing load balancer target group. The load balancer target group allows ingress to the gateway task.
No additional load balancer configuration is necessary. Only NLBs and ALBs are supported. The container name and port will be automatically set based on other fields. | +| `load_balancer_target_group_arn` | string | Specifies the ARN of an existing load balancer target group. The load balancer target group allows ingress to the gateway task.
No additional load balancer configuration is necessary. Only NLBs and ALBs are supported. The container name and port are set automatically based on other fields. | #### Mesh init -The `mesh-init` container is a short-lived container that sets up the initial configurations for Consul and Envoy (refer to [Task Startup](/docs/ecs/architecture#task-startup) for additional information). The `gateway-task` module automatically configures the `mesh-init` container based on the inputs specified in the [task definition](#task-definition) and [ECS service](#ecs-service) configuration. +The `mesh-init` container is a short-lived container that sets up the initial configurations for Consul and Envoy. The `gateway-task` module automatically configures the `mesh-init` container based on the inputs specified in the [task definition](#task-definition) and [ECS service](#ecs-service) configuration. + +For additional information, refer to [Task Startup](/docs/ecs/architecture#task-startup) for additional information. #### Gateway task configuration examples @@ -217,7 +218,7 @@ Mesh gateways need to be reachable over the WAN to route traffic between datacen | Option | Type | Description | | --- | --- | --- | | `lb_enabled` | Boolean | Set to `true` to automatically deploy and configure a network load balancer for ingress to the mesh gateway. | -| `lb_vpc_id` | string | Specifies the VPC in which to launch the load balancer. | +| `lb_vpc_id` | string | Specifies the VPC to launch the load balancer in. | | `lb_subnets` | list of strings | Specifies one or more public subnets to associate with the load balancer. | From cfd9e2e41da895a22f2ca75899b50ed990b6f3dc Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 20 Jun 2022 14:14:18 -0700 Subject: [PATCH 12/18] fixed links to TF install examples --- website/content/docs/ecs/terraform/install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index 10950eff9..d52aeeaf4 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -189,7 +189,7 @@ Refer to the [gateway task configuration examples](#gateway-task-configuration-e The ECS service is created as part of the `gateway-task` module configuration. The service can run one or more instances of the gateway. -The following table describes the inputs for configuring the ECS service in your Terraform configuration file. All inputs are required. Refer to the [example gateway task configuration](#example-gateway-task-configuration) for a fully-configured task definition. +The following table describes the inputs for configuring the ECS service in your Terraform configuration file. All inputs are required. Refer to the [gateway task configuration examples](#gateway-task-configuration-examples) for a fully-configured task definition. | Input variable | Type | Description | | --- | --- | --- | From c0a0227c964256d41008c9cee0b1535307f29a1b Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Tue, 21 Jun 2022 08:08:37 -0700 Subject: [PATCH 13/18] Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Chris Thain <32781396+cthain@users.noreply.github.com> --- .../content/docs/ecs/manual/secure-configuration.mdx | 4 ++-- website/content/docs/ecs/terraform/install.mdx | 12 +++++++----- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/website/content/docs/ecs/manual/secure-configuration.mdx b/website/content/docs/ecs/manual/secure-configuration.mdx index 02a4bd4a8..f9a0ac934 100644 --- a/website/content/docs/ecs/manual/secure-configuration.mdx +++ b/website/content/docs/ecs/manual/secure-configuration.mdx @@ -32,7 +32,7 @@ You must create two types of ACL tokens for Consul on ECS: * **Client tokens:** used by the `consul-client` containers to join the Consul cluster * **Service tokens:** used by sidecar containers for service registration and health syncing -This section describes how to manually create ACL tokens. You can install the ACL controller, however, to ease the burden of creating tokens. The ACL controller can automatically create ACL tokens for Consul on ECS. Refer to the [ACL Controller](/docs/manual/acl-controller) documentation for installation details. +This section describes how to manually create ACL tokens. Alternatively, you can install the ACL controller to ease the burden of creating tokens. The ACL controller can automatically create ACL tokens for Consul on ECS. For additional details, refer to [ACL Controller](/docs/manual/acl-controller). ### Define policies @@ -80,7 +80,7 @@ agent_prefix "" { ```hcl partition "" { ## If partitions enabled namespace "" { ## If namespaces enabled - service "" { + service "" { policy = "write" } node_prefix "" { diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index d52aeeaf4..99099d21b 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -162,6 +162,7 @@ module "my_mesh_gateway" { ecs_cluster_arn = "" subnets = [""] retry_join = ["
"] + tls = true consul_server_ca_cert_arn = "" gossip_key_secret_arn = "" } @@ -180,6 +181,7 @@ The following fields are required. Refer to the [module reference documentation] | `ecs_cluster_arn` | string | Specifies the ARN of the ECS cluster where the mesh gateway task should be launched. | | `subnets` | list of strings | Specifies the subnet IDs where the task will be launched. | | `retry_join` | list of strings | Defines a set of arguments to pass to the Consul agent [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) flag. The arguments specify locations of the Consul servers in the local datacenter that Consul client agents can connect to. | +| `tls` | boolean | Set to `true` to enable TLS. | | `consul_server_ca_cert_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul server CA certificate | | `gossip_key_secret_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul's gossip encryption key. | @@ -215,7 +217,7 @@ The following examples illustrate how to configure the `gateway-task` for differ Mesh gateways need to be reachable over the WAN to route traffic between datacenters. Configure the following options in the `gateway-task` to enable ingress through the mesh gateway. -| Option | Type | Description | +| Input variable | Type | Description | | --- | --- | --- | | `lb_enabled` | Boolean | Set to `true` to automatically deploy and configure a network load balancer for ingress to the mesh gateway. | | `lb_vpc_id` | string | Specifies the VPC to launch the load balancer in. | @@ -421,15 +423,15 @@ module "web" { ## Configure the bind address To ensure that your application only receives traffic through the service mesh, -you must change the address that your application is listening on to only the loopback address. The loopback address is also called `localhost`, `lo`, and `127.0.0.1`. +you must change the address that your application listens on to the loopback address. The loopback address is also called `localhost`, `lo`, and `127.0.0.1`. Binding to the loopback address allows the sidecar proxy running in the same task to only make requests within the service mesh. -If your application is listening on all interfaces, e.g., `0.0.0.0`, then other +If your application is listening on all interfaces, such as `0.0.0.0`, then other applications can call it directly, bypassing its sidecar proxy. Changing the listening address is specific to the language and framework you're -using in your application. Regardless of which language/framework you're using, -it is a good practice to make the address configurable via environment variable. +using in your application. Regardless of which language or framework you're using, +it is a good practice to use the environment variable to configure the address. The following examples demonstrate how to bind the loopback address in golang and Django (Python): From 8dc94aff32720159b0d9c3875a303f39fba08700 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 21 Jun 2022 09:27:04 -0700 Subject: [PATCH 14/18] removed terminating and ingress polices from secure manual installation --- .../docs/ecs/manual/secure-configuration.mdx | 45 ++++--------------- 1 file changed, 8 insertions(+), 37 deletions(-) diff --git a/website/content/docs/ecs/manual/secure-configuration.mdx b/website/content/docs/ecs/manual/secure-configuration.mdx index f9a0ac934..c9a856043 100644 --- a/website/content/docs/ecs/manual/secure-configuration.mdx +++ b/website/content/docs/ecs/manual/secure-configuration.mdx @@ -38,6 +38,8 @@ This section describes how to manually create ACL tokens. Alternatively, you can Configure the following ACL policy for the Consul client token: + + ```hcl node_prefix "" { policy = "write" @@ -47,19 +49,19 @@ service_prefix "" { } ``` + + The policy allows `node:write` for any node name, which is necessary because the Consul node names on ECS are not known until runtime. You can add the policy in Consul using the [`consul acl policy create`](/commands/acl/policy/create) command or the [`[PUT] /v1/acl/policy`](/api-docs/acl/policies#create-a-policy) API endpoint. -If you intend to create a gateway for connecting multiple Consul datacenters, you will need additional policies to specify the permission scope. +If you intend to create a gateway for connecting multiple Consul datacenters, you will need to configure a mesh gateway policy. If namespaces are enabled, the mesh gateway must run in the default namespace. -#### Mesh gateway policy - -Mesh gateways must run in the default namespace. + ```hcl namespace "default" { ## If namespaces enabled - service "" { + service "" { policy = "write" } } @@ -75,39 +77,8 @@ agent_prefix "" { policy = "read" } ``` -#### Terminating gateway policy - -```hcl -partition "" { ## If partitions enabled - namespace "" { ## If namespaces enabled - service "" { - policy = "write" - } - node_prefix "" { - policy = "read" - } - } -} -``` - -#### Ingress gateway policy - -```hcl -partition "" { ## If partitions enabled - namespace "" { ## If namespaces enabled - service "" { - policy = "write" - } - node_prefix "" { - policy = "read" - } - service_prefix "" { - policy = "read" - } - } -} -``` + ### Create service tokens From be6fe117846d8574cc27c061060b4c1f98a47687 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 21 Jun 2022 13:20:14 -0700 Subject: [PATCH 15/18] applied suggestions from review, udpates to TF secure configuration --- .../content/docs/ecs/terraform/install.mdx | 4 +- .../ecs/terraform/secure-configuration.mdx | 86 ++++++++++--------- 2 files changed, 48 insertions(+), 42 deletions(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index 99099d21b..87bf6da0c 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -22,13 +22,13 @@ The following procedure describes the general workflow: 2. [Run Terraform](#running-terraform) to deploy the resources in AWS -If you want to operate Consul with ACLs enabled (recommended), follow the instructions in the [Secure Configuration](/docs/ecs/terraform/secure-configuration) documentation. ACLs provide network security for production-grade deployments. +If you want to operate Consul in production environments, follow the instructions in the [Secure Configuration](/docs/ecs/terraform/secure-configuration) documentation. The instructions describe how to enable ACLs and TLS and gossip encyption, which provide network security for production-grade deployments. ## Requirements * You should have some familiarity with using Terraform. Refer to the [Terraform documentation](https://www.terraform.io/docs) to learn about infrastructure as code and how to get started with Terraform. * You should also be familiar with AWS ECS before following these instructions. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details. -* If you intend to [use the `gateway-task` module to deploy mesh gateways](#configure-the-gateway-task-module), all Consul server and client agents in all datacenters must have TLS and gossip encryption enabled (refer to [Encryption](/docs/security/encryption) for instructions). +* If you intend to [use the `gateway-task` module to deploy mesh gateways](#configure-the-gateway-task-module), all Consul server and client agents in all datacenters must have TLS and gossip encryption enabled. Refer to the [Secure Configuration](/docs/ecs/terraform/secure-configuration) documentation for instructions. ## Create the task definition diff --git a/website/content/docs/ecs/terraform/secure-configuration.mdx b/website/content/docs/ecs/terraform/secure-configuration.mdx index 521141da8..3a7f60e74 100644 --- a/website/content/docs/ecs/terraform/secure-configuration.mdx +++ b/website/content/docs/ecs/terraform/secure-configuration.mdx @@ -7,63 +7,69 @@ description: >- # Secure Configuration -This topic describes how to enable Consul security features for your production workloads. The following overview describes the process: +This topic describes how to enable Consul security features for your production workloads. + +## Overview + +To enable security in your production workloads, you must deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller), which provisions tokens for other service mesh tasks. Refer to [Automatic ACL Token Provisioning](/docs/ecs/architecture#automatic-acl-token-provisioning) to learn more about the ACL controller. + +The controller cannot provision tokens for itself, so you must create the token for the ACL controller. The following steps describe the overall process of enabling security features for your production workloads: 1. Enable the security features on your Consul server cluster per the [Prerequisites](#prerequisites). -1. Deploy the ACL controller. -1. Deploy your services. +1. Create the ACL token for the ACL controller in the datacenter. +1. Create a Secrets Manager secret containing the ACL controller's token. +1. Create a Secrets Manager secret containing the Consul CA certificate. +1. Deploy the ACL controller +1. Deploy the other services on the mesh. ## Prerequisites -Implement the following configurations before proceeding: +Implement the following security features for your Consul server clusters before applying them to your workloads: 1. [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. 1. [Gossip encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. 1. [Access control lists (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. +## ACL controller -## Deploy the ACL controller +1. Create a policy that grants `acl:write` and `operator:write` access for the controller. Refer to the [ACL policies documentation](/docs/security/acl/policies) for instructions. +1. Create a token and link it to the ACL controller policy. Refer to the [ACL tokens documentation](/docs/security/acl/tokens) for instructions. +1. Create a Secrets Manager secret containing the ACL controller's token and a Secrets Manager secret containing the Consul CA cert. -Before deploying your service, you will need to deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller) so that it can provision the necessary tokens -for tasks on the service mesh. To learn more about the ACL Controller, please see [Automatic ACL Token Provisioning](/docs/ecs/architecture#automatic-acl-token-provisioning). + ```hcl + resource "aws_secretsmanager_secret" "bootstrap_token" { + name = "bootstrap-token" + } -To deploy the controller, you will first need to store an ACL token with `acl:write` and `operator:write` privileges, -and a CA certificate for the Consul server in AWS Secrets Manager. + resource "aws_secretsmanager_secret_version" "bootstrap_token" { + secret_id = aws_secretsmanager_secret.bootstrap_token.id + secret_string = "" + } -```hcl -resource "aws_secretsmanager_secret" "bootstrap_token" { - name = "bootstrap-token" -} + resource "aws_secretsmanager_secret" "ca_cert" { + name = "server-ca-cert" + } -resource "aws_secretsmanager_secret_version" "bootstrap_token" { - secret_id = aws_secretsmanager_secret.bootstrap_token.id - secret_string = "" -} + resource "aws_secretsmanager_secret_version" "ca_cert" { + secret_id = aws_secretsmanager_secret.ca_cert.id + secret_string = "" + } + ``` -resource "aws_secretsmanager_secret" "ca_cert" { - name = "server-ca-cert" -} +1. Use the [`acl-controller` terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller?tab=inputs) to deploy the controller. You must provide the ARN's for the token and CA cert in the `consul_bootstrap_token_secret_arn` and `consul_server_ca_cert_arn` fields, respectively. -resource "aws_secretsmanager_secret_version" "ca_cert" { - secret_id = aws_secretsmanager_secret.ca_cert.id - secret_string = "" -} -``` - -Use the [`acl-controller` terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller?tab=inputs) to deploy the controller: - -```hcl -module "acl_controller" { - source = "hashicorp/consul/aws-ecs//modules/acl-controller" - consul_bootstrap_token_secret_arn = aws_secretsmanager_secret.bootstrap_token.arn - consul_server_http_addr = "https://consul-server.example.com:8501" - consul_server_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn - ecs_cluster_arn = "arn:aws:ecs:my-region:111111111111:cluster/consul-ecs" - region = "my-region" - subnets = ["subnet-abcdef123456789"] - name_prefix = "consul-ecs" -} -``` + ```hcl + module "acl_controller" { + source = "hashicorp/consul/aws-ecs//modules/acl-controller" + consul_bootstrap_token_secret_arn = aws_secretsmanager_secret.bootstrap_token.arn + consul_server_http_addr = "https://consul-server.example.com:8501" + consul_server_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn + ecs_cluster_arn = "arn:aws:ecs:my-region:111111111111:cluster/consul-ecs" + region = "my-region" + subnets = ["subnet-abcdef123456789"] + name_prefix = "consul-ecs" + } + ``` The `name_prefix` parameter is used to prefix any secrets that the ACL controller will update in AWS Secrets Manager. The `name_prefix` parameter value must be unique for each ECS cluster where you deploy this controller. From 88dc4de903e22d5d247c598aa78cc28da2b16cac Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Tue, 21 Jun 2022 16:53:10 -0700 Subject: [PATCH 16/18] Apply suggestions from code review Co-authored-by: Chris Thain <32781396+cthain@users.noreply.github.com> --- website/content/docs/ecs/terraform/install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index 87bf6da0c..a7f346b89 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -431,7 +431,7 @@ applications can call it directly, bypassing its sidecar proxy. Changing the listening address is specific to the language and framework you're using in your application. Regardless of which language or framework you're using, -it is a good practice to use the environment variable to configure the address. +it is a good practice to use an environment variable to configure the address. The following examples demonstrate how to bind the loopback address in golang and Django (Python): From e4f243c40209e8d22710a7f8e3d7e02a02f70100 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 21 Jun 2022 17:02:18 -0700 Subject: [PATCH 17/18] removed most of 'ECS service' information --- website/content/docs/ecs/terraform/install.mdx | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index a7f346b89..39b9c2f26 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -189,19 +189,7 @@ Refer to the [gateway task configuration examples](#gateway-task-configuration-e #### ECS service -The ECS service is created as part of the `gateway-task` module configuration. The service can run one or more instances of the gateway. - -The following table describes the inputs for configuring the ECS service in your Terraform configuration file. All inputs are required. Refer to the [gateway task configuration examples](#gateway-task-configuration-examples) for a fully-configured task definition. - -| Input variable | Type | Description | -| --- | --- | --- | -| `ecs_cluster_arn` | string | Specifies the ECS cluster where tasks should be launched. | -| `launch_type` | string | Specifies the ECS service launch type. Can be either `fargate` or `ec2`. | -| `desired_count` | integer | Specifies the number instances for the service to create. Defaults to `0`. | -| `subnets` | string | Specifies the subnet IDs where the tasks launch. | -| `security_group_ids` | string | Specifies the security group IDs to assign to the task ENI. | -| `assign_public_ip` | Boolean | Set to `true` to create a task accessible at a public IP address. Default is `false`.
If set to `true` and `wan_address` is not configured, the WAN address will be set to the public IP of the task. | -| `load_balancer_target_group_arn` | string | Specifies the ARN of an existing load balancer target group. The load balancer target group allows ingress to the gateway task.
No additional load balancer configuration is necessary. Only NLBs and ALBs are supported. The container name and port are set automatically based on other fields. | +The ECS service is automatically created by the `gateway-task` module. The service can run one or more instances of the gateway. #### Mesh init From e8b1ac2060e018eee17087f31b055d7257ae7587 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 22 Jun 2022 10:18:56 -0700 Subject: [PATCH 18/18] applied feedback from review --- website/content/docs/ecs/terraform/install.mdx | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index 39b9c2f26..c523cc0b8 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -243,7 +243,7 @@ module "my_mesh_gateway" { Mesh gateways route L4 TCP connections and do not terminate mTLS sessions. If you manually configure [AWS Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) for ingress to a mesh gateway, you must use an AWS [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) or a [Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html). -#### ACLs +##### ACLs Configure the following options in the `gateway-task` when ACLs are enabled. @@ -267,7 +267,7 @@ module "my_mesh_gateway" { -#### WAN federation +##### WAN federation Configure the following options in the `gateway-task` to enable [WAN federation via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). @@ -419,22 +419,26 @@ applications can call it directly, bypassing its sidecar proxy. Changing the listening address is specific to the language and framework you're using in your application. Regardless of which language or framework you're using, -it is a good practice to use an environment variable to configure the address. +binding the loopback address to a dynamic value, such as an environment variable, is a best practice: -The following examples demonstrate how to bind the loopback address in golang and Django (Python): +```bash +export BIND_ADDRESS="127.0.0.1:8080" +``` + +The following examples demonstrate how to bind the loopback address to an environment variable in golang and Django (Python): ```go s := &http.Server{ - Addr: "127.0.0.1:8080", + Addr: os.Getenv("BIND_ADDRESS"), ... } log.Fatal(s.ListenAndServe()) ``` ```bash -python manage.py runserver "127.0.0.1:8080" +python manage.py runserver "$BIND_ADDRESS" ```