How do I set up dynamic port mapping for Amazon ECS?

3 minute read

I want to use an Application Load Balancer to set up dynamic port mapping for Amazon Elastic Container Service (Amazon ECS) and target groups that run multiple task copies on one instance.

Short description

You can set up dynamic port mapping when you create a new Application Load Balancer and a new Amazon ECS service. Or, use the AWS Command Line Interface (AWS CLI) to set up dynamic port mapping for an existing Application Load Balancer and Amazon ECS service.

To use Network Load Balancers for dynamic port mapping, see Use a Network Load Balancer for Amazon ECS.

Note: Application Load Balancers use dynamic port mapping to run multiple tasks from one service on the same container instance. A Classic Load Balancer doesn't run multiple copies of a task on the same instance. If you use the Classic Load Balancer, then you must statically map port numbers on a container instance.

Resolution

Note: If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Use a new Application Load Balancer to set up dynamic port mapping for a new Amazon ECS service

Create an Application Load Balancer for Amazon ECS and a target group.

Open the Amazon ECS console, and then set the host port to 0 for the task definition that you must create or update. Then, configure the container port mappings task definition parameter to match your application. The host and awsvpc network modes don't support dynamic host port mapping.

Add a rule to allow inbound traffic from your load balancer to your container instances. The security group and network access control list (network ACL) must allow traffic from your Application Load Balancer to your instances over the ephemeral port range. For more information about ephemeral port ranges, see PortMapping.

Then, use the Amazon ECS console to configure your new Amazon ECS service to use the Application Load Balancer that you created.

Use AWS CLI to set up dynamic port mapping for an existing Application Load Balancer and Amazon ECS service

Important: If you update your service task definition, then the container name and container port that you specified when you created your service must remain in your task definition. For more information, see Service load balancing.

To update an existing service, use the update-service AWS CLI command to change configurations or add an Application Load Balancer for an existing Amazon ECS service:

aws ecs update-service --cluster example-cluster-name --service example-service-name --load-balancers "{\"containerName\": \"example-container-name\", \"containerPort\": example-container-port-number, \"targetGroupArn\": \"example-target-group-arn\"}"

Note: Replace example-cluster-name, example-service-name, and example-container-name with the names of your values. Replace example-container-port-number with your container port number, and replace example-target-group-arn with the Amazon Resource Name (ARN) of your target group.

Verify that you correctly configured port mapping

Complete the following steps:

Open the Amazon Elastic Compute Cloud (Amazon EC2) console.
In the navigation pane, choose Target Groups.
Select the hyperlinked name for your target group.
In the Targets tab, verify that the task in the service that you created uses the correct port.

If dynamic port mapping is correctly set up, then you can see the registered targets in the target group and the assigned port for the task. You can also see the task in the registered targets for the following ephemeral port ranges: