Migrate Tasks to Consul on AWS Elastic Container Service (ECS) with Terraform

This topic describes how to migrate your existing ECS Tasks to use our mesh-task Terraform module.

Define Tasks in Terraform

Your tasks must first be specified in Terraform using the ecs_task_definition resource so that they can then be converted to use the mesh-task module.

For example, your tasks should be defined with Terraform similar to the following:

resource "aws_ecs_task_definition" "my_task" {
  family                   = "my_task"
  requires_compatibilities = ["FARGATE"]
  network_mode             = "awsvpc"
  cpu                      = 256
  memory                   = 512
  execution_role_arn       = "arn:aws:iam::111111111111:role/execution-role"
  task_role_arn            = "arn:aws:iam::111111111111:role/task-role"
  container_definitions = jsonencode(
    [{
      name             = "example-client-app"
      image            = "docker.io/org/my_task:v0.0.1"
      essential        = true
      portMappings = [
        {
          containerPort = 9090
          hostPort      = 9090
          protocol      = "tcp"
        }
      ]
      cpu         = 0
      mountPoints = []
      volumesFrom = []
    }]
  )
}

resource "aws_ecs_service" "my_task" {
  name            = "my_task"
  cluster         = "arn:aws:ecs:us-east-1:111111111111:cluster/my-cluster"
  task_definition = aws_ecs_task_definition.my_task.arn
  desired_count   = 1
  network_configuration {
    subnets = ["subnet-abc123"]
  }
  launch_type            = "FARGATE"
}

Convert to the `mesh-task` Module

In order to add the necessary sidecar containers for your task to join the mesh, you must use the mesh-task module.

The mesh-task module uses inputs similar to your old ECS task definition but creates a new version of the task definition with additional containers.

The mesh-task module is used as follows:

module "my_task" {
  source  = "hashicorp/consul-ecs/aws//modules/mesh-task"
  version = "<latest version>"

  family                = "my_task"
  container_definitions = [
    {
      name         = "example-client-app"
      image        = "docker.io/org/my_task:v0.0.1"
      essential    = true
      portMappings = [
        {
          containerPort = 9090
          hostPort      = 9090
          protocol      = "tcp"
        }
      ]
      cpu         = 0
      mountPoints = []
      volumesFrom = []
    }
  ]

  port       = 9090
  retry_join = ["<address of the Consul server>"]
}

The main differences are:

You should remove the execution_role_arn and task_role_arn fields. The mesh-task module creates the task and execution roles by default. If you need to use existing IAM role(s), set the task_role and execution_role fields to pass in existing roles.
You must set the port field to the port that your application listens on. If your application has no listening port, set outbound_only = true and remove the port field.
You must add the retry_join field. This specifies the location of your Consul servers so that your task can join the mesh.
You must remove the jsonencode() function from the container_definitions field.

The mesh-task module will create a new version of your task definition with the necessary sidecar containers added so you can delete your existing aws_ecs_task_definition resource.

Next Steps

Now that your task(s) are migrated to the mesh-task module,

Start at the ECS Service section of the Installation Guide to continue installing Consul on ECS.
Refer to the mesh-task reference documentation for all available inputs to your mesh tasks.

Migrate Tasks to Consul on AWS Elastic Container Service (ECS) with Terraform

Define Tasks in Terraform

Convert to the mesh-task Module

Next Steps

Convert to the `mesh-task` Module