terraform-aws-modules/terraform-aws-ecs

The project is organized into several specialized sub-modules (constructs) that represent different levels of the Amazon ECS hierarchy. Understanding these helps you decide how to compose your infrastructure:

• Cluster: Manages the ECS cluster, capacity providers (EC2, Fargate on-demand, Fargate spot), CloudWatch log groups, and task execution IAM roles.
• Service: Manages an ECS service deployed on a cluster. It includes advanced logic for ignoring specific changes (like desired_count or task_definition) to support autoscaling and continuous deployment.
• Task: Manages task definitions, task sets, and application autoscaling. It handles IAM roles for tasks and container definitions.
• Container Definition: A building block used to construct the container_definitions argument for tasks. It provides advanced management for CloudWatch log groups and Firelens configurations.

The wrappers/container-definition directory provides a module wrapper pattern designed for scenarios where native Terraform for_each is not feasible, such as when using Terragrunt. This wrapper allows you to manage multiple instances of the underlying modules/container-definition module within a single configuration block by defining a map of items.

This wrapper does not add new functionality; it simply provides a way to pass a map of configurations (items) and a set of shared configuration values (defaults) to the underlying module.

module "wrapper" {
  source = "terraform-aws-modules/ecs/aws//wrappers/container-definition"

  defaults = {
    create = true
    tags = {
      Terraform   = "true"
      Environment = "dev"
    }
  }

  items = {
    my-item = {
      # arguments supported by the underlying container-definition module
    }
    my-second-item = {
      # arguments supported by the underlying container-definition module
    }
  }
}

When configuring tasks, you must distinguish between these two IAM roles, as they serve different purposes and have different lifecycles:

Task Execution IAM Role

• Purpose: Used by the Amazon ECS service itself during the task creation process.
• Use Case: Required if your task definition needs to pull secrets from AWS Secrets Manager or retrieve parameters from SSM Parameter Store to inject them as environment variables.
• Scope: Permissions are only used during task startup; the containers running inside the task do not inherit these permissions.

Task IAM Role

• Purpose: Used by the application code running inside the container at runtime.
• Use Case: Required if your application needs to interact with AWS services directly (e.g., reading from S3, connecting to RDS via IAM authentication).
• Analogy: Similar to an IAM Instance Profile for EC2 or an IAM Role for Service Accounts (IRSA) for EKS pods.

Use the following inputs to control resource lifecycle:

• Disable service and all resources: Set create_service = false to prevent the creation of the ECS service and its associated resources.
• Enable ECS Exec: Set enable_ecs_exec = true to enable the ECS Exec feature, allowing you to run commands in containers.
• Manage IAM Roles manually:
  • Set create_service_iam_role = false and provide an existing role via iam_role_arn to skip creating the service IAM role.
  • Set create_task_exec_iam_role = false and provide an existing role via task_exec_iam_role_arn to skip creating the task execution IAM role.
• Manage Task Definitions manually:
  • Set create_task_definition = false and provide an existing ARN via task_definition_arn to skip creating a new task definition.
• Manage Task Execution IAM Role Policies:
  • Set create_task_exec_iam_role_policy = false to prevent the module from creating the policy attached to the task execution role.

The container_definitions argument accepts a map of container configurations. This allows you to define multiple containers within a single task, such as an application container and a sidecar (e.g., Fluent Bit for logging).

Common configuration options for containers include:

• cpu and memory: Resource limits.
• essential: Whether the container is required for the task to run.
• image: The container image URI.
• firelensConfiguration: Used for FireLens logging sidecars.
• logConfiguration: Configures the log driver (e.g., awsfirelens).
• dependsOn: Defines startup dependencies between containers.
• readonlyRootFilesystem: Controls filesystem permissions.

container_definitions = {
    fluent-bit = {
      cpu       = 512
      memory    = 1024
      essential = true
      image     = "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:stable"
      firelensConfiguration = {
        type = "fluentbit"
      }
      memoryReservation = 50
    }

    ecs-sample = {
      cpu       = 512
      memory    = 1024
      essential = true
      image     = "public.ecr.aws/aws-containers/ecsdemo-frontend:776fd50"
      portMappings = [
        {
          name          = "ecs-sample"
          containerPort = 80
          protocol      = "tcp"
        }
      ]
      readonlyRootFilesystem = false
      dependsOn = [{
        containerName = "fluent-bit"
        condition     = "START"
      }]
      logConfiguration = {
        logDriver = "awsfirelens"
        options = {
          Name                    = "firehose"
          region                  = "eu-west-1"
          delivery_stream         = "my-stream"
          log-driver-buffer-limit = "2097152"
        }
      }
    }
  }

The ecs_service sub-module in version 6.x has split security group rules into two distinct maps: security_group_ingress_rules and security_group_egress_rules. Additionally, the underlying AWS resources have changed from aws_security_group_rule to aws_vpc_security_group_ingress_rule and aws_vpc_security_group_egress_rule.

Key Mapping Changes:

• security_group_rules $\rightarrow$ security_group_ingress_rules AND security_group_egress_rules
• source_security_group_id $\rightarrow$ referenced_security_group_id
• protocol $\rightarrow$ ip_protocol
• cidr_blocks $\rightarrow$ cidr_ipv4

Important State Migration: Because these are different resource types, you cannot use terraform mv. You must remove the old rules from the state and import the new ones manually.

# For Ingress rules
terraform state rm 'module.ecs_service.aws_security_group_rule.this["alb_ingress_3000"]'
terraform state import 'module.ecs_service.aws_vpc_security_group_ingress_rule.this["alb_3000"]' 'sg-xxx'

# For Egress rules
terraform state rm 'module.ecs_service.aws_security_group_rule.this["egress_all"]'
terraform state import 'module.ecs_service.aws_vpc_security_group_egress_rule.this["all"]' 'sg-xxx'