Battle-tested AWS ECS infrastructure: CloudMap service discovery for Fargate (Service Connect) and EC2 (DNS) clusters

This template helps set up Fargate and EC2-based ECS clusters using AWS CloudMap for communication.

Service Discovery

• Fargate: Uses AWS Service Connect, creating HTTP-only CloudMap services. Includes an automatic proxy container.
• EC2-based ECS: Uses DNS-based discovery.

AWS Service Connect (Fargate)

• Creates HTTP-only CloudMap services (no DNS resolution)
• Requires an additional proxy container (managed by AWS)

DNS-based Service Discovery (EC2-based ECS)

• If containers use bridge mode, creates SRV records instead of A records (Nginx free version cannot resolve SRV records)
• To get A records, use awsvpc mode

Rationale

Environments (dev, prod, etc)

To avoid duplicating code, the same my-application folder is used for different environments. However, it is necessary to re-initialize the local Terraform state from S3 every time the environment is switched.

To switch environments, follow these steps:

• Clear the local state, including the .terraform folder and .terraform.lock.hcl file.
• Run terraform init with the appropriate environment variables.

It is crucial to clear the local state to avoid merging states from different environments. Delete the local state, and terraform init will restore it from S3, which is always safe.

Structure

• terraform/my-application/ - AWS resources for the ECS clusters
• terraform/environments/ - Environment-specific variables
• terraform/modules/ - Common Terraform code
• tests/features/ - BDD tests for the Terraform configuration
• Makefile - Commands for Terraform and tests

Usage

To use AWS CLI:

1. Create an IAM user and include it in the admin group.
2. Attach AutoScalingFullAccess policy.
3. Create Access Key credentials.
4. Set credentials in environment variables or ~/.aws/credentials:

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

Debugging in the Cloud

In the configuration, the debug mode for ECS containers is enabled (marked with # ecs execute-command). See details in AWS ECS EXEC.

You should locally install Session Manager.

A useful utility to check your system's readiness for ECS EXEC is Exec-checker.

You can connect to the container in ECS using:

aws ecs execute-command --cluster ec2 \
  --task $(aws ecs list-tasks --cluster ec2 --query "taskArns" --output text) \
  --container ec2 --interactive --command "/bin/sh"

To inspect an active task:

aws ecs describe-tasks --cluster ec2 \
  --tasks $(aws ecs list-tasks --cluster ec2 --query "taskArns" --output text)

Developer environment

Terraform

Install Terraform from the official website or via Homebrew (macOS).

brew install hashicorp/tap/terraform

Pre-commit

Use pre-commit hooks to validate the Terraform code quality:

pre-commit install

Terraform code analysis

brew tap liamg/tfsec
brew install terraform-docs tflint tfsec checkov
brew install pre-commit gawk coreutils

BDD Testing

virtualenv

Install and/or activate Python virtual environment (you need uv installed):

. ./activate.sh

Note the spaces after the first dot.

For this to work, you need uv installed.

Terraform

Initialize Terraform (requires active AWS credentials) with:

make init

BDD tests

make test

Visit terraform-compliance for more on writing tests.