luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #13492 from hashicorp/docs-ecs-mesh-gw 

Docs for ECS Mesh Gateway
This commit is contained in:
trujillo-adam 2022-06-22 15:55:31 -07:00 committed by GitHub
parent 11fb9f6e37 e8b1ac2060
commit 760df49741
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 390 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
website/content/docs/ecs/enterprise.mdx
View File

@ -7,20 +7,19 @@ description: >-
# Consul Enterprise # Consul Enterprise
Consul on ECS supports running Consul Enterprise by specifying the Consul Enterprise You can run Consul Enterprise on ECS by specifying the Consul Enterprise Docker image in the Terraform module parameters.
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, 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, e.g. `hashicorp/consul-enterprise:1.10.0-ent`: 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 ```hcl
module "my_task" { module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task" source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "<latest version>" version = "<latest version>"
consul_image = "hashicorp/consul-enterprise:<version>-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 ### 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. 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:
These features have the following requirements:
* ACLs must be enabled. - ACLs must be enabled.
* ACL controller must run in the ECS cluster. - ACL controller must run in the ECS cluster.
* `mesh-tasks` must use a Consul Enterprise client image. - `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. 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. It also creates admin partitions and namespaces if they do not already exist.

6
website/content/docs/ecs/index.mdx
View File

@ -8,15 +8,13 @@ description: >-
# AWS ECS # AWS ECS
Consul service mesh applications can be deployed on [AWS Elastic Container Service](https://aws.amazon.com/ecs/) (ECS) 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).
using either our official [Terraform modules](/docs/ecs/terraform/install) or without Terraform by [manually configuring
the task definition](/docs/ecs/manual/install).
## Service Mesh ## Service Mesh
Using Consul on AWS ECS enables you to add your ECS tasks to the service mesh and 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, 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 ## Architecture

16
website/content/docs/ecs/manual/install.mdx
View File

@ -7,7 +7,9 @@ description: >-
# Manual Installation # 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.
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 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 ## Task Definition
You must create a task definition, which includes the following containers: Configure a task definition that creates the containers:
* Your application container - Your application container
* An Envoy sidecar-proxy container - An Envoy sidecar-proxy container
* A Consul client container - A Consul client container
* A `consul-ecs-mesh-init` container for service mesh setup - 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 ## Top-level fields

82
website/content/docs/ecs/manual/secure-configuration.mdx
View File

@ -7,41 +7,38 @@ description: >-
# Secure Configuration # Secure Configuration
For a production-ready installation of Consul on ECS, you will need to make sure that the cluster is secured. This topic describes how to enable Consul security features for your production workloads.
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.
## Prerequisites ## Prerequisites
* You should already have followed the [installation instructions](/docs/ecs/manual/install) to understand how to define The following features must be configured for your Consul server cluster:
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. - [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers.
* 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. - [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 [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.
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 ## 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: 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 * **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 * **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. 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).
-> **NOTE:** This section describes how operators would create ACL tokens by hand. To ease operator ### Define policies
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.
### Create Consul client token Configure the following ACL policy for the Consul client token:
You must create a token for the Consul client. This is a shared token used by the `consul-client` <CodeBlockConfig filename="client-token-policy.hcl">
containers to join the Consul cluster.
The following is the ACL policy needed for the Consul client token:
```hcl ```hcl
node_prefix "" { node_prefix "" {
@ -52,22 +49,49 @@ service_prefix "" {
} }
``` ```
This policy allows `node:write` for any node name, which is necessary because the Consul node </CodeBlockConfig>
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 to configure a mesh gateway policy. If namespaces are enabled, the mesh gateway must run in the default namespace.
<CodeBlockConfig filename="mesh-gateway-policy.hcl">
```hcl
namespace "default" { ## If namespaces enabled
service "<service name>" {
policy = "write"
}
}
namespace_prefix "" { ## If namespaces enabled
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
}
agent_prefix "" {
policy = "read"
}
```
</CodeBlockConfig>
### Create service tokens ### Create service tokens
Service tokens should be associated with a [service identity](/docs/security/acl#service-identities). 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 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 ```shell-session
consul acl token create -service-identity=example-client-app ... $ consul acl token create -service-identity=example-client-app ...
``` ```
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.
-> **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 ## Secret storage

320
website/content/docs/ecs/terraform/install.mdx
View File

@ -7,34 +7,42 @@ description: >-
# Installation with Terraform # 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 and runnable examples.
## Overview ## Overview
This topic describes the following procedure: The following procedure describes the general workflow:
1. Create Terraform configuration files for the necessary components: 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 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 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 2. [Run Terraform](#running-terraform) to deploy the resources in AWS
## Prerequisites 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 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. * 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 the [Secure Configuration](/docs/ecs/terraform/secure-configuration) documentation for instructions.
## 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) 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.
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 module enables connectivity between datacenters across service meshes.
### Configure the mesh task module
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 Terraform configuration file called `mesh-task.tf` creates a task definition with an application container called `example-client-app`:
<CodeBlockConfig filename="mesh-task.tf"> <CodeBlockConfig filename="mesh-task.tf">
@ -80,10 +88,216 @@ 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. | | `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. | | `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`. | | `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. |
| `consul_datacenter` | string | The name of your Consul datacenter. | ### Configure an ECS service for the mesh task module
### Running Terraform [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.
<CodeBlockConfig filename="mesh-task.tf" highlight="6-12">
```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"
...
}
```
</CodeBlockConfig>
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 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 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
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`
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 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:
* [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. The following example defines a mesh gateway task called `my-gateway` in a file called `mesh-gateway.tf`:
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
source = "hashicorp/consul-ecs/aws//modules/gateway-task"
version = "<latest version>"
kind = "mesh-gateway"
family = "my-gateway"
ecs_cluster_arn = "<ECS cluster ARN>"
subnets = ["<subnet ID>"]
retry_join = ["<address of the Consul server>"]
tls = true
consul_server_ca_cert_arn = "<Secrets Manager secret ARN>"
gossip_key_secret_arn = "<Secrets Manager secret ARN>"
}
```
</CodeBlockConfig>
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 | 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. |
| `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. |
Refer to the [gateway task configuration examples](#gateway-task-configuration-examples) for additional example configurations.
#### ECS service
The ECS service is automatically created by the `gateway-task` module. The service can run one or more instances of the gateway.
#### Mesh init
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
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.
| 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. |
| `lb_subnets` | list of strings | Specifies one or more public subnets to associate with the load balancer. |
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
lb_enabled = true
lb_vpc_id = "<VPC ID>"
lb_subnets = ["<public subnet IDs>"]
}
```
</CodeBlockConfig>
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.
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
wan_address = "<public WAN address>"
wan_port = <public WAN port>
}
```
</CodeBlockConfig>
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. |
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
acls = true
consul_http_addr = "<HTTP address of the Consul server>"
consul_https_ca_cert_arn = "<Secrets Manager secret ARN>"
}
```
</CodeBlockConfig>
##### 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.
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
consul_datacenter = "<name of the local Consul datacenter>"
consul_primary_datacenter = "<name of the primary Consul datacenter>"
enable_mesh_gateway_wan_federation = true
enable_acl_token_replication = true
}
```
</CodeBlockConfig>
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
You will need to run Terraform to create the task definition. You will need to run Terraform to create the task definition.
@ -132,52 +346,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. 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. Refer to the [Terraform documentation](https://www.terraform.io/docs) for more information and Terraform best practices.
## ECS Service ## Configure routes
[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.
<CodeBlockConfig filename="mesh-task.tf" highlight="6-12">
```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"
...
}
```
</CodeBlockConfig>
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
Now that your tasks are registered in the mesh, you're able to use the service Now that your tasks are registered in the mesh, you're able to use the service
mesh to route between them. mesh to route between them.
@ -239,37 +408,42 @@ module "web" {
} }
``` ```
## Bind Address ## Configure the bind address
To ensure that your application only receives traffic through the service mesh, 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 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`.
(also known as `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.
so that only the sidecar proxy running in the same task can make requests to it.
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. applications can call it directly, bypassing its sidecar proxy.
Changing the listening address is specific to the language and framework you're 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, using in your application. Regardless of which language or framework you're using,
it's a good practice to make the address configurable via environment variable. binding the loopback address to a dynamic value, such as an environment variable, is a best practice:
For example in Go, you would use: ```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):
<CodeTabs>
```go ```go
s := &http.Server{ s := &http.Server{
Addr: "127.0.0.1:8080", Addr: os.Getenv("BIND_ADDRESS"),
... ...
} }
log.Fatal(s.ListenAndServe()) log.Fatal(s.ListenAndServe())
``` ```
In Django you'd use:
```bash ```bash
python manage.py runserver "127.0.0.1:8080" python manage.py runserver "$BIND_ADDRESS"
``` ```
## Next Steps </CodeTabs>
## Next steps
- Follow the [Secure Configuration](/docs/ecs/terraform/secure-configuration) to get production-ready. - 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 - Now that your applications are running in the service mesh, read about

119
website/content/docs/ecs/terraform/secure-configuration.mdx
View File

@ -7,71 +7,82 @@ description: >-
# Secure Configuration # Secure Configuration
For a production-ready installation of Consul on ECS, you will need to make sure that the cluster is secured. This topic describes how to enable Consul security features for your production workloads.
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. ## Overview
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:** This page assumes that you have already configured your Consul server with the above features. 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.
## Deploy 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:
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 1. Enable the security features on your Consul server cluster per the [Prerequisites](#prerequisites).
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). 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.
To deploy the controller, you will first need to store an ACL token with `acl:write` and `operator:write` privileges, ## Prerequisites
and a CA certificate for the Consul server in AWS Secrets Manager.
```hcl Implement the following security features for your Consul server clusters before applying them to your workloads:
resource "aws_secretsmanager_secret" "bootstrap_token" {
name = "bootstrap-token"
}
resource "aws_secretsmanager_secret_version" "bootstrap_token" { 1. [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers.
secret_id = aws_secretsmanager_secret.bootstrap_token.id 1. [Gossip encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic.
secret_string = "<bootstrap token>" 1. [Access control lists (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh.
}
resource "aws_secretsmanager_secret" "ca_cert" { ## ACL controller
name = "server-ca-cert"
}
resource "aws_secretsmanager_secret_version" "ca_cert" { 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.
secret_id = aws_secretsmanager_secret.ca_cert.id 1. Create a token and link it to the ACL controller policy. Refer to the [ACL tokens documentation](/docs/security/acl/tokens) for instructions.
secret_string = "<CA certificate for the Consul server's HTTPS endpoint>" 1. Create a Secrets Manager secret containing the ACL controller's token and a Secrets Manager secret containing the Consul CA cert.
}
```
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
resource "aws_secretsmanager_secret" "bootstrap_token" {
name = "bootstrap-token"
}
```hcl resource "aws_secretsmanager_secret_version" "bootstrap_token" {
module "acl_controller" { secret_id = aws_secretsmanager_secret.bootstrap_token.id
source = "hashicorp/consul/aws-ecs//modules/acl-controller" secret_string = "<bootstrap token>"
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 resource "aws_secretsmanager_secret" "ca_cert" {
ecs_cluster_arn = "arn:aws:ecs:my-region:111111111111:cluster/consul-ecs" name = "server-ca-cert"
region = "my-region" }
subnets = ["subnet-abcdef123456789"]
name_prefix = "consul-ecs" resource "aws_secretsmanager_secret_version" "ca_cert" {
} secret_id = aws_secretsmanager_secret.ca_cert.id
``` secret_string = "<CA certificate for the Consul server's HTTPS endpoint>"
}
```
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.
```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 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 deploy this controller.
-> **NOTE:** Make sure that the `name_prefix` is unique for each ECS cluster where you are ## Deploy your services
deploying this controller.
## 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). ### Create an AWS Secrets Manager secret
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.
First, you will need to create an AWS Secrets Manager secret for the gossip encryption key that the Consul clients The secret stores the gossip encryption key that the Consul clients use.
should use.
<CodeBlock>
```hcl ```hcl
resource "aws_secretsmanager_secret" "gossip_key" { resource "aws_secretsmanager_secret" "gossip_key" {
@ -83,8 +94,11 @@ resource "aws_secretsmanager_secret_version" "gossip_key" {
secret_string = "<Gossip encryption key>" secret_string = "<Gossip encryption key>"
} }
``` ```
</CodeBlock>
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. should be the same as the `name_prefix` you provide to the ACL controller module.
```hcl ```hcl
@ -104,5 +118,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) Complete the following steps described in the Installation with Terraform chapter to deploy and connect your services:
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)