From 13c6973e47452917b72cde2e40d35642737342b4 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 16:10:04 -0500 Subject: [PATCH 1/6] 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 0000000000..b5ee18868e --- /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 15838d9da8..1451888777 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 2c9fbc2bff330a7bd629aa3f6de7ccc659620309 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 17:02:29 -0500 Subject: [PATCH 2/6] 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 82116d5855..d74498e7b9 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`. - -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. +- `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. -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 b5ee18868e..a5f59d5fab 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: - -- 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 - ... - } - ] - } - ``` +The main differences are: -- `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 1451888777..57f9fb8910 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 bbbf58fa95aad33ebe5d576de7ce0c4bf46a047f Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 15 Sep 2021 17:27:03 -0500 Subject: [PATCH 3/6] 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 57f9fb8910..7f4f7f68f0 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 01dfbedcf3d1c25576224e18f37059ab80003369 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Thu, 16 Sep 2021 10:19:15 -0500 Subject: [PATCH 4/6] 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 d74498e7b9..45b1bd0780 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 a5f59d5fab..b6378e3f5c 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 392919ae6122c1273150a8fc2712c358c3ec76f5 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Thu, 16 Sep 2021 10:39:37 -0500 Subject: [PATCH 5/6] 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 45b1bd0780..39ad895956 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 b6378e3f5c..717cbed9c3 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 930e3824dfc892c07fc644784f4986a92c3336f9 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Thu, 16 Sep 2021 12:30:08 -0500 Subject: [PATCH 6/6] 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 39ad895956..ea8c13a0e3 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