# Use load balancing to distribute Amazon ECS service traffic
Your service can optionally be configured to use Elastic Load Balancing to distribute traffic evenly across the tasks in your service.
**Note**
When you use tasks sets, all the tasks in the set must all be configured to use Elastic Load Balancing or to not use Elastic Load Balancing.
Amazon ECS services hosted on AWS Fargate support the Application Load Balancers, Network Load Balancers, and Gateway Load Balancers. Use the following table to learn about what type of load balancer to use.
| Load Balancer type | Use in these cases |
| --- | --- |
| Application Load Balancer | Route HTTP/HTTPS (or layer 7) traffic.Application Load Balancers offer several features that make them attractive for use with Amazon ECS services: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-load-balancing.html) |
| Network Load Balancer | Route TCP or UDP (or layer 4) traffic. |
| Gateway Load Balancer | Route TCP or UDP (or layer 4) traffic. Use virtual appliances, such as firewalls, intrusion detection and prevention systems, and deep packet inspection systems. |
We recommend that you use Application Load Balancers for your Amazon ECS services so that you can take advantage of these latest features, unless your service requires a feature that is only available with Network Load Balancers or Gateway Load Balancers. For more information about Elastic Load Balancing and the differences between the load balancer types, see the [Elastic Load Balancing User Guide](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/).
With your load balancer, you pay only for what you use. For more information, see [Elastic Load Balancing pricing](https://aws.amazon.com/elasticloadbalancing/pricing/).
# Optimize load balancer health check parameters for Amazon ECS
Load balancers route requests only to the healthy targets in the Availability Zones for the load balancer. Each target is registered to a target group. The load balancer checks the health of each target, using the target group health check settings. After you register the target, it must pass one health check to be considered healthy. Amazon ECS monitors the load balancer. The load balancer periodically sends health checks to the Amazon ECS container. The Amazon ECS agent monitors, and waits for the load balancer to report on the container health. It does this before it considers the container to be in a healthy status.
Two Elastic Load Balancing health check parameters affect deployment speed:
+ Health check interval: Determines the approximate amount of time, in seconds, between health checks of an individual container. By default, the load balancer checks every 30 seconds.
This parameter is named:
+ `HealthCheckIntervalSeconds` in the Elastic Load Balancing API
+ **Interval** on the Amazon EC2 console
+ Healthy threshold count: Determines the number of consecutive health check successes required before considering an unhealthy container healthy. By default, the load balancer requires five passing health checks before it reports that the target container is healthy.
This parameter is named:
+ `HealthyThresholdCount` in the Elastic Load Balancing API
+ **Healthy threshold** on the Amazon EC2 console
**Important:** For newly registered targets, only a single successful health check is required to consider the target healthy, regardless of the healthy threshold count setting. The healthy threshold count only applies when a target is transitioning from an unhealthy state back to a healthy state.
With the default settings, if a target becomes unhealthy and then recovers, the total time to determine the health of a container is two minutes and 30 seconds (`30 seconds * 5 = 150 seconds`).
You can speed up the health-check process if your service starts up and stabilizes in under 10 seconds. To speed up the process, reduce the health check interval and the healthy threshold count.
+ `HealthCheckIntervalSeconds` (Elastic Load Balancing API name) or **Interval** (Amazon EC2 console name): 5
+ `HealthyThresholdCount` (Elastic Load Balancing API name) or **Healthy threshold** (Amazon EC2 console name): 2
With this setting, the health-check process takes 10 seconds compared to the default of two minutes and 30 seconds.
For more information about the Elastic Load Balancing health check parameters, see [Health checks for your target groups](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-health-checks.html) in the *Elastic Load Balancing User Guide*.
# Optimize load balancer connection draining parameters for Amazon ECS
To allow for optimization, clients maintain a keep alive connection to the container service. This allows subsequent requests from that client to reuse the existing connection. When you want to stop traffic to a container, you notify the load balancer. The load balancer periodically checks to see if the client closed the keep alive connection. Amazon ECS monitors the load balancer, and waits for the load balancer to report that the keep alive connection is closed (the target is in an `UNUSED` state).
The amount of time that the load balancer waits to move the target to the `UNUSED` state is the deregistration delay. You can configure the following load balancer parameter to speed up your deployments.
+ `deregistration_delay.timeout_seconds`: 300 (default)
When you have a service with a response time that's under 1 second, set the parameter to the following value to have the load balancer only wait 5 seconds before it breaks the connection between the client and the back-end service:
+ `deregistration_delay.timeout_seconds`: 5
**Note**
Do not set the value to 5 seconds when you have a service with long-lived requests, such as slow file uploads or streaming connections.
## SIGTERM responsiveness
Amazon ECS first sends a stop signal to the task to notify the application needs to finish and shut down. This signal can be defined in your container image with the STOPSIGNAL instruction and will default to SIGTERM. Then, Amazon ECS sends a SIGKILL message. When applications ignore the SIGTERM, the Amazon ECS service must wait to send the SIGKILL signal to terminate the process.
The amount of time that Amazon ECS waits to send the SIGKILL message is determined by the following Amazon ECS agent option:
+ `ECS_CONTAINER_STOP_TIMEOUT`: 30 (default)
For more information about the container agent parameter, see [Amazon ECS Container Agent](https://github.com/aws/amazon-ecs-agent/blob/master/README.md) on GitHub.
To speed up the waiting period, set the Amazon ECS agent parameter to the following value:
+ `ECS_CONTAINER_STOP_TIMEOUT`: 2
If your application takes more than 1 second, multiply the value by 2 and use that number as the value.
In this case, the Amazon ECS waits 2 seconds for the container to shut down, and then Amazon ECS sends a SIGKILL message when the application didn't stop.
You can also modify the application code to trap the SIGTERM signal and react to it. The following is example in JavaScript:
```
process.on('SIGTERM', function() {
server.close();
})
```
This code causes the HTTP server to stop listening for any new requests, finish answering any in-flight requests, and then the Node.js process terminates because the event loop has nothing to do. Given this, if it takes the process only 500 ms to finish its in-flight requests, it terminates early without having to wait out the stop timeout and get sent a SIGKILL.
# Use an Application Load Balancer for Amazon ECS
An Application Load Balancer makes routing decisions at the application layer (HTTP/HTTPS), supports path-based routing, and can route requests to one or more ports on each container instance in your cluster. Application Load Balancers support dynamic host port mapping. For example, if your task's container definition specifies port 80 for an NGINX container port, and port 0 for the host port, then the host port is dynamically chosen from the ephemeral port range of the container instance (such as 32768 to 61000 on the latest Amazon ECS-optimized AMI). When the task launches, the NGINX container is registered with the Application Load Balancer as an instance ID and port combination, and traffic is distributed to the instance ID and port corresponding to that container. This dynamic mapping allows you to have multiple tasks from a single service on the same container instance. For more information, see the [User Guide for Application Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/).
For information about the best practices for setting parameters to speed up you deployments see:
+ [Optimize load balancer health check parameters for Amazon ECS](load-balancer-healthcheck.md)
+ [Optimize load balancer connection draining parameters for Amazon ECS](load-balancer-connection-draining.md)
Consider the following when using Application Load Balancers with Amazon ECS:
+ Amazon ECS requires the service-linked IAM role which provides the permissions needed to register and deregister targets with your load balancer when tasks are created and stopped. For more information, see [Using service-linked roles for Amazon ECS](using-service-linked-roles.md).
+ For services in an IPv6-only configuration, you must set the target group IP address type of the Application Load Balancer to `dualstack` or `dualstack-without-public-ipv4`.
+ For services with tasks using the `awsvpc` network mode, when you create a target group for your service, you must choose `ip` as the target type, not `instance`. This is because tasks that use the `awsvpc` network mode are associated with an elastic network interface, not an Amazon EC2 instance.
+ If your service requires access to multiple load balanced ports, such as port 80 and port 443 for an HTTP/HTTPS service, you can configure two listeners. One listener is responsible for HTTPS that forwards the request to the service, and another listener that is responsible for redirecting HTTP requests to the appropriate HTTPS port. For more information, see [Create a listener to your Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-listener.html) in the *User Guide for Application Load Balancers*.
+ Your load balancer subnet configuration must include all Availability Zones that your container instances reside in.
+ After you create a service, the load balancer configuration can't be changed from the AWS Management Console. You can use the AWS Copilot, AWS CloudFormation, AWS CLI or SDK to modify the load balancer configuration for the `ECS` rolling deployment controller only, not AWS CodeDeploy blue/green or external. When you add, update, or remove a load balancer configuration, Amazon ECS starts a new deployment with the updated Elastic Load Balancing configuration. This causes tasks to register to and deregister from load balancers. We recommend that you verify this on a test environment before you update the Elastic Load Balancing configuration. For information about how to modify the configuration, see [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html) in the *Amazon Elastic Container Service API Reference*.
+ If a service task fails the load balancer health check criteria, the task is stopped and restarted. This process continues until your service reaches the number of desired running tasks.
+ If you are experiencing problems with your load balancer-enabled services, see [Troubleshooting service load balancers in Amazon ECS](troubleshoot-service-load-balancers.md).
+ When using `instance` target type, your tasks and load balancer must be in the same VPC. When using `ip` target type, cross-VPC connectivity is supported.
+ Use a unique target group for each service.
Using the same target group for multiple services might lead to issues during service deployments.
+ You must specify target groups that are associated with an Application Load Balancer.
For information about how to create an Application Load Balancer, see [Create an Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-application-load-balancer.html) in *Application Load Balancers *
# Use a Network Load Balancer for Amazon ECS
A Network Load Balancer makes routing decisions at the transport layer (TCP/SSL). It can handle millions of requests per second. After the load balancer receives a connection, it selects a target from the target group for the default rule using a flow hash routing algorithm. It attempts to open a TCP connection to the selected target on the port specified in the listener configuration. It forwards the request without modifying the headers. Network Load Balancers support dynamic host port mapping. For example, if your task's container definition specifies port 80 for an NGINX container port, and port 0 for the host port, then the host port is dynamically chosen from the ephemeral port range of the container instance (such as 32768 to 61000 on the latest Amazon ECS-optimized AMI). When the task is launched, the NGINX container is registered with the Network Load Balancer as an instance ID and port combination, and traffic is distributed to the instance ID and port corresponding to that container. This dynamic mapping allows you to have multiple tasks from a single service on the same container instance. For more information, see the [User Guide for Network Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/).
For information about the best practices for setting parameters to speed up you deployments see:
+ [Optimize load balancer health check parameters for Amazon ECS](load-balancer-healthcheck.md)
+ [Optimize load balancer connection draining parameters for Amazon ECS](load-balancer-connection-draining.md)
Consider the following when using Network Load Balancers with Amazon ECS:
+ Amazon ECS requires the service-linked IAM role which provides the permissions needed to register and deregister targets with your load balancer when tasks are created and stopped. For more information, see [Using service-linked roles for Amazon ECS](using-service-linked-roles.md).
+ You cannot attach more than five target groups to a service.
+ For services in an IPv6-only configuration, you must set the target group IP address type of the Network Load Balancer to `dualstack`.
+ For services with tasks using the `awsvpc` network mode, when you create a target group for your service, you must choose `ip` as the target type, not `instance`. This is because tasks that use the `awsvpc` network mode are associated with an elastic network interface, not an Amazon EC2 instance.
+ Your load balancer subnet configuration must include all Availability Zones that your container instances reside in.
+ After you create a service, the load balancer configuration can't be changed from the AWS Management Console. You can use the AWS Copilot, AWS CloudFormation, AWS CLI or SDK to modify the load balancer configuration for the `ECS` rolling deployment controller only, not AWS CodeDeploy blue/green or external. When you add, update, or remove a load balancer configuration, Amazon ECS starts a new deployment with the updated Elastic Load Balancing configuration. This causes tasks to register to and deregister from load balancers. We recommend that you verify this on a test environment before you update the Elastic Load Balancing configuration. For information about how to modify the configuration, see [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html) in the *Amazon Elastic Container Service API Reference*.
+ If a service task fails the load balancer health check criteria, the task is stopped and restarted. This process continues until your service reaches the number of desired running tasks.
+ When you use a Gateway Load Balancer configured with IP addresses as targets and Client IP Preservation off, requests are seen as coming from the Gateway Load Balancers private IP address. This means that services behind an Gateway Load Balancer are effectively open to the world as soon as you allow incoming requests and health checks in the target security group.
+ For Fargate tasks, you must use platform version `1.4.0` (Linux) or `1.0.0` (Windows).
+ If you are experiencing problems with your load balancer-enabled services, see [Troubleshooting service load balancers in Amazon ECS](troubleshoot-service-load-balancers.md).
+ When using `instance` target type, your tasks and load balancer must be in the same VPC. When using `ip` target type, cross-VPC connectivity is supported.
+ The Network Load Balancer client IP address preservation is compatible with Fargate targets.
+ Use a unique target group for each service.
Using the same target group for multiple services might lead to issues during service deployments.
+ You must specify target groups that are associated with a Network Load Balancer.
For information about how to create a Network Load Balancer, see [Create a Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-network-load-balancer.html) in *Network Load Balancers *
**Important**
If your service's task definition uses the `awsvpc` network mode (which is required for Fargate), you must choose `ip` as the target type, not `instance`. This is because tasks that use the `awsvpc` network mode are associated with an elastic network interface, not an Amazon EC2 instance.
You cannot register instances by instance ID if they have the following instance types: C1, CC1, CC2, CG1, CG2, CR1, G1, G2, HI1, HS1, M1, M2, M3, and T1. You can register instances of these types by IP address.
# Use a Gateway Load Balancer for Amazon ECS
A Gateway Load Balancer operates at the third layer of the Open Systems Interconnection (OSI) model, the network layer. It listens for all IP packets across all ports and forwards traffic to the target group that's specified in the listener rule. It maintains stickiness of flows to a specific target appliance using 5-tuple (for TCP/UDP flows) or 3-tuple (for non-TCP/UDP flows). For example, if your task's container definition specifies port 80 for an NGINX container port, and port 0 for the host port, then the host port is dynamically chosen from the ephemeral port range of the container instance (such as 32768 to 61000 on the latest Amazon ECS-optimized AMI). When the task is launched, the NGINX container is registered with the Gateway Load Balancer as an instance ID and port combination, and traffic is distributed to the instance ID and port corresponding to that container. This dynamic mapping allows you to have multiple tasks from a single service on the same container instance. For more information, see [What is a Gateway Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/gateway/introduction.html) in *Gateway Load Balancers*.
For information about the best practices for setting parameters to speed up you deployments see:
+ [Optimize load balancer health check parameters for Amazon ECS](load-balancer-healthcheck.md)
+ [Optimize load balancer connection draining parameters for Amazon ECS](load-balancer-connection-draining.md)
Consider the following when using Gateway Load Balancers with Amazon ECS:
+ Amazon ECS requires the service-linked IAM role which provides the permissions needed to register and deregister targets with your load balancer when tasks are created and stopped. For more information, see [Using service-linked roles for Amazon ECS](using-service-linked-roles.md).
+ For services in an IPv6-only configuration, you must set the target group IP address type of the Gateway Load Balancer to `dualstack`.
+ For services with tasks that use a network mode other than `awsvpc`, Gateway Load Balancers are not supported.
+ Your load balancer subnet configuration must include all Availability Zones that your container instances reside in.
+ After you create a service, the load balancer configuration can't be changed from the AWS Management Console. You can use the AWS Copilot, AWS CloudFormation, AWS CLI or SDK to modify the load balancer configuration for the `ECS` rolling deployment controller only, not AWS CodeDeploy blue/green or external. When you add, update, or remove a load balancer configuration, Amazon ECS starts a new deployment with the updated Elastic Load Balancing configuration. This causes tasks to register to and deregister from load balancers. We recommend that you verify this on a test environment before you update the Elastic Load Balancing configuration. For information about how to modify the configuration, see [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html) in the *Amazon Elastic Container Service API Reference*.
+ If a service task fails the load balancer health check criteria, the task is stopped and restarted. This process continues until your service reaches the number of desired running tasks.
+ When you use a Gateway Load Balancer configured with IP addresses as targets, requests are seen as coming from the Gateway Load Balancers private IP address. This means that services behind an Gateway Load Balancer are effectively open to the world as soon as you allow incoming requests and health checks in the target security group.
+ For Fargate tasks, you must use platform version `1.4.0` (Linux) or `1.0.0` (Windows).
+ If you are experiencing problems with your load balancer-enabled services, see [Troubleshooting service load balancers in Amazon ECS](troubleshoot-service-load-balancers.md).
+ When using `instance` target type, your tasks and load balancer must be in the same VPC. When using `ip` target type, cross-VPC connectivity is supported.
+ Use a unique target group for each service.
Using the same target group for multiple services might lead to issues during service deployments.
+ You must specify target groups that are associated with a Gateway Load Balancer.
For information about how to create a Gateway Load Balancer, see [Getting started with Gateway Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/gateway/getting-started.html) in *Gateway Load Balancers *
**Important**
If your service's task definition uses the `awsvpc` network mode (which is required for Fargate), you must choose `ip` as the target type, not `instance`. This is because tasks that use the `awsvpc` network mode are associated with an elastic network interface, not an Amazon EC2 instance.
You cannot register instances by instance ID if they have the following instance types: C1, CC1, CC2, CG1, CG2, CR1, G1, G2, HI1, HS1, M1, M2, M3, and T1. You can register instances of these types by IP address.
# Registering multiple target groups with an Amazon ECS service
Your Amazon ECS service can serve traffic from multiple load balancers and expose multiple load balanced ports when you specify multiple target groups in a service definition.
To create a service specifying multiple target groups, you must create the service using the Amazon ECS API, SDK, AWS CLI, or an CloudFormation template. After the service is created, you can view the service and the target groups registered to it with the AWS Management Console. You must use `[UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html)` to modify the load balancer configuration of an existing service.
Multiple target groups can be specified in a service definition using the following format. For the full syntax of a service definition, see [Service definition template](sd-template.md).
```
"loadBalancers":[
{
"targetGroupArn":"arn:aws:elasticloadbalancing:region:123456789012:targetgroup/target_group_name_1/1234567890123456",
"containerName":"container_name",
"containerPort":container_port
},
{
"targetGroupArn":"arn:aws:elasticloadbalancing:region:123456789012:targetgroup/target_group_name_2/6543210987654321",
"containerName":"container_name",
"containerPort":container_port
}
]
```
## Considerations
The following should be considered when you specify multiple target groups in a service definition.
+ For services that use an Application Load Balancer or Network Load Balancer, you cannot attach more than five target groups to a service.
+ Specifying multiple target groups in a service definition is only supported under the following conditions:
+ The service must use either an Application Load Balancer or Network Load Balancer.
+ The service must use the (`ECS`) deployment controller type. This can be either the Amazon ECS native/blue green deployment, or the rolling update deployment.
+ Specifying multiple target groups is supported for services containing tasks using both the Fargate and EC2 launch types.
+ When creating a service that specifies multiple target groups, the Amazon ECS service-linked role must be created. The role is created by omitting the `role` parameter in API requests, or the `Role` property in CloudFormation. For more information, see [Using service-linked roles for Amazon ECS](using-service-linked-roles.md).
## Example service definitions
Following are a few example use cases for specifying multiple target groups in a service definition. For the full syntax of a service definition, see [Service definition template](sd-template.md).
### Having separate load balancers for internal and external traffic
In the following use case, a service uses two separate load balancers, one for internal traffic and a second for internet-facing traffic, for the same container and port.
```
"loadBalancers":[
//Internal ELB
{
"targetGroupArn":"arn:aws:elasticloadbalancing:region:123456789012:targetgroup/target_group_name_1/1234567890123456",
"containerName":"nginx",
"containerPort":8080
},
//Internet-facing ELB
{
"targetGroupArn":"arn:aws:elasticloadbalancing:region:123456789012:targetgroup/target_group_name_2/6543210987654321",
"containerName":"nginx",
"containerPort":8080
}
]
```
### Exposing multiple ports from the same container
In the following use case, a service uses one load balancer but exposes multiple ports from the same container. For example, a Jenkins container might expose port 8080 for the Jenkins web interface and port 50000 for the API.
```
"loadBalancers":[
{
"targetGroupArn":"arn:aws:elasticloadbalancing:region:123456789012:targetgroup/target_group_name_1/1234567890123456",
"containerName":"jenkins",
"containerPort":8080
},
{
"targetGroupArn":"arn:aws:elasticloadbalancing:region:123456789012:targetgroup/target_group_name_2/6543210987654321",
"containerName":"jenkins",
"containerPort":50000
}
]
```
### Exposing ports from multiple containers
In the following use case, a service uses one load balancer and two target groups to expose ports from separate containers.
```
"loadBalancers":[
{
"targetGroupArn":"arn:aws:elasticloadbalancing:region:123456789012:targetgroup/target_group_name_1/1234567890123456",
"containerName":"webserver",
"containerPort":80
},
{
"targetGroupArn":"arn:aws:elasticloadbalancing:region:123456789012:targetgroup/target_group_name_2/6543210987654321",
"containerName":"database",
"containerPort":3306
}
]
```