From e81bf74e4eddb5e6830d4bd6a4350d2d9874afd8 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 14 Sep 2021 16:36:52 -0700 Subject: [PATCH 01/16] updates to ECS docs per beta release --- .../content/docs/ecs/get-started/install.mdx | 132 ------------------ .../docs/ecs/get-started/requirements.mdx | 14 +- website/content/docs/ecs/index.mdx | 4 +- website/data/docs-nav-data.json | 2 +- 4 files changed, 7 insertions(+), 145 deletions(-) diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx index 7cc30e552..bd860ed7b 100644 --- a/website/content/docs/ecs/get-started/install.mdx +++ b/website/content/docs/ecs/get-started/install.mdx @@ -11,8 +11,6 @@ Installing Consul on ECS is a multi-part process: 1. [**Terraform:**](#terraform) Your tasks must be specified in Terraform using [`ecs_task_definition`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition) and [`ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) resources. -1. [**Consul Server:**](#consul-server) You must deploy the Consul server onto the cluster using the [`dev-server` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/dev-server). -1. [**Task IAM Role:**](#task-iam-role) Modify task IAM role to add `ecs:ListTasks` and `ecs:DescribeTasks` permissions. 1. [**Task Module:**](#task-module) You can then take your `ecs_task_definition` resources and copy their configuration into a new [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) resource that will add the necessary containers to the task definition. 1. [**Routing:**](#routing) With your tasks as part of the mesh, you must specify their upstream @@ -72,136 +70,6 @@ resource "aws_ecs_service" "my_task" { } ``` -## Consul Server - -With your tasks defined in Terraform, you're ready to run the Consul server -on ECS. - --> **NOTE:** This is a development-only Consul server. It has no persistent -storage and so will lose any data when it restarts. This should only be -used for test workloads. In the future, we will support Consul servers -running in HashiCorp Cloud Platform and on EC2 VMs for production workloads. - -In order to deploy the Consul server, use the `dev-server` module: - -```hcl -module "dev_consul_server" { - source = "hashicorp/consul/aws-ecs//modules/dev-server" - version = "" - - ecs_cluster_arn = var.ecs_cluster_arn - subnet_ids = var.subnet_ids - lb_vpc_id = var.vpc_id - load_balancer_enabled = true - lb_subnets = var.lb_subnet_ids - lb_ingress_rule_cidr_blocks = var.lb_ingress_rule_cidr_blocks - log_configuration = { - logDriver = "awslogs" - options = { - awslogs-group = aws_cloudwatch_log_group.log_group.name - awslogs-region = var.region - awslogs-stream-prefix = "consul-server" - } - } -} - -data "aws_security_group" "vpc_default" { - name = "default" - vpc_id = var.vpc_id -} - -resource "aws_security_group_rule" "ingress_from_server_alb_to_ecs" { - type = "ingress" - from_port = 8500 - to_port = 8500 - protocol = "tcp" - source_security_group_id = module.dev_consul_server.lb_security_group_id - security_group_id = data.aws_security_group.vpc_default.id -} - -output "consul_server_url" { - value = "http://${module.dev_consul_server.lb_dns_name}:8500" -} -``` - --> **NOTE:** The documentation for all possible inputs can be found in the [module reference -docs](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/dev-server?tab=inputs). - -The example code above will create a Consul server ECS task and Application Load -Balancer for the Consul UI. You can then use the output `consul_server_url` as -the URL to the Consul server. - -## Task IAM Role - -Your tasks must have an IAM role that allows them to list and describe -other tasks. This is required in order for the tasks to find the IP -address of the Consul server. - -The specific permissions needed are: - -1. `ecs:ListTasks` on resource `*`. -1. `ecs:DescribeTasks` on all tasks in this account and region. You can either - use `*` for simplicity or scope it to the region and account, e.g. `arn:aws:ecs:us-east-1:1111111111111:task/*`. If - your account is configured to use the new, [longer ECS task ARN format](https://docs.aws.amazon.com/AmazonECS/latest/userguide/ecs-account-settings.html#ecs-resource-ids) - then you can further scope `ecs:DescribeTasks` down to tasks in a specific cluster, e.g. `arn:aws:ecs:us-east-1:1111111111111:task/MY_CLUSTER_NAME/*`. - -The IAM role's ARN will be passed into the `mesh-task` module in the next step -via the `task_role_arn` input. - --> **NOTE:** There are two IAM roles needed by ECS Tasks: Execution roles and -Task roles. Here we are referring to the Task role, not the Execution role. -The Execution role is used by ECS itself whereas the Task role defines the -permissions for the containers running in the task. - -Terraform for creating the IAM role might look like: - -```hcl -data "aws_caller_identity" "this" {} - -resource "aws_iam_role" "this_task" { - name = "this_task" - assume_role_policy = jsonencode({ - Version = "2012-10-17" - Statement = [ - { - Action = "sts:AssumeRole" - Effect = "Allow" - Sid = "" - Principal = { - Service = "ecs-tasks.amazonaws.com" - } - }, - ] - }) - - inline_policy { - name = "this_task" - policy = jsonencode({ - Version = "2012-10-17" - Statement = [ - { - Effect = "Allow" - Action = [ - "ecs:ListTasks", - ] - Resource = "*" - }, - { - Effect = "Allow" - Action = [ - "ecs:DescribeTasks" - ] - Resource = [ - "arn:aws:ecs:${var.region}:${data.aws_caller_identity.this.account_id}:task/*", - ] - } - ] - }) - } -} - -``` - ## Task Module In order to add the necessary sidecar containers for your task to join the mesh, diff --git a/website/content/docs/ecs/get-started/requirements.mdx b/website/content/docs/ecs/get-started/requirements.mdx index eae69f257..33f1ab459 100644 --- a/website/content/docs/ecs/get-started/requirements.mdx +++ b/website/content/docs/ecs/get-started/requirements.mdx @@ -7,16 +7,10 @@ description: >- # Requirements -Currently, the following requirements must be met in order to install Consul on ECS: +The following requirements must be met in order to install Consul on ECS: 1. **Terraform:** The tasks that you want to add to the service mesh must first be modeled in Terraform. -1. **Launch Type:** Only the Fargate launch type is currently supported. +1. **Launch Type:** Fargate and EC2 launch types are supported. 1. **Subnets:** ECS Tasks can run in private or public subnets. Tasks must have [network access](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-api-error-ecr/) to Amazon ECR to pull images. -1. **Consul Servers:** Currently, Consul servers must run inside ECS on Fargate using the `dev-server` Terraform module. This is a development/testing only server that does not support persistent storage. In the future, we will support production-ready Consul servers running in HashiCorp Cloud Platform and on EC2 VMs. - -## Future Improvements - -- Support EC2 launch type. -- Support production-ready Consul servers running outside of ECS in HashiCorp Cloud Platform or EC2. -- Support Consul TLS, ACLs, and Gossip Encryption. -- Support Consul service health checks. +1. **Consul Servers:** You can use your own Consul servers or run servers inside ECS on Fargate using the `dev-server` Terraform module. The is a development/testing only server that does not support persistent storage. +1. **ACL Controller:** If you are running a secure Consul installation, configure the ACL controller. diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx index e3518beb3..67c20c589 100644 --- a/website/content/docs/ecs/index.mdx +++ b/website/content/docs/ecs/index.mdx @@ -8,8 +8,8 @@ description: >- # AWS ECS --> **Tech Preview:** This functionality is currently in Tech Preview and is -not yet ready for production use. +-> **Beta:** This functionality is currently in beta and is +not recommended for use in production environments. Refer to the [consul-ecs-project road map](https://github.com/hashicorp/consul-ecs/projects/1) for information about upcoming features and enhancements. Consul can be deployed on [AWS ECS](https://aws.amazon.com/ecs/) (Elastic Container Service) using our official Terraform modules. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 5b27cffc1..15838d9da 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -556,7 +556,7 @@ ] }, { - "title": "AWS ECS Tech Preview", + "title": "AWS ECS BETA", "routes": [ { "title": "Overview", From d2dce8735fda274d8d4d17823578b662b14f909c Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Wed, 15 Sep 2021 10:46:00 -0700 Subject: [PATCH 02/16] Apply suggestions from code review Co-authored-by: mrspanishviking --- website/content/docs/ecs/get-started/requirements.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/ecs/get-started/requirements.mdx b/website/content/docs/ecs/get-started/requirements.mdx index 33f1ab459..f063e2012 100644 --- a/website/content/docs/ecs/get-started/requirements.mdx +++ b/website/content/docs/ecs/get-started/requirements.mdx @@ -11,6 +11,6 @@ The following requirements must be met in order to install Consul on ECS: 1. **Terraform:** The tasks that you want to add to the service mesh must first be modeled in Terraform. 1. **Launch Type:** Fargate and EC2 launch types are supported. -1. **Subnets:** ECS Tasks can run in private or public subnets. Tasks must have [network access](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-api-error-ecr/) to Amazon ECR to pull images. -1. **Consul Servers:** You can use your own Consul servers or run servers inside ECS on Fargate using the `dev-server` Terraform module. The is a development/testing only server that does not support persistent storage. +1. **Subnets:** ECS Tasks can run in private or public subnets. Tasks must have [network access](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-api-error-ecr/) to Amazon ECR or other public container registries to pull images. +1. **Consul Servers:** You can use your own Consul servers (VM) or use HCP Consul. For development purposes or testing, you may use the `dev-server` [Terraform module](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main). The `dev-server` does not support persistent storage. 1. **ACL Controller:** If you are running a secure Consul installation, configure the ACL controller. From 1097c78a6a4c95546e9563d5829619db056e620c Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 13:00:33 -0500 Subject: [PATCH 03/16] ECS architecture docs for Beta --- website/content/docs/ecs/architecture.mdx | 45 +++++++++++++++-------- website/public/img/consul-ecs-arch.png | 4 +- website/public/img/ecs-task-startup.png | 4 +- 3 files changed, 34 insertions(+), 19 deletions(-) diff --git a/website/content/docs/ecs/architecture.mdx b/website/content/docs/ecs/architecture.mdx index 5c1e9cd59..d8203a31b 100644 --- a/website/content/docs/ecs/architecture.mdx +++ b/website/content/docs/ecs/architecture.mdx @@ -9,9 +9,9 @@ description: >- ![Consul on ECS Architecture](/img/consul-ecs-arch.png) -As shown above there are two main components to the architecture. +As shown above, these are the main components to the architecture for a secure installation: -1. **Consul Server task:** Runs the Consul server. +1. **Consul Servers:** Production-ready Consul server cluster 1. **Application tasks:** Runs user application containers along with two helper containers: 1. **Consul Client:** The Consul client container runs Consul. The Consul client communicates with the Consul server and configures the Envoy proxy sidecar. This communication @@ -19,14 +19,13 @@ As shown above there are two main components to the architecture. 1. **Sidecar Proxy:** The sidecar proxy container runs [Envoy](https://envoyproxy.io/). All requests to and from the application container(s) run through the sidecar proxy. This communication is called _data plane_ communication. +1. **ACL Controller:** Automatically provisions Consul ACL tokens for Consul clients and service mesh services + in an ECS Cluster. For more information about how Consul works in general, see Consul's [Architecture Overview](/docs/architecture). -In addition to the long-running Consul Client and Sidecar Proxy containers, there -are also two initialization containers that run: - -1. `discover-servers`: This container runs at startup and uses the AWS API to determine the IP address of the Consul server task. -1. `mesh-init`: This container runs at startup and sets up initial configuration for Consul and Envoy. +In addition to the long-running Consul Client and Sidecar Proxy containers, the `mesh-init` container runs +at startup and sets up initial configuration for Consul and Envoy. ### Task Startup @@ -34,12 +33,28 @@ This diagram shows the timeline of a task starting up and all its containers: ![Task Startup Timeline](/img/ecs-task-startup.png) -- **T0:** ECS starts the task. The `discover-servers` container starts looking for the Consul server task’s IP. - It waits for the Consul server task to be running on ECS, looks up its IP and then writes the address to a file. - Then the container exits. -- **T1:** Both the `consul-client` and `mesh-init` containers start: - - `consul-client` starts up and uses the server IP to join the cluster. +- **T0:** ECS starts the task. The `consul-client` and `mesh-init` containers start: + - `consul-client` uses the `retry-join` option to join the Consul cluster - `mesh-init` registers the service for this task and its sidecar proxy into Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s bootstrap JSON file and write it to a shared volume. After registration and bootstrapping, `mesh-init` exits. -- **T2:** The `sidecar-proxy` container starts. It runs Envoy by executing `envoy -c `. -- **T3:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, the user’s application containers are started since all the Consul machinery is ready to service requests. -- **T4:** Consul marks the service as healthy by running the health checks specified in the task Terraform. The service will now receive traffic. At this time the only running containers are `consul-client`, `sidecar-proxy` and the user’s application container(s). +- **T1:** The `sidecar-proxy` container starts. It runs Envoy by executing `envoy -c `. +- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, the user’s application containers are started since all the Consul machinery is ready to service requests. +- **T3:** Consul marks the service as healthy by running the health checks specified in the task Terraform. The service will now receive traffic. At this time the only running containers are `consul-client`, `sidecar-proxy` and the user’s application container(s). + +### Automatic ACL Token Provisioning + +Consul ACL tokens secure communication between agents and services. +The following containers in a task require an ACL token: + +- `consul-client`: The Consul client uses a token to authorize itself with Consul servers. + All `consul-client` containers share the same token. +- `mesh-init`: The `mesh-init` container uses a token to register the service with Consul. + This token is unique for the Consul service, and is shared by instances of the service. + +The ACL controller automatically creates ACL tokens for mesh-enabled tasks in an ECS cluster. +The `acl-controller` Terraform module creates the ACL token used by `consul-client` containers, and +then starts the ACL controller task. The controller watches for tasks in the cluster. It checks tags +to determine if the task is mesh-enabled. If so, it creates the service ACL token for the task, if the +token does not yet exist. + +The ACL controller stores all ACL tokens in AWS Secrets Manager, and tasks are configured to pull these +tokens from AWS Secrets Manager when they start. diff --git a/website/public/img/consul-ecs-arch.png b/website/public/img/consul-ecs-arch.png index 15edb2dc1..ae43ab9b4 100644 --- a/website/public/img/consul-ecs-arch.png +++ b/website/public/img/consul-ecs-arch.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:0c7a6a32cd0274676472a23118dc514846167bd90aeb467fa3cc72c24eaa4aa3 -size 90967 +oid sha256:96298e2c4297f01f39c68e1b6c5f79e136efc4a297265a294a0ee44edd1f210f +size 77203 diff --git a/website/public/img/ecs-task-startup.png b/website/public/img/ecs-task-startup.png index cd038b65c..9a25c090a 100644 --- a/website/public/img/ecs-task-startup.png +++ b/website/public/img/ecs-task-startup.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:32ab2df3e73593b1aa9174c604049f8bdf4b25d31d56a667e037f36f485fb84a -size 15140 +oid sha256:c66ab08977f6b51de03edf631ee217503821150cec71cf73ee69f25cecf052aa +size 11547 From a10d3f1991970c34bfd742024e762a410cb0f6f5 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 13:38:19 -0500 Subject: [PATCH 04/16] docs: correct point about service health checks for ECS --- website/content/docs/ecs/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/ecs/architecture.mdx b/website/content/docs/ecs/architecture.mdx index d8203a31b..df108a624 100644 --- a/website/content/docs/ecs/architecture.mdx +++ b/website/content/docs/ecs/architecture.mdx @@ -38,7 +38,7 @@ This diagram shows the timeline of a task starting up and all its containers: - `mesh-init` registers the service for this task and its sidecar proxy into Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s bootstrap JSON file and write it to a shared volume. After registration and bootstrapping, `mesh-init` exits. - **T1:** The `sidecar-proxy` container starts. It runs Envoy by executing `envoy -c `. - **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, the user’s application containers are started since all the Consul machinery is ready to service requests. -- **T3:** Consul marks the service as healthy by running the health checks specified in the task Terraform. The service will now receive traffic. At this time the only running containers are `consul-client`, `sidecar-proxy` and the user’s application container(s). +- **T3:** The service will now receive traffic. At this time the only running containers are `consul-client`, `sidecar-proxy` and the user’s application container(s). ### Automatic ACL Token Provisioning From 58062ce58779d54fab42905c8d8b7093146efe20 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 13:49:33 -0500 Subject: [PATCH 05/16] docs: remove T3 in ECS task startup arch doc --- website/content/docs/ecs/architecture.mdx | 3 +-- website/public/img/ecs-task-startup.png | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/website/content/docs/ecs/architecture.mdx b/website/content/docs/ecs/architecture.mdx index df108a624..a9ab9ead2 100644 --- a/website/content/docs/ecs/architecture.mdx +++ b/website/content/docs/ecs/architecture.mdx @@ -37,8 +37,7 @@ This diagram shows the timeline of a task starting up and all its containers: - `consul-client` uses the `retry-join` option to join the Consul cluster - `mesh-init` registers the service for this task and its sidecar proxy into Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s bootstrap JSON file and write it to a shared volume. After registration and bootstrapping, `mesh-init` exits. - **T1:** The `sidecar-proxy` container starts. It runs Envoy by executing `envoy -c `. -- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, the user’s application containers are started since all the Consul machinery is ready to service requests. -- **T3:** The service will now receive traffic. At this time the only running containers are `consul-client`, `sidecar-proxy` and the user’s application container(s). +- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, the user’s application containers are started since all the Consul machinery is ready to service requests. The only running containers are `consul-client`, `sidecar-proxy` and the user’s application container(s). ### Automatic ACL Token Provisioning diff --git a/website/public/img/ecs-task-startup.png b/website/public/img/ecs-task-startup.png index 9a25c090a..423cac98a 100644 --- a/website/public/img/ecs-task-startup.png +++ b/website/public/img/ecs-task-startup.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:c66ab08977f6b51de03edf631ee217503821150cec71cf73ee69f25cecf052aa -size 11547 +oid sha256:45b65560c8acd7069c0e98fe9f5dbe074486b2043edf3794c770267eae07dd3d +size 10694 From c9aa64270ea56b5d7c31103316b75c8c9f935086 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 15:04:39 -0500 Subject: [PATCH 06/16] docs: Address ECS architecture feedback --- website/content/docs/ecs/architecture.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/website/content/docs/ecs/architecture.mdx b/website/content/docs/ecs/architecture.mdx index a9ab9ead2..e6e3ed39f 100644 --- a/website/content/docs/ecs/architecture.mdx +++ b/website/content/docs/ecs/architecture.mdx @@ -7,16 +7,16 @@ description: >- # Architecture +The following diagram shows the main components of the Consul architecture when deployed to an ECS cluster: + ![Consul on ECS Architecture](/img/consul-ecs-arch.png) -As shown above, these are the main components to the architecture for a secure installation: - -1. **Consul Servers:** Production-ready Consul server cluster +1. **Consul servers:** Production-ready Consul server cluster 1. **Application tasks:** Runs user application containers along with two helper containers: - 1. **Consul Client:** The Consul client container runs Consul. The Consul client communicates + 1. **Consul client:** The Consul client container runs Consul. The Consul client communicates with the Consul server and configures the Envoy proxy sidecar. This communication is called _control plane_ communication. - 1. **Sidecar Proxy:** The sidecar proxy container runs [Envoy](https://envoyproxy.io/). All requests + 1. **Sidecar proxy:** The sidecar proxy container runs [Envoy](https://envoyproxy.io/). All requests to and from the application container(s) run through the sidecar proxy. This communication is called _data plane_ communication. 1. **ACL Controller:** Automatically provisions Consul ACL tokens for Consul clients and service mesh services @@ -24,7 +24,7 @@ As shown above, these are the main components to the architecture for a secure i For more information about how Consul works in general, see Consul's [Architecture Overview](/docs/architecture). -In addition to the long-running Consul Client and Sidecar Proxy containers, the `mesh-init` container runs +In addition to the long-running Consul client and sidecar proxy containers, the `mesh-init` container runs at startup and sets up initial configuration for Consul and Envoy. ### Task Startup @@ -37,7 +37,7 @@ This diagram shows the timeline of a task starting up and all its containers: - `consul-client` uses the `retry-join` option to join the Consul cluster - `mesh-init` registers the service for this task and its sidecar proxy into Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s bootstrap JSON file and write it to a shared volume. After registration and bootstrapping, `mesh-init` exits. - **T1:** The `sidecar-proxy` container starts. It runs Envoy by executing `envoy -c `. -- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, the user’s application containers are started since all the Consul machinery is ready to service requests. The only running containers are `consul-client`, `sidecar-proxy` and the user’s application container(s). +- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that detects if its public listener port is open. At this time, your application containers are started since all Consul machinery is ready to service requests. The only running containers are `consul-client`, `sidecar-proxy`, and your application container(s). ### Automatic ACL Token Provisioning From a12fb39af72829b2eab9cd687e9758dd0ad8057a Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 15 Sep 2021 14:09:47 -0700 Subject: [PATCH 07/16] applied comment feedback about my_task example --- website/content/docs/ecs/get-started/install.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx index bd860ed7b..82116d585 100644 --- a/website/content/docs/ecs/get-started/install.mdx +++ b/website/content/docs/ecs/get-started/install.mdx @@ -37,8 +37,6 @@ resource "aws_ecs_task_definition" "my_task" { network_mode = "awsvpc" cpu = 256 memory = 512 - execution_role_arn = "arn:aws:iam::111111111111:role/execution-role" - task_role_arn = "arn:aws:iam::111111111111:role/task-role" container_definitions = jsonencode( [{ name = "example-client-app" @@ -86,8 +84,6 @@ module "my_task" { version = "" family = "my_task" - execution_role_arn = "arn:aws:iam::111111111111:role/execution-role" - task_role_arn = "arn:aws:iam::111111111111:role/task-role" container_definitions = [ { name = "example-client-app" @@ -107,7 +103,7 @@ module "my_task" { ] port = "9090" - consul_server_service_name = module.dev_consul_server.ecs_service_name + retry_join = "
" } ``` From 198841c2968ef4742aab858d61daf80b8d019049 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 16:18:37 -0500 Subject: [PATCH 08/16] docs: ECS architecture feedback --- website/content/docs/ecs/architecture.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/ecs/architecture.mdx b/website/content/docs/ecs/architecture.mdx index e6e3ed39f..2dcfcbf68 100644 --- a/website/content/docs/ecs/architecture.mdx +++ b/website/content/docs/ecs/architecture.mdx @@ -50,8 +50,8 @@ The following containers in a task require an ACL token: This token is unique for the Consul service, and is shared by instances of the service. The ACL controller automatically creates ACL tokens for mesh-enabled tasks in an ECS cluster. -The `acl-controller` Terraform module creates the ACL token used by `consul-client` containers, and -then starts the ACL controller task. The controller watches for tasks in the cluster. It checks tags +The `acl-controller` Terraform module creates the ACL controller task. The controller creates the +ACL token used by `consul-client` containers at startup and then watches for tasks in the cluster. It checks tags to determine if the task is mesh-enabled. If so, it creates the service ACL token for the task, if the token does not yet exist. From f969ffec633793dffe3f436fedb7e01929d30be9 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 16:10:04 -0500 Subject: [PATCH 09/16] docs: Migrate Existing Tasks page for ECS --- .../get-started/migrate-existing-tasks.mdx | 173 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 2 files changed, 177 insertions(+) create mode 100644 website/content/docs/ecs/get-started/migrate-existing-tasks.mdx diff --git a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx b/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx new file mode 100644 index 000000000..b5ee18868 --- /dev/null +++ b/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx @@ -0,0 +1,173 @@ +--- +layout: docs +page_title: Migrate Existing Tasks - AWS ECS +description: >- + Migrate Existing Tasks +--- + +# Migrate Existing Tasks + +This guide explains how to migrate your existing ECS Tasks to use our [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). + +## Define Tasks in Terraform + +Your tasks must first be specified in Terraform using [`ecs_task_definition`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition) +and [`ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) resources so that +they can later be converted to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). + +For example, your tasks should be defined with Terraform similar to the following: + +```hcl +resource "aws_ecs_task_definition" "my_task" { + family = "my_task" + requires_compatibilities = ["FARGATE"] + network_mode = "awsvpc" + cpu = 256 + memory = 512 + execution_role_arn = "arn:aws:iam::111111111111:role/execution-role" + task_role_arn = "arn:aws:iam::111111111111:role/task-role" + container_definitions = jsonencode( + [{ + name = "example-client-app" + image = "docker.io/org/my_task:v0.0.1" + essential = true + portMappings = [ + { + containerPort = 9090 + hostPort = 9090 + protocol = "tcp" + } + ] + cpu = 0 + mountPoints = [] + volumesFrom = [] + }] + ) +} + +resource "aws_ecs_service" "my_task" { + name = "my_task" + cluster = "arn:aws:ecs:us-east-1:111111111111:cluster/my-cluster" + task_definition = aws_ecs_task_definition.my_task.arn + desired_count = 1 + network_configuration { + subnets = ["subnet-abc123"] + } + launch_type = "FARGATE" +} +``` + +## Convert Tasks to Mesh Module + +In order to add the necessary sidecar containers for your task to join the mesh, +you must use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). + +The `mesh-task` module uses inputs similar to your old ECS task definition but +creates a new version of the task definition with additional containers. + +The `mesh-task` module is used as follows: + +```hcl +module "my_task" { + source = "hashicorp/consul/aws-ecs//modules/mesh-task" + version = "" + + family = "my_task" + container_definitions = [ + { + name = "example-client-app" + image = "docker.io/org/my_task:v0.0.1" + essential = true + portMappings = [ + { + containerPort = 9090 + hostPort = 9090 + protocol = "tcp" + } + ] + cpu = 0 + mountPoints = [] + volumesFrom = [] + } + ] + + port = "9090" + retry_join = "
" +} +``` + +All possible inputs are documented on the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) +however there are some important inputs worth highlighting: + +- You do not need the `execution_role_arn` or `task_role_arn` fields. The `mesh-task` module will create the task and execution roles. +- `family` is used as the [task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family) and the name of the service that is registered in Consul. +- `container_definitions` accepts an array of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions). + These are your application containers and are the same as `container_definitions` key in the + `aws_ecs_task_definition` resource without the `jsonencode() function`. + + For example, if your original task definition looked like: + + ```hcl + resource "aws_ecs_task_definition" "my_task" { + ... + container_definitions = jsonencode( + [ + { + name = "example-client-app" + image = "docker.io/org/my_task:v0.0.1" + essential = true + ... + } + ] + ) + } + ``` + + Then remove the `jsonencode()` function and use the rest of the value + as the input for the `mesh-task` module: + + ```hcl + module "my_task" { + source = "hashicorp/consul/aws-ecs//modules/mesh-task" + version = "" + + ... + container_definitions = [ + { + name = "example-client-app" + image = "docker.io/org/my_task:v0.0.1" + essential = true + ... + } + ] + } + ``` + +- `port` is the port that your application listens on. This should be set to a + string, not an integer, i.e. `port = "9090"`, not `port = 9090`. +- `retry_join` is passed to the `-retry-join` option for the Consul agent. This tells + the agent the location of your Consul server so that it can join the Consul cluster. + +The `mesh-task` module will create a new version of your task definition with the +necessary sidecar containers added so you can delete your existing `aws_ecs_task_definition` +resource. + +Your `aws_ecs_service` resource can remain unchanged except for the `task_definition` +input which should reference the new module's output of the task definition's ARN: + +```hcl +resource "aws_ecs_service" "my_task" { + ... + task_definition = module.my_task.task_definition_arn +} +``` + +-> **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. + +After running `terraform apply`, you should see your tasks registered in +the Consul UI. + +## Complete Installation + +Now that your task(s) are migrated to the `mesh-task` module, see the [Install Guide](/docs/ecs/get-started/install) to install Consul on ECS. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 15838d9da..145188877 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -576,6 +576,10 @@ { "title": "Install", "path": "ecs/get-started/install" + }, + { + "title": "Migrate Existing Tasks", + "path": "ecs/get-started/migrate-existing-tasks" } ] }, From f2d800c5335d0aaf50e0e6a422af8fb39bb96fbf Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 17:02:29 -0500 Subject: [PATCH 10/16] docs: update ECS Install guide for beta --- .../content/docs/ecs/get-started/install.mdx | 159 ++++-------------- .../get-started/migrate-existing-tasks.mdx | 95 ++--------- website/data/docs-nav-data.json | 2 +- 3 files changed, 47 insertions(+), 209 deletions(-) diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx index 82116d585..d74498e7b 100644 --- a/website/content/docs/ecs/get-started/install.mdx +++ b/website/content/docs/ecs/get-started/install.mdx @@ -1,94 +1,40 @@ --- layout: docs -page_title: Install - AWS ECS +page_title: Installation - AWS ECS description: >- Install Consul Service Mesh on AWS ECS (Elastic Container Service). --- -# Install +# Installation Installing Consul on ECS is a multi-part process: -1. [**Terraform:**](#terraform) Your tasks must be specified in Terraform using [`ecs_task_definition`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition) - and [`ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) resources. -1. [**Task Module:**](#task-module) You can then take your `ecs_task_definition` resources and copy their configuration into a new [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) - resource that will add the necessary containers to the task definition. +1. [**Task Module:**](#task-module) Define the [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) + to create a task definition with the necessary sidecar containers for your application to join the service mesh. 1. [**Routing:**](#routing) With your tasks as part of the mesh, you must specify their upstream - services and change the URLs the tasks are using so that they're making requests - through the service mesh. + services and change the URLs the tasks are using so that they're making requests through the service mesh. 1. [**Bind Address:**](#bind-address) Now that all communication is flowing through the service mesh, you should change the address your application is listening on to `127.0.0.1` so that it only receives requests through the sidecar proxy. -> **NOTE:** This page assumes you're familiar with ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for more details. -## Terraform - -Your tasks must first be specified in Terraform using [`ecs_task_definition`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition) -and [`ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) resources so that -they can later be converted to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). - -For example, your tasks should be defined with Terraform similar to the following: - -```hcl -resource "aws_ecs_task_definition" "my_task" { - family = "my_task" - requires_compatibilities = ["FARGATE"] - network_mode = "awsvpc" - cpu = 256 - memory = 512 - container_definitions = jsonencode( - [{ - name = "example-client-app" - image = "docker.io/org/my_task:v0.0.1" - essential = true - portMappings = [ - { - containerPort = 9090 - hostPort = 9090 - protocol = "tcp" - } - ] - cpu = 0 - mountPoints = [] - volumesFrom = [] - }] - ) -} - -resource "aws_ecs_service" "my_task" { - name = "my_task" - cluster = "arn:aws:ecs:us-east-1:111111111111:cluster/my-cluster" - task_definition = aws_ecs_task_definition.my_task.arn - desired_count = 1 - network_configuration { - subnets = ["subnet-abc123"] - } - launch_type = "FARGATE" -} -``` - ## Task Module In order to add the necessary sidecar containers for your task to join the mesh, -you must use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). - -The module will reference the same inputs as your old ECS task definition but it will -create a new version of the task definition with additional containers. - -The `mesh-task` module is used as follows: +you must use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task): ```hcl module "my_task" { source = "hashicorp/consul/aws-ecs//modules/mesh-task" version = "" - family = "my_task" + family = "my_task" container_definitions = [ { - name = "example-client-app" - image = "docker.io/org/my_task:v0.0.1" - essential = true + name = "example-client-app" + image = "docker.io/org/my_task:v0.0.1" + essential = true portMappings = [ { containerPort = 9090 @@ -102,71 +48,25 @@ module "my_task" { } ] - port = "9090" + port = "9090" retry_join = "
" } ``` -All possible inputs are documented on the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) +All possible inputs are documented on the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs), however there are some important inputs worth highlighting: - `family` is used as the [task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family) but it's also used as the name of the service that gets registered in Consul. - `container_definitions` accepts an array of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions). - These are your application containers and this should be set to the same value as what you - were passing into the `container_definitions` key in the `aws_ecs_task_definition` resource - without the `jsonencode() function`. - - For example, if your original task definition looked like: - - ```hcl - resource "aws_ecs_task_definition" "my_task" { - ... - container_definitions = jsonencode( - [ - { - name = "example-client-app" - image = "docker.io/org/my_task:v0.0.1" - essential = true - ... - } - ] - ) - } - ``` - - Then you would remove the `jsonencode()` function and use the rest of the value - as the input for the `mesh-task` module: - - ```hcl - module "my_task" { - source = "hashicorp/consul/aws-ecs//modules/mesh-task" - version = "" - - ... - container_definitions = [ - { - name = "example-client-app" - image = "docker.io/org/my_task:v0.0.1" - essential = true - ... - } - ] - } - ``` - + This is where you include application containers. - `port` is the port that your application listens on. This should be set to a string, not an integer, i.e. `port = "9090"`, not `port = 9090`. -- `consul_server_service_name` should be set to the name of the ECS service for - the Consul dev server. This is an output of the `dev-server` module so it - can be referenced, e.g. `consul_server_service_name = module.dev_consul_server.ecs_service_name`. +- `retry_join` is passed to the `-retry-join` option for the Consul agent. This tells + the agent the location of your Consul server so that it can join the Consul cluster. -The `mesh-task` module will create a new version of your task definition with the -necessary sidecar containers added so you can delete your existing `aws_ecs_task_definition` -resource. - -Your `aws_ecs_service` resource can remain unchanged except for the `task_definition` -input which should reference the new module's output of the task definition's ARN: +To define an ECS service, reference the mesh-task module's `task_definition_arn` output value +in your `aws_ecs_service` resource: ```hcl resource "aws_ecs_service" "my_task" { @@ -191,10 +91,10 @@ proxy to listen on a different port for each upstream service your application needs to call. You then must modify your application to make requests to the sidecar proxy on that port. -For example, say my application `web` wants to make calls to my other application +For example, say your application `web` wants to make calls to my other application `backend`. -First, I must configure the `mesh-task` module's upstreams: +First, you must configure the `mesh-task` module's upstream(s): ```hcl module "web" { @@ -208,19 +108,19 @@ module "web" { } ``` -I set the `destination_name` to the name of the upstream service (in this case `backend`), -and I set `local_bind_port` to an unused port. This is the port that the sidecar proxy -will listen on and any requests to this port will be forwarded over to the `destination_name`. -This does not have to be the port that `backend` is listening on because the service mesh -will handle routing the request to the right port. +- Set the `destination_name` to the name of the upstream service (in this case `backend`) +- Set `local_bind_port` to an unused port. This is the port that the sidecar proxy + will listen on. Any requests to this port will be forwarded over to the `destination_name`. + This does not have to be the port that `backend` is listening on because the service mesh + will handle routing the request to the right port. -If you have multiple upstream services they'll each need to be listed here. +If you have multiple upstream services they each need to be listed here. -Next, I must configure my application to make requests to `localhost:8080` when +Next, configure your application to make requests to `localhost:8080` when it wants to call the `backend` service. -For example, if my service allows configuring the URL for `backend` via the -`BACKEND_URL` environment variable, I would set: +For example, if your service allows configuring the URL for `backend` via the +`BACKEND_URL` environment variable, you would set: ```hcl module "web" { @@ -251,7 +151,7 @@ module "web" { 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`) +(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. If your application is listening on all interfaces, e.g. `0.0.0.0`, then other @@ -279,6 +179,7 @@ python manage.py runserver "127.0.0.1:8080" ## Next Steps +- Configure a secure [Production Installation](TODO-LINK). - Now that your applications are running in the service mesh, read about other [Service Mesh features](/docs/connect). - View the [Architecture](/docs/ecs/architecture) documentation to understand diff --git a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx b/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx index b5ee18868..a5f59d5fa 100644 --- a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx +++ b/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx @@ -11,9 +11,8 @@ This guide explains how to migrate your existing ECS Tasks to use our [`mesh-tas ## Define Tasks in Terraform -Your tasks must first be specified in Terraform using [`ecs_task_definition`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition) -and [`ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) resources so that -they can later be converted to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). +Your tasks must first be specified in Terraform using the [`ecs_task_definition`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition) +resource so that they can then be converted to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). For example, your tasks should be defined with Terraform similar to the following: @@ -57,7 +56,7 @@ resource "aws_ecs_service" "my_task" { } ``` -## Convert Tasks to Mesh Module +## Convert to the `mesh-task` Module In order to add the necessary sidecar containers for your task to join the mesh, you must use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). @@ -72,12 +71,12 @@ module "my_task" { source = "hashicorp/consul/aws-ecs//modules/mesh-task" version = "" - family = "my_task" + family = "my_task" container_definitions = [ { - name = "example-client-app" - image = "docker.io/org/my_task:v0.0.1" - essential = true + name = "example-client-app" + image = "docker.io/org/my_task:v0.0.1" + essential = true portMappings = [ { containerPort = 9090 @@ -91,83 +90,21 @@ module "my_task" { } ] - port = "9090" - retry_join = "
" + port = "9090" + retry_join = "
" } ``` -All possible inputs are documented on the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) -however there are some important inputs worth highlighting: +The main differences are: -- You do not need the `execution_role_arn` or `task_role_arn` fields. The `mesh-task` module will create the task and execution roles. -- `family` is used as the [task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family) and the name of the service that is registered in Consul. -- `container_definitions` accepts an array of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions). - These are your application containers and are the same as `container_definitions` key in the - `aws_ecs_task_definition` resource without the `jsonencode() function`. - - For example, if your original task definition looked like: - - ```hcl - resource "aws_ecs_task_definition" "my_task" { - ... - container_definitions = jsonencode( - [ - { - name = "example-client-app" - image = "docker.io/org/my_task:v0.0.1" - essential = true - ... - } - ] - ) - } - ``` - - Then remove the `jsonencode()` function and use the rest of the value - as the input for the `mesh-task` module: - - ```hcl - module "my_task" { - source = "hashicorp/consul/aws-ecs//modules/mesh-task" - version = "" - - ... - container_definitions = [ - { - name = "example-client-app" - image = "docker.io/org/my_task:v0.0.1" - essential = true - ... - } - ] - } - ``` - -- `port` is the port that your application listens on. This should be set to a - string, not an integer, i.e. `port = "9090"`, not `port = 9090`. -- `retry_join` is passed to the `-retry-join` option for the Consul agent. This tells - the agent the location of your Consul server so that it can join the Consul cluster. +- You must remove the `execution_role_arn` and `task_role_arn` fields. The `mesh-task` module will create the task and execution roles. +- You must add the `port` field. This is the port that your application listens on. +- You must add the `retry_join` field. This specifies the location of your Consul servers so that your task can join the mesh. +- You must remove the `jsonencode()` function from the `container_definitions` field. The `mesh-task` module will create a new version of your task definition with the necessary sidecar containers added so you can delete your existing `aws_ecs_task_definition` resource. -Your `aws_ecs_service` resource can remain unchanged except for the `task_definition` -input which should reference the new module's output of the task definition's ARN: - -```hcl -resource "aws_ecs_service" "my_task" { - ... - task_definition = module.my_task.task_definition_arn -} -``` - --> **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. - -After running `terraform apply`, you should see your tasks registered in -the Consul UI. - -## Complete Installation - -Now that your task(s) are migrated to the `mesh-task` module, see the [Install Guide](/docs/ecs/get-started/install) to install Consul on ECS. +Now that your task(s) are migrated to the `mesh-task` module, see the [Installation Guide](/docs/ecs/get-started/install) to continue installing +Consul on ECS. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 145188877..57f9fb891 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -574,7 +574,7 @@ "path": "ecs/get-started/requirements" }, { - "title": "Install", + "title": "Installation", "path": "ecs/get-started/install" }, { From 3ca995cf8fcb6d66d508e46836978e1f69196f0c Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 17:27:03 -0500 Subject: [PATCH 11/16] docs: Update ECS sidebar with links to Fargate/EC2 examples --- website/data/docs-nav-data.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 57f9fb891..7f4f7f68f 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -566,9 +566,13 @@ "title": "Get Started", "routes": [ { - "title": "Example Installation", + "title": "Example Installation on ECS Fargate", "href": "https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate" }, + { + "title": "Example Installation on ECS EC2", + "href": "https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2" + }, { "title": "Requirements", "path": "ecs/get-started/requirements" From fc460c0a8d9f81a9579299a2982e90f190d91449 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Thu, 16 Sep 2021 10:19:15 -0500 Subject: [PATCH 12/16] docs: Apply suggestions from code review Co-authored-by: Luke Kysow <1034429+lkysow@users.noreply.github.com> Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/ecs/get-started/install.mdx | 5 ++--- .../content/docs/ecs/get-started/migrate-existing-tasks.mdx | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx index d74498e7b..45b1bd078 100644 --- a/website/content/docs/ecs/get-started/install.mdx +++ b/website/content/docs/ecs/get-started/install.mdx @@ -62,7 +62,7 @@ however there are some important inputs worth highlighting: This is where you include application containers. - `port` is the port that your application listens on. This should be set to a string, not an integer, i.e. `port = "9090"`, not `port = 9090`. -- `retry_join` is passed to the `-retry-join` option for the Consul agent. This tells +- `retry_join` is passed to the [`-retry-join`](/docs/agent/options#_retry_join) option for the Consul agent. This tells the agent the location of your Consul server so that it can join the Consul cluster. To define an ECS service, reference the mesh-task module's `task_definition_arn` output value @@ -91,10 +91,9 @@ proxy to listen on a different port for each upstream service your application needs to call. You then must modify your application to make requests to the sidecar proxy on that port. -For example, say your application `web` wants to make calls to my other application +For example, if your application `web` makes calls to another application called `backend`, then you would first configure the `mesh-task` module's upstream(s): `backend`. -First, you must configure the `mesh-task` module's upstream(s): ```hcl module "web" { diff --git a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx b/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx index a5f59d5fa..b6378e3f5 100644 --- a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx +++ b/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx @@ -7,7 +7,7 @@ description: >- # Migrate Existing Tasks -This guide explains how to migrate your existing ECS Tasks to use our [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). +This topic describes how to migrate your existing ECS Tasks to use our [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task). ## Define Tasks in Terraform From fd2a3f3305192b11c68108c5f216a0054d4e6a3d Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Thu, 16 Sep 2021 10:39:37 -0500 Subject: [PATCH 13/16] docs: adjust references between ECS "migrate" and "install" pages --- website/content/docs/ecs/get-started/install.mdx | 13 +++++++------ .../docs/ecs/get-started/migrate-existing-tasks.mdx | 11 ++++++++--- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx index 45b1bd078..39ad89595 100644 --- a/website/content/docs/ecs/get-started/install.mdx +++ b/website/content/docs/ecs/get-started/install.mdx @@ -65,7 +65,12 @@ however there are some important inputs worth highlighting: - `retry_join` is passed to the [`-retry-join`](/docs/agent/options#_retry_join) option for the Consul agent. This tells the agent the location of your Consul server so that it can join the Consul cluster. -To define an ECS service, reference the mesh-task module's `task_definition_arn` output value +-> **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. + +## ECS Service + +To define an ECS Service, reference the mesh-task module's `task_definition_arn` output value in your `aws_ecs_service` resource: ```hcl @@ -75,9 +80,6 @@ resource "aws_ecs_service" "my_task" { } ``` --> **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. - After running `terraform apply`, you should see your tasks registered in the Consul UI. @@ -94,7 +96,6 @@ proxy on that port. For example, if your application `web` makes calls to another application called `backend`, then you would first configure the `mesh-task` module's upstream(s): `backend`. - ```hcl module "web" { family = "web" @@ -178,7 +179,7 @@ python manage.py runserver "127.0.0.1:8080" ## Next Steps -- Configure a secure [Production Installation](TODO-LINK). +- Configure a secure [Production Installation](/docs/ecs/production-installation). - Now that your applications are running in the service mesh, read about other [Service Mesh features](/docs/connect). - View the [Architecture](/docs/ecs/architecture) documentation to understand diff --git a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx b/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx index b6378e3f5..717cbed9c 100644 --- a/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx +++ b/website/content/docs/ecs/get-started/migrate-existing-tasks.mdx @@ -98,7 +98,8 @@ module "my_task" { The main differences are: - You must remove the `execution_role_arn` and `task_role_arn` fields. The `mesh-task` module will create the task and execution roles. -- You must add the `port` field. This is the port that your application listens on. +- You must set the `port` field to the port that your application listens on. + If your application has no listening port, set `outbound_only = true` and remove the `port` field. - You must add the `retry_join` field. This specifies the location of your Consul servers so that your task can join the mesh. - You must remove the `jsonencode()` function from the `container_definitions` field. @@ -106,5 +107,9 @@ The `mesh-task` module will create a new version of your task definition with th necessary sidecar containers added so you can delete your existing `aws_ecs_task_definition` resource. -Now that your task(s) are migrated to the `mesh-task` module, see the [Installation Guide](/docs/ecs/get-started/install) to continue installing -Consul on ECS. +## Next Steps + +Now that your task(s) are migrated to the `mesh-task` module, + +- Start at the [ECS Service section](/docs/ecs/get-started/install#ecs-service) of the Installation Guide to continue installing Consul on ECS. +- Refer to the [`mesh-task` reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for all available inputs to your mesh tasks. From e84c429be16ec7a913600efec2f37fd21da61b9f Mon Sep 17 00:00:00 2001 From: Luke Kysow <1034429+lkysow@users.noreply.github.com> Date: Thu, 16 Sep 2021 09:17:01 -0700 Subject: [PATCH 14/16] Update ecs docs (#11053) --- website/content/docs/ecs/get-started/requirements.mdx | 4 ++-- website/content/docs/ecs/index.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/content/docs/ecs/get-started/requirements.mdx b/website/content/docs/ecs/get-started/requirements.mdx index f063e2012..1c4d0488d 100644 --- a/website/content/docs/ecs/get-started/requirements.mdx +++ b/website/content/docs/ecs/get-started/requirements.mdx @@ -12,5 +12,5 @@ The following requirements must be met in order to install Consul on ECS: 1. **Terraform:** The tasks that you want to add to the service mesh must first be modeled in Terraform. 1. **Launch Type:** Fargate and EC2 launch types are supported. 1. **Subnets:** ECS Tasks can run in private or public subnets. Tasks must have [network access](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-api-error-ecr/) to Amazon ECR or other public container registries to pull images. -1. **Consul Servers:** You can use your own Consul servers (VM) or use HCP Consul. For development purposes or testing, you may use the `dev-server` [Terraform module](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main). The `dev-server` does not support persistent storage. -1. **ACL Controller:** If you are running a secure Consul installation, configure the ACL controller. +1. **Consul Servers:** You can use your own Consul servers running on virtual machines or use [HashiCorp Cloud Platform Consul](https://www.hashicorp.com/cloud-platform) to host the servers for you. For development purposes or testing, you may use the `dev-server` [Terraform module](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main) that runs the Consul server as an ECS task. The `dev-server` does not support persistent storage. +1. **ACL Controller:** If you are running a secure Consul installation with ACLs enabled, configure the ACL controller. diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx index 67c20c589..ee1078477 100644 --- a/website/content/docs/ecs/index.mdx +++ b/website/content/docs/ecs/index.mdx @@ -9,7 +9,7 @@ description: >- # AWS ECS -> **Beta:** This functionality is currently in beta and is -not recommended for use in production environments. Refer to the [consul-ecs-project road map](https://github.com/hashicorp/consul-ecs/projects/1) for information about upcoming features and enhancements. +not recommended for use in production environments. Refer to the [consul-ecs project road map](https://github.com/hashicorp/consul-ecs/projects/1) for information about upcoming features and enhancements. Consul can be deployed on [AWS ECS](https://aws.amazon.com/ecs/) (Elastic Container Service) using our official Terraform modules. From a39b58622b29a435624025003e05aae677b44574 Mon Sep 17 00:00:00 2001 From: Iryna Shustava Date: Thu, 16 Sep 2021 10:28:05 -0600 Subject: [PATCH 15/16] docs: Add production installation ECS docs (#11049) Co-authored-by: Paul Glass Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../get-started/production-installation.mdx | 109 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 2 files changed, 113 insertions(+) create mode 100644 website/content/docs/ecs/get-started/production-installation.mdx diff --git a/website/content/docs/ecs/get-started/production-installation.mdx b/website/content/docs/ecs/get-started/production-installation.mdx new file mode 100644 index 000000000..2e3306c00 --- /dev/null +++ b/website/content/docs/ecs/get-started/production-installation.mdx @@ -0,0 +1,109 @@ +--- +layout: docs +page_title: Production Installation - AWS ECS +description: >- + Production Installation of the Consul Service Mesh on AWS ECS (Elastic Container Service). +--- + +# Production Installation + +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:** This page assumes that you have already configured your Consul server with the above features. + +## Deploy 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). + +To deploy the controller, you will first need store an ACL token with `acl:write` privileges +and a CA certificate for the Consul server in AWS Secrets Manager. + +```hcl +resource "aws_secretsmanager_secret" "bootstrap_token" { + name = "bootstrap-token" +} + +resource "aws_secretsmanager_secret_version" "bootstrap_token" { + secret_id = aws_secretsmanager_secret.bootstrap_token.id + secret_string = "" +} + +resource "aws_secretsmanager_secret" "ca_cert" { + name = "server-ca-cert" +} + +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" +} +``` + +The `name_prefix` parameter is used to prefix any secrets that the ACL controller will +update in AWS Secrets Manager. + +-> **NOTE:** Make sure that the `name_prefix` is unique for each ECS cluster where you are +deploying this controller. + +## Deploy Services + +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/get-started/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 +should use. + +```hcl +resource "aws_secretsmanager_secret" "gossip_key" { + name = "gossip-encryption-key" +} + +resource "aws_secretsmanager_secret_version" "gossip_key" { + secret_id = aws_secretsmanager_secret.gossip_key.id + secret_string = "" +} +``` + +Next, add the following configurations to enable secure deployment. Note that the `acl_secret_name_prefix` +should be the same as the `name_prefix` you provide to the ACL controller module. + +```hcl +module "my_task" { + source = "hashicorp/consul/aws-ecs//modules/mesh-task" + family = "my_task" + + ... + + tls = true + consul_server_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn + gossip_key_secret_arn = aws_secretsmanager_secret.gossip_key.arn + + acls = true + consul_client_token_secret_arn = module.acl_controller.client_token_secret_arn + acl_secret_name_prefix = "consul-ecs" +} +``` + +Now you can deploy your services! Follow the rest of the steps in the [Installation instructions](/docs/ecs/get-started/install#task-module) +to deploy and connect your services. + diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 15838d9da..92b37e87c 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -576,6 +576,10 @@ { "title": "Install", "path": "ecs/get-started/install" + }, + { + "title": "Production Installation", + "path": "ecs/get-started/production-installation" } ] }, From 4d87fc14e74b7753b6b7b29167c7003e4c6d5099 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Thu, 16 Sep 2021 12:30:08 -0500 Subject: [PATCH 16/16] docs: correct link to ecs production installation --- website/content/docs/ecs/get-started/install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/ecs/get-started/install.mdx b/website/content/docs/ecs/get-started/install.mdx index 39ad89595..ea8c13a0e 100644 --- a/website/content/docs/ecs/get-started/install.mdx +++ b/website/content/docs/ecs/get-started/install.mdx @@ -179,7 +179,7 @@ python manage.py runserver "127.0.0.1:8080" ## Next Steps -- Configure a secure [Production Installation](/docs/ecs/production-installation). +- Configure a secure [Production Installation](/docs/ecs/get-started/production-installation). - Now that your applications are running in the service mesh, read about other [Service Mesh features](/docs/connect). - View the [Architecture](/docs/ecs/architecture) documentation to understand