docs: Apply suggestions to ECS docs from code review
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
This commit is contained in:
Paul Glass
parent
35b37345be
commit
69de9c4d2e
|
|
@ -1,15 +1,17 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Installation with Terraform - AWS ECS
|
||||
page_title: Installing Consul on AWS ECS using Terraform
|
||||
description: >-
|
||||
Install Consul Service Mesh on AWS ECS with Terraform (Elastic Container Service).
|
||||
---
|
||||
|
||||
# Installation with Terraform
|
||||
|
||||
This will describe how to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) Terraform module to launch your application in AWS ECS as part of Consul service mesh.
|
||||
This topic describes how to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) Terraform module to launch your application in AWS ECS as part of Consul service mesh.
|
||||
|
||||
## Pre-requisites
|
||||
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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* This pages assumes you are familiar with Terraform. If you are new to Terraform, see the [Terraform documentation](https://www.terraform.io/docs) to
|
||||
learn about infrastructure as code and how to get started with Terraform.
|
||||
|
|
@ -24,7 +26,7 @@ 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.
|
||||
|
||||
Here is an example Terraform configuration file which defines a task definition with an application container called `example-client-app`.
|
||||
The following example shows a Terraform configuration file that defines a task definition with an application container called `example-client-app`.
|
||||
|
||||
```hcl
|
||||
module "my_task" {
|
||||
|
|
@ -61,7 +63,7 @@ however there are some important inputs worth highlighting:
|
|||
| Input Variable | Type | Description |
|
||||
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `source` and `version` | string | This specifies the source location and 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. |
|
||||
| `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` | number | 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. |
|
||||
|
|
|
|||
|
|
@ -7,19 +7,17 @@ description: >-
|
|||
|
||||
# Manual Installation
|
||||
|
||||
While the [Consul ECS Terraform module](/docs/ecs/install) is the easiest way to use Consul on ECS,
|
||||
this page will describe how to directly create the ECS task definition using the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs)
|
||||
for use without Terraform.
|
||||
This topic describes how to manually create the ECS task definition for use without Terraform from the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs). Refer to the [Consul ECS Terraform module](/docs/ecs/install) documentation for an alternative method for installing Consul on ECS.
|
||||
|
||||
## Pre-requisites
|
||||
This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples.
|
||||
|
||||
* This page assumes you are familiar with AWS ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for more details.
|
||||
* This page does not show how to create all necessary AWS resources, such as a VPC or the ECS Cluster.
|
||||
For complete runnable examples, see the links in the [Getting Started](/docs/ecs#getting-started) section.
|
||||
## Prerequisites
|
||||
|
||||
You should have some familiarity with AWS ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details.
|
||||
|
||||
## Task Definition
|
||||
|
||||
You must define a Task Definition which includes the following containers:
|
||||
You must define a task definition which includes the following containers:
|
||||
|
||||
* Your application container
|
||||
* An Envoy sidecar-proxy container
|
||||
|
|
@ -29,7 +27,7 @@ You must define a Task Definition which includes the following containers:
|
|||
|
||||
## Top-level fields
|
||||
|
||||
In your task definition, you'll need to define these important top-level fields:
|
||||
Your task definition must include the following top-level fields:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -49,9 +47,9 @@ In your task definition, you'll need to define these important top-level fields:
|
|||
|
||||
| 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 ares used to share configuration between containers for intial task setup. |
|
||||
| `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). |
|
||||
|
||||
## Application container
|
||||
|
|
@ -95,7 +93,7 @@ See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/devel
|
|||
|
||||
## `sidecar-proxy` container
|
||||
|
||||
The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for Consul Connect.
|
||||
The `sidecar-proxy` container runs [Envoy proxy](/docs/connect/proxies/envoy) for Consul Connect. In most cases, the container should contain the following parameters and values.
|
||||
|
||||
<CodeBlockConfig highlight="8-40">
|
||||
|
||||
|
|
@ -146,7 +144,7 @@ The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for
|
|||
|
||||
</CodeBlockConfig>
|
||||
|
||||
In most cases, the `sidecar-proxy` container can be configured exactly as shown above.
|
||||
The following table describes the available configuration settings.
|
||||
|
||||
| Field name | Type | Description |
|
||||
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
|
|
@ -252,7 +250,7 @@ exec consul agent \
|
|||
-config-file /consul/agent-defaults.hcl
|
||||
```
|
||||
|
||||
Set the following fields as shown above:
|
||||
The following table describes the values that you should use to configure the `command` script:
|
||||
|
||||
| Field name | Type | Description |
|
||||
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
|
|
@ -263,7 +261,7 @@ Set the following fields as shown above:
|
|||
| `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. |
|
||||
|
||||
-> **NOTE**: Use `exec` to start the Consul agent, so that the Consul agent runs as PID 1. This ensures
|
||||
-> **NOTE**: Use `exec` to start the Consul agent so that the Consul agent runs as PID 1. This ensures
|
||||
the Consul agent directly receives signals from ECS, which is important for graceful shutdown of the Consul agent.
|
||||
|
||||
Refer to the [Consul Agent documentation](/docs/agent/options#configuration_files) for a complete reference of Consul agent
|
||||
|
|
@ -364,14 +362,14 @@ Here is the sample config from above, expanded to be readable:
|
|||
| `proxy.upstreams` | list | The upstream services that your application calls over the service mesh, if any. |
|
||||
| `service.name` | string | The name used to register this service into the Consul service catalog. |
|
||||
| `service.port` | number | The port your application listens on. Set to `0` if your application does not listen on any port. |
|
||||
| `service.checks` | list | Consul [checks](/docs/discovery/checks) to include, to have Consul run health checks against your application. |
|
||||
| `service.checks` | list | Specifies the Consul health [checks](/docs/discovery/checks) to run against your application. |
|
||||
|
||||
See the [`consul-ecs JSON Schema`](https://github.com/hashicorp/consul-ecs/blob/main/config/schema.json) for a complete reference of fields.
|
||||
|
||||
## `consul-ecs-health-sync` container
|
||||
|
||||
Optionally, Consul ECS can sync health checks for this task into Consul checks.
|
||||
This allows you to configure a health check for your application in one place, and
|
||||
This allows you to configure a health check for your application in one place and
|
||||
see a consistent health status in both ECS and Consul.
|
||||
|
||||
For example, the following defines an ECS health check command that runs `curl localhost:9090/health`:
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ The following requirements must be met in order to install Consul on ECS:
|
|||
1. **Sidecar containers:** Consul on ECS requires two sidecar containers to run in each ECS task: a
|
||||
Consul agent container and a sidecar proxy container. These additional sidecar containers must
|
||||
be included in the ECS task definition. The [Consul ECS Terraform module](/docs/ecs/install)
|
||||
will include these sidecar containers for you. Or if you do not use Terraform, you can construct
|
||||
will include these sidecar containers for you. If you do not use Terraform, you can construct
|
||||
the task definition yourself by following [our documentation](/docs/ecs/manual-installation).
|
||||
1. **Routing:** With your application running in tasks as part of the mesh, you must specify the
|
||||
upstream services that your application calls. You will also need to change the URLs your
|
||||
|
|
|
|||
Loading…
Reference in New Issue