From 5ccc1fdcca835945886f5ee02ba5ece73294b1d1 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Tue, 25 Jan 2022 12:24:37 -0600 Subject: [PATCH] docs: Refine ECS installation docs Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/ecs/install.mdx | 95 ++++++++++++++++--- .../content/docs/ecs/manual-installation.mdx | 27 +++--- 2 files changed, 98 insertions(+), 24 deletions(-) diff --git a/website/content/docs/ecs/install.mdx b/website/content/docs/ecs/install.mdx index dc35b53efe..ce51332b59 100644 --- a/website/content/docs/ecs/install.mdx +++ b/website/content/docs/ecs/install.mdx @@ -11,6 +11,17 @@ This topic describes how to use the [`mesh-task`](https://registry.terraform.io/ This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples. +## Overview + +This topic describes the following procedure: + +1. Create Terraform configuration files for the necessary components: + + * [ECS task definition](#using-the-mesh-task-module): Use the `mesh-task` module to create an ECS task definition for Consul on ECS + * [ECS service](#ecs-service): Use the `aws_ecs_service` resource to create an ECS service that schedules service mesh tasks to run on ECS + +2. [Run Terraform](#running-terraform) to deploy the resources in AWS + ## Prerequisites * You should have some familiarity with using Terraform. Refer to the [Terraform documentation](https://www.terraform.io/docs) to learn about infrastructure as code and how to get started with Terraform. @@ -23,7 +34,9 @@ and additional sidecar containers, such as the Consul agent container and the En The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) will automatically include the necessary sidecar containers. -The following example shows a Terraform configuration file that creates a task definition with an application container called `example-client-app`. +The following example shows a Terraform configuration file that creates a task definition with an application container called `example-client-app` in a file called `mesh-task.tf`: + + ```hcl module "my_task" { @@ -54,26 +67,84 @@ module "my_task" { } ``` -All possible inputs are documented in 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 following fields are required. Refer to the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for a complete reference. | Input Variable | Type | Description | | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `source` and `version` | string | This specifies the source location and version of the `mesh-task` module. | +| `source` | string | Must be set to the source location of the `mesh-task` module, `hashicorp/consul-ecs/aws//modules/mesh-task`. | +| `version` | string | Must be set to the version of the `mesh-task` module. | | `family` | string | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default. | | `container_definitions` | list | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. | | `port` | integer | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`. | | `retry_join` | list | The is the [`retry_join`](/docs/agent/options#_retry_join) option for the Consul agent, which specifies the locations of your Consul servers. | +### Running Terraform + +You will need to run Terraform to create the task definition. + +Save the Terraform configuration for the task definition to a file, such as `mesh-task.tf`. +You should place this file in a directory alongside other Terraform configuration files for your project. + +The `mesh-task` module requires the AWS Terraform provider. The following example shows how to include +and configure the AWS provider in a file called `provider.tf`. Refer to the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) +documentation for complete configuration details. + + + +```hcl +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = "" + } + } +} + +provider "aws" { + region = "" + ... +} +``` + + + +Additional AWS resources for your project can be included in additional Terraform configuration files +in the same directory. The following example shows a basic project directory: + +```shell-session +$ ls +mesh-task.tf +provider.tf +... +``` + +Terraform should be run in your project directory as follows. + +* Run `terraform init` first to download dependencies, such as Terraform providers +* Run `terraform apply` to have Terraform create AWS resources, such as the task definition from the `mesh-task` module. + +Terraform automatically reads all files in the current directory that have a `.tf` file extension. +Refer to the [Terraform documentation](https://www.terraform.io/docs) for more information and Terraform best practices. + ## ECS Service [ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common -ways to start tasks using a task definition.. +ways to start tasks using a task definition. -To define an ECS Service, reference the mesh-task module's `task_definition_arn` output value -in your `aws_ecs_service` resource: +To define an ECS service, reference the `mesh-task` module's `task_definition_arn` output value +in your `aws_ecs_service` resource. The following example shows how to include the service in the `mesh-task.tf` file. + + ```hcl +module "my_task" { + source = "hashicorp/consul-ecs/aws//modules/mesh-task" + ... +} + resource "aws_ecs_service" "my_task" { name = "my_task_service" task_definition = module.my_task.task_definition_arn @@ -83,6 +154,8 @@ resource "aws_ecs_service" "my_task" { } ``` + + This is a partial configuration to highlight some important fields. See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) documentation for a complete reference. @@ -93,10 +166,10 @@ See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aw | `launch_type` | string | The launch type. Consul on ECS supports the `FARGATE` and `EC2` launch types. | | `propagate_tags` | string | This must be set to `TASK_DEFINITION` so that tags added by `mesh-task` to the task definition are copied to tasks. | -After defining the Terraform configuration for both the `mesh-task` and ECS service, -run `terraform apply` to create the ECS task definition and service resources. The ECS -service will soon start your application in a task. The task will automatically -register itself into the Consul service catalog. +After including the ECS service in your Terraform configuration, run `terraform apply` +from your project directory to create the ECS service resource. The ECS service will +soon start your application in a task. The task will automatically register itself +into the Consul service catalog during startup. -> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true` in their [`network_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service#network_configuration) block so that ECS can pull the Docker images. diff --git a/website/content/docs/ecs/manual-installation.mdx b/website/content/docs/ecs/manual-installation.mdx index 56ca858271..31e57eac3f 100644 --- a/website/content/docs/ecs/manual-installation.mdx +++ b/website/content/docs/ecs/manual-installation.mdx @@ -52,10 +52,10 @@ during task startup. | Field name | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | -| `family` | string | The task family name. This is used as the Consul service name by default. | +| `family` | string | The task family name. This is used as the Consul service name by default. | | `networkMode` | string | Must be `awsvpc`, which is the only network mode supported by Consul on ECS. | -| `volumes` | list | Must be defined as shown above. Volumes are used to share configuration between containers for intial task setup. | -| `containerDefinitions` | list | The list of containers to run in this task (see below). | +| `volumes` | list | Must be defined as shown above. Volumes are used to share configuration between containers for intial task setup. | +| `containerDefinitions` | list | The list of containers to run in this task (see [Application container](#application-container)). | ## Application container @@ -218,16 +218,17 @@ Each task must include a Consul client container in order for the task to join y -| Field name | Type | Description | -| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | -| `name` | string | The container name, which should always be `consul-client`. | -| `image` | string | The Consul image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits. | -| `mountPoints` | list | Must be set as shown above. Volumes are mounted to share information with other containers for task setup. | -| `entrypoint` | list | Must be set to a plain shell so that the startup `command` works properly. | -| `command` | list | The startup command. See below for details. | +| Field name | Type | Description | +| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `name` | string | The container name, which should always be `consul-client`. | +| `image` | string | The Consul image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits. | +| `mountPoints` | list | Must be set as shown above. Volumes are mounted to share information with other containers for task setup. | +| `entrypoint` | list | Must be set to a plain shell so that the startup `command` works properly. | +| `command` | list | Specifies the contents of the [startup script](#consul-client-startup-script). Copy the script and format it into a JSON string. | -The following is the recommended `command` script for the Consul agent. -This is the same as the above `command` field, but is unescaped and has comments added. +### Consul client startup script + +The following script is used to start the Consul client for Consul on ECS. ```shell # Copy the consul binary to a shared volume for `consul-ecs-mesh-init` to use to generate Envoy configuration. @@ -271,7 +272,7 @@ The following table describes the values that you should use to configure the `c | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `addresses.*` | strings | Set the DNS, GRPC, and HTTP addresses to `127.0.0.1` to ensure these are not accessible outside of the task. | | `advertise_addr` | string | Must be set to the task IP address so that other Consul agents know how to reach this agent. | -| `client_addr` | string | Must be set to an interface reacable by other Consul agents. | +| `client_addr` | string | Must be set to an interface reachable by other Consul agents. | | `datacenter` | string | Must be set to the Consul datacenter this task will join. | | `leave_on_terminate` | boolean | Must be set to `true` so that the Consul agent leaves the cluster gracefully before exiting. | | `retry_join` | string | Must be set to your Consul server location(s) so this agent can join the Consul cluster. |