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.

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 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

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.
2. The mesh-init container registers services and proxies with the Consul servers.
3. The mesh-init container writes the bootstrap configuration for the Consul dataplane process and stores it in a shared volume.
4. The mesh-init container configures Consul DNS and modifies traffic redirection rules.
5. The dataplane container starts and configures itself using the bootstrap configuration generated by the mesh-init container.
6. The dataplane container starts the Envoy sidecar proxy.
7. The health-sync container starts listening for ECS health checks.
8. 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 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 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.