mirror of https://github.com/status-im/consul.git
docs: Refine ECS installation docs
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
This commit is contained in:
Paul Glass
parent
296fbaf5b1
commit
5ccc1fdcca
|
|
@ -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`:
|
||||
|
||||
<CodeBlockConfig filename="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:
|
||||
</CodeBlockConfig>
|
||||
|
||||
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.
|
||||
|
||||
<CodeBlockConfig filename="provider.tf">
|
||||
|
||||
```hcl
|
||||
terraform {
|
||||
required_providers {
|
||||
aws = {
|
||||
source = "hashicorp/aws"
|
||||
version = "<latest version>"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "aws" {
|
||||
region = "<AWS region>"
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
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.
|
||||
|
||||
<CodeBlockConfig filename="mesh-task.tf" highlight="6-12">
|
||||
|
||||
```hcl
|
||||
module "my_task" {
|
||||
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
|
||||
...
|
||||
}
|
||||
|
||||
resource "aws_ecs_service" "my_task" {
|
||||
name = "my_task_service"
|
||||
task_definition = module.my_task.task_definition_arn
|
||||
|
|
@ -83,6 +154,8 @@ resource "aws_ecs_service" "my_task" {
|
|||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
This is a partial configuration to highlight some important fields.
|
||||
See the [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) documentation for a complete reference.
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
|||
|
||||
</CodeBlockConfig>
|
||||
|
||||
| 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. |
|
||||
|
|
|
|||
Loading…
Reference in New Issue