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.jpg#light-theme-only)
![Diagram that provides an overview of the Consul Architecture on ECS ](/img/ecs/consul-on-ecs-architecture-dataplanes-dark.jpg#dark-theme-only)

## Components
Consul starts several components and containers inside the ECS cluster. Refer to [Startup sequence](#startup-sequence) for details about the order of the startup procedure:
 
### Control-plane container

The control-plane container 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
- Synchronizes ECS health checks
- Watches the Consul server for changes

### Dataplane containers

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 control-plane 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 control-plane container starts and logs into Consul.
1. The control-plane container registers services and proxies with the Consul servers.
1. The control-plane container writes the bootstrap configuration for the Consul dataplane process and stores it in a shared volume.
1. The dataplane container starts and configures itself using the bootstrap configuration generated by the control-plane container. 
1. The dataplane container starts the Envoy sidecar proxy.
1. The control-plane container starts listening for ECS health checks.
1. When the ECS task indicates that the application instance is healthy, the control-plane container marks the service as healthy and starts allowing 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.