github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Apply suggestions to ECS docs from code review 

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
pull/11825/head
Paul Glass 2022-01-21 10:12:32 -06:00
parent 919b659c98
commit bb4a035254
3 changed files with 23 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
website/content/docs/ecs/install.mdx
View File

@ -1,15 +1,17 @@
--- ---
layout: docs layout: docs
page_title: Installation with Terraform - AWS ECS page_title: Installing Consul on AWS ECS using Terraform
description: >- description: >-
Install Consul Service Mesh on AWS ECS with Terraform (Elastic Container Service). Install Consul Service Mesh on AWS ECS with Terraform (Elastic Container Service).
--- ---
# Installation with Terraform # 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 * 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. 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. 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 ```hcl
module "my_task" { module "my_task" {
@ -61,7 +63,7 @@ however there are some important inputs worth highlighting:
| Input Variable | Type | Description | | Input Variable | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source` and `version` | string | This specifies the source location and version of the `mesh-task` module. | | `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. | | `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`. | | `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. | | `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. |

32
website/content/docs/ecs/manual-installation.mdx
View File

@ -7,19 +7,17 @@ description: >-
# Manual Installation # Manual Installation
While the [Consul ECS Terraform module](/docs/ecs/install) is the easiest way to use Consul on ECS, 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.
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.
## 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. ## Prerequisites
* 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. 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 ## 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 * Your application container
* An Envoy sidecar-proxy container * An Envoy sidecar-proxy container
@ -29,7 +27,7 @@ You must define a Task Definition which includes the following containers:
## Top-level fields ## 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 ```json
{ {
@ -49,9 +47,9 @@ In your task definition, you'll need to define these important top-level fields:
| Field name | Type | Description | | 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. | | `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). | | `containerDefinitions` | list | The list of containers to run in this task (see below). |
## Application container ## Application container
@ -95,7 +93,7 @@ See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/devel
## `sidecar-proxy` container ## `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"> <CodeBlockConfig highlight="8-40">
@ -146,7 +144,7 @@ The sidecar proxy container runs [Envoy proxy](/docs/connect/proxies/envoy) for
</CodeBlockConfig> </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 | | Field name | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -252,7 +250,7 @@ exec consul agent \
-config-file /consul/agent-defaults.hcl -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 | | 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. | | `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. | | `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. 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 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. | | `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.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.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. 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 ## `consul-ecs-health-sync` container
Optionally, Consul ECS can sync health checks for this task into Consul checks. 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. 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`: For example, the following defines an ECS health check command that runs `curl localhost:9090/health`:

2
website/content/docs/ecs/requirements.mdx
View File

@ -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 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 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) 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). 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 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 upstream services that your application calls. You will also need to change the URLs your