Merge pull request #13492 from hashicorp/docs-ecs-mesh-gw
Docs for ECS Mesh Gateway
This commit is contained in:
trujillo-adam
GitHub
commit
760df49741
|
|
@ -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 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
|
||||
module "my_task" {
|
||||
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
|
||||
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
|
||||
|
||||
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.
|
||||
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-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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 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.
|
||||
|
||||
|
|
@ -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:
|
||||
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
|
||||
* Optionally, a `consul-ecs-health-sync` container to sync ECS health checks into Consul
|
||||
- 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
|
||||
|
||||
|
|
|
|||
|
|
@ -7,41 +7,38 @@ 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 [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
|
||||
|
||||
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. 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
|
||||
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
|
||||
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`
|
||||
containers to join the Consul cluster.
|
||||
|
||||
The following is the ACL policy needed for the Consul client token:
|
||||
<CodeBlockConfig filename="client-token-policy.hcl">
|
||||
|
||||
```hcl
|
||||
node_prefix "" {
|
||||
|
|
@ -52,22 +49,49 @@ 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.
|
||||
</CodeBlockConfig>
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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 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
|
||||
|
||||
|
|
|
|||
|
|
@ -7,34 +7,42 @@ 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 and 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
|
||||
|
||||
## 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 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)
|
||||
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.
|
||||
|
||||
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">
|
||||
|
||||
|
|
@ -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. |
|
||||
| `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. |
|
||||
| `consul_datacenter` | string | The name of your Consul datacenter. |
|
||||
| `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. |
|
||||
### 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.
|
||||
|
||||
|
|
@ -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.
|
||||
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.
|
||||
|
||||
<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
|
||||
## Configure routes
|
||||
|
||||
Now that your tasks are registered in the mesh, you're able to use the service
|
||||
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,
|
||||
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 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's a good practice to make the address configurable via environment variable.
|
||||
using in your application. Regardless of which language or framework you're using,
|
||||
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
|
||||
s := &http.Server{
|
||||
Addr: "127.0.0.1:8080",
|
||||
Addr: os.Getenv("BIND_ADDRESS"),
|
||||
...
|
||||
}
|
||||
log.Fatal(s.ListenAndServe())
|
||||
```
|
||||
|
||||
In Django you'd use:
|
||||
|
||||
```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.
|
||||
- Now that your applications are running in the service mesh, read about
|
||||
|
|
|
|||
|
|
@ -7,47 +7,59 @@ 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.
|
||||
|
||||
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.
|
||||
## Overview
|
||||
|
||||
-> **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
|
||||
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. Enable the security features on your Consul server cluster per the [Prerequisites](#prerequisites).
|
||||
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,
|
||||
and a CA certificate for the Consul server in AWS Secrets Manager.
|
||||
## Prerequisites
|
||||
|
||||
```hcl
|
||||
resource "aws_secretsmanager_secret" "bootstrap_token" {
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
```hcl
|
||||
resource "aws_secretsmanager_secret" "bootstrap_token" {
|
||||
name = "bootstrap-token"
|
||||
}
|
||||
}
|
||||
|
||||
resource "aws_secretsmanager_secret_version" "bootstrap_token" {
|
||||
resource "aws_secretsmanager_secret_version" "bootstrap_token" {
|
||||
secret_id = aws_secretsmanager_secret.bootstrap_token.id
|
||||
secret_string = "<bootstrap token>"
|
||||
}
|
||||
}
|
||||
|
||||
resource "aws_secretsmanager_secret" "ca_cert" {
|
||||
resource "aws_secretsmanager_secret" "ca_cert" {
|
||||
name = "server-ca-cert"
|
||||
}
|
||||
}
|
||||
|
||||
resource "aws_secretsmanager_secret_version" "ca_cert" {
|
||||
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>"
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
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" {
|
||||
```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"
|
||||
|
|
@ -56,22 +68,21 @@ module "acl_controller" {
|
|||
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.
|
||||
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
|
||||
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 use.
|
||||
|
||||
<CodeBlock>
|
||||
|
||||
```hcl
|
||||
resource "aws_secretsmanager_secret" "gossip_key" {
|
||||
|
|
@ -83,8 +94,11 @@ resource "aws_secretsmanager_secret_version" "gossip_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.
|
||||
|
||||
```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)
|
||||
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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue