consul/website/content/docs/ecs/architecture.mdx

---
layout: docs
page_title: Consul on AWS Elastic Container Service (ECS) architecture
description: >-
  Learn about the Consul architecture on Amazon Web Services ECS deployments. Learn about how the two work together, including the order tasks and containers startup and shutdown, as well as requirements for the AWS IAM auth method, the ACL controller and tokens, and health check syncing.
---

# Consul on AWS Elastic Container Service (ECS) architecture

This topic provides reference information about the Consul's deployment architecture on AWS ECS. The following diagram shows the main components of the Consul architecture when deployed to an ECS cluster.

![Diagram that provides an overview of the Consul Architecture on ECS](/img/ecs/consul-on-ecs-architecture-dataplanes.png#light-theme-only)
![Diagram that provides an overview of the Consul Architecture on ECS ](/img/ecs/consul-on-ecs-architecture-dataplanes-dark.png#dark-theme-only)

## Components

Consul starts several components and containers inside the ECS cluster. Using a combination of short-lived containers (`mesh-init`) and long-lived containers (`health-sync`) ensures that any long running containers do not have root access to Consul. Refer to [Startup sequence](#startup-sequence) for details about the order of the startup procedure.
 
### `mesh-init` container

The `mesh-init` container is a short-lived container that performs the following actions:

- Logs into Consul servers
- Communicates directly with Consul server
- Registers proxies and services
- Creates a bootstrap configuration file for Consul dataplane container and stores it in a shared volume
- Invokes the `iptables` SDK to configure traffic redirection rules

### `health-sync` container

The `health-sync` container is a long-lived container that performs the following actions:

- Synchronizes ECS health checks
- Watches the Consul server for changes

When you stop the ECS task, it performs the following actions:

- Deregisters service and proxy instances on receiving SIGTERM to support graceful shutdown
- Performs logout from [ACL auth method](/consul/docs/security/acl/auth-methods)

### `dataplane` container

The dataplane process runs in the same container as the Envoy proxy and performs the following actions:

- Consumes and configures itself according to the bootstrap configuration written by the `mesh-init` container.
- Contains and starts up the Envoy sidecar.

### ECS controller container

One ECS task in the cluster contains the controller container, which performs the following actions:

- Creates AWS IAM auth methods
- Creates ACL policies and roles
- Maintains ACL state
- Removes tokens when services exit
- Deregisters services if the ECS task exits without deregistering them
- Registers a _synthetic node_ that enables Consul to register services to the catalog  
 
## Startup sequence

Deploying Consul to ECS starts the following process to build the architecture:

1. The `mesh-init` container starts and logs in to Consul.
1. The `mesh-init` container registers services and proxies with the Consul servers.
1. The `mesh-init` container writes the bootstrap configuration for the Consul dataplane process and stores it in a shared volume.
1. The `mesh-init` container configures Consul DNS and modifies traffic redirection rules.
1. The `dataplane` container starts and configures itself using the bootstrap configuration generated by the `mesh-init` container. 
1. The `dataplane` container starts the Envoy sidecar proxy.
1. The `health-sync` container starts listening for ECS health checks.
1. When the ECS task indicates that the application instance is healthy, the `health-sync` container marks the service as healthy and allows traffic to flow.

## Consul security components

Consul leverages AWS components to facilitate its own security features.  

### Auth methods

Consul on ECS uses the AWS IAM auth method so that ECS tasks can automatically obtain Consul ACL tokens during startup.

When ACLs are enabled, the Terraform modules for Consul on ECS support AWS IAM auth methods by default. The ECS controller sets up the auth method on the Consul servers. The `mesh-task` module configures the ECS task definition to be compatible with the auth method.

A unique task IAM role is required for each ECS task family. A task family represents only one Consul service and the task IAM role must encode the Consul service name. As a result, task IAM roles must not be shared by different task families. 

By default, the mesh-task module creates and configures the task IAM role for you.

To pass an existing IAM role to the mesh-task module using the `task_role` input variable, configure the IAM role as described in ECS Task Role Configuration to be compatible with the AWS IAM auth method.

### ECS task roles

The [ECS task role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) is an IAM role associated with an ECS task.

When an ECS task starts up, it runs a `consul login` command. The command obtains credentials for the task role from AWS and then uses those credentials to sign the login request to the AWS IAM auth method. The credentials prove the ECS task's identity to the Consul servers.

You must configure the task role with the following details for it to be compatible with the AWS IAM auth method:

- An `iam:GetRole` permission to fetch itself. Refer to [IAM Policies](/consul/docs/security/acl/auth-methods/aws-iam#iam-policies) for additional information. 
- A `consul.hashicorp.com.service-name` tag on the task role which contains the Consul service name for the application in this task.
- When using Consul Enterprise, add a `consul.hashicorp.com.namespace` tag on the task role indicating the Consul Enterprise namespace where this service is registered.