Edit target group attributes for your Network Load Balancer - Elastic Load Balancing

Edit target group attributes for your Network Load Balancer

After you create a target group for you Network Load Balancer, you can edit its target group attributes.

Client IP preservation

Network Load Balancers can preserve the source IP address of clients when routing requests to backend targets. When you disable client IP preservation, the source IP address is the private IP address of the Network Load Balancer.

By default, client IP preservation is enabled (and can't be disabled) for instance and IP type target groups with UDP and TCP_UDP protocols. However, you can enable or disable client IP preservation for TCP and TLS target groups using the preserve_client_ip.enabled target group attribute.

Default settings
  • Instance type target groups: Enabled

  • IP type target groups (UDP, TCP_UDP): Enabled

  • IP type target groups (TCP, TLS): Disabled

Requirements and considerations
  • When client IP preservation is enabled, the traffic must flow directly from the Network Load Balancer to the target. The target must be located in the same VPC as the Network Load Balancer or in a peered VPC in the same region.

  • Client IP preservation is not supported when using a Gateway Load Balancer endpoint to inspect traffic between the Network Load Balancer and the target (instance or IP), even if the target is in the same Amazon VPC as the Network Load Balancer.

  • The following instance types do not support client IP preservation: C1, CC1, CC2, CG1, CG2, CR1, G1, G2, HI1, HS1, M1, M2, M3, and T1. We recommend that you register these instance types as IP addresses with client IP preservation disabled.

  • Client IP preservation has no effect on inbound traffic from AWS PrivateLink. The source IP of the AWS PrivateLink traffic is always the private IP address of the Network Load Balancer.

  • Client IP preservation is not supported when a target group contains AWS PrivateLink ENIs, or the ENI of another Network Load Balancer. This will cause loss of communication to those targets.

  • Client IP preservation has no effect on traffic converted from IPv6 to IPv4. The source IP of this type of traffic is always the private IP address of the Network Load Balancer.

  • When you specify targets by Application Load Balancer type, the client IP of all incoming traffic is preserved by the Network Load Balancer and is sent to the Application Load Balancer. The Application Load Balancer then appends the client IP to the X-Forwarded-For request header before sending it to the target.

  • Client IP preservation changes take effect only for new TCP connections.

  • NAT loopback, also known as hairpinning, is not supported when client IP preservation is enabled. This occurs when using internal Network Load Balancers, and the target registered behind a Network Load Balancer creates connections to the same Network Load Balancer. The connection can be routed to the target which is attempting to create the connection, leading to connection errors. We recommend not connecting to a Network Load Balancer from targets behind same Network Load Balancer, alternatively you can also prevent this type of connection error by disabling client IP preservation. If you need the client IP you can use retrieve it using Proxy Protocol v2. To learn more about Proxy Protocol, see Proxy protocol.

  • When client IP preservation is disabled, a Network Load Balancer supports 55,000 simultaneous connections or about 55,000 connections per minute to each unique target (IP address and port). If you exceed these connections, there is an increased chance of port allocation errors, resulting in failures to establish new connections. Port allocation errors can be tracked using the PortAllocationErrorCount metric. To fix port allocation errors, add more targets to the target group. For more information, see CloudWatch metrics for your Network Load Balancer.

To configure client IP preservation using the console
  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the navigation pane, under Load Balancing, choose Target Groups.

  3. Choose the name of the target group to open its details page.

  4. On the Attributes tab, choose Edit.

  5. To enable client IP preservation, turn on Preserve client IP addresses. To disable client IP preservation, turn off Preserve client IP addresses.

  6. Choose Save changes.

To enable or disable client IP preservation using the AWS CLI

Use the modify-target-group-attributes command with the preserve_client_ip.enabled attribute.

For example, use the following command to disable client IP preservation.

aws elbv2 modify-target-group-attributes --attributes Key=preserve_client_ip.enabled,Value=false --target-group-arn ARN

Your output should be similar to the following example.

{ "Attributes": [ { "Key": "proxy_protocol_v2.enabled", "Value": "false" }, { "Key": "preserve_client_ip.enabled", "Value": "false" }, { "Key": "deregistration_delay.timeout_seconds", "Value": "300" } ] }

Deregistration delay

When a target is deregistered, the load balancer stops creating new connections to the target. The load balancer uses connection draining to ensure that in-flight traffic completes on the existing connections. If the deregistered target stays healthy and an existing connection is not idle, the load balancer can continue to send traffic to the target. To ensure that existing connections are closed, you can do one of the following: enable the target group attribute for connection termination, ensure that the instance is unhealthy before you deregister it, or periodically close client connections.

The initial state of a deregistering target is draining, during which the target will stop receiving new connections. However, the target may still receive connections due to configuration propagation delay. By default, the load balancer changes the state of a deregistering target to unused after 300 seconds. To change the amount of time that the load balancer waits before changing the state of a deregistering target to unused, update the deregistration delay value. We recommend that you specify a value of at least 120 seconds to ensure that requests are completed.

If you enable the target group attribute for connection termination, connections to deregistered targets are closed shortly after the end of the deregistration timeout.

To update the deregistration attributes using the console
  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the navigation pane, under Load Balancing, choose Target Groups.

  3. Choose the name of the target group to open its details page.

  4. On Attributes tab, choose Edit.

  5. To change the deregistration timeout, enter a new value for Deregistration delay. To ensure that existing connections are closed after you deregister targets, select Terminate connections on deregistration.

  6. Choose Save changes.

To update the deregistration attributes using the AWS CLI

Use the modify-target-group-attributes command.

Proxy protocol

Network Load Balancers use proxy protocol version 2 to send additional connection information such as the source and destination. Proxy protocol version 2 provides a binary encoding of the proxy protocol header. With TCP listeners, the load balancer prepends a proxy protocol header to the TCP data. It does not discard or overwrite any existing data, including any incoming proxy protocol headers sent by the client or any other proxies, load balancers, or servers in the network path. Therefore, it is possible to receive more than one proxy protocol header. Also, if there is another network path to your targets outside of your Network Load Balancer, the first proxy protocol header might not be the one from your Network Load Balancer.

If you specify targets by IP address, the source IP addresses provided to your applications depend on the protocol of the target group as follows:

  • TCP and TLS: By default, client IP preservation is disabled, and the source IP addresses provided to your applications are the private IP addresses of the load balancer nodes. To preserve the client's IP address, ensure that the target is located within the same VPC or a peered VPC and enable client IP preservation. If you need the IP address of the client and these conditions are not met, enable the proxy protocol and get the client IP address from the proxy protocol header.

  • UDP and TCP_UDP: The source IP addresses are the IP addresses of the clients, as client IP preservation is enabled by default for these protocols and cannot be disabled. If you specify targets by instance ID, the source IP addresses provided to your applications are the client IP addresses. However, if you prefer, you can enable proxy protocol and get the client IP addresses from the proxy protocol header.

If you specify targets by instance ID, the source IP addresses provided to your applications are the client IP addresses. However, if you prefer, you can enable proxy protocol and get the client IP addresses from the proxy protocol header.

Note

TLS listeners do not support incoming connections with proxy protocol headers sent by the client or any other proxies.

Health check connections

After you enable proxy protocol, the proxy protocol header is also included in health check connections from the load balancer. However, with health check connections, the client connection information is not sent in the proxy protocol header.

VPC endpoint services

For traffic coming from service consumers through a VPC endpoint service, the source IP addresses provided to your applications are the private IP addresses of the load balancer nodes. If your applications need the IP addresses of the service consumers, enable proxy protocol and get them from the proxy protocol header.

The proxy protocol header also includes the ID of the endpoint. This information is encoded using a custom Type-Length-Value (TLV) vector as follows.

Field Length (in octets) Description

Type

1

PP2_TYPE_AWS (0xEA)

Length

2

The length of value

Value

1

PP2_SUBTYPE_AWS_VPCE_ID (0x01)

variable (value length minus 1) The ID of the endpoint

For an example that parses TLV type 0xEA, see https://github.com/aws/elastic-load-balancing-tools/tree/master/proprot.

Enable proxy protocol

Before you enable proxy protocol on a target group, make sure that your applications expect and can parse the proxy protocol v2 header, otherwise, they might fail. For more information, see PROXY protocol versions 1 and 2.

To enable proxy protocol v2 using the console
  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the navigation pane, under Load Balancing, choose Target Groups.

  3. Choose the name the target group to open its details page.

  4. On the Attributes tab, choose Edit.

  5. On the Edit attributes page, select Proxy protocol v2.

  6. Choose Save changes.

To enable proxy protocol v2 using the AWS CLI

Use the modify-target-group-attributes command.

Sticky sessions

Sticky sessions are a mechanism to route client traffic to the same target in a target group. This is useful for servers that maintain state information in order to provide a continuous experience to clients.

Considerations
  • Using sticky sessions can lead to an uneven distribution of connections and flows, which might impact the availability of your targets. For example, all clients behind the same NAT device have the same source IP address. Therefore, all traffic from these clients is routed to the same target.

  • The load balancer might reset the sticky sessions for a target group if the health state of any of its targets changes or if you register or deregister targets with the target group.

  • When the stickiness attribute is turned on for a target group, passive health checks are not supported. For more information, see Health checks for your target groups.

  • Sticky sessions are not supported for TLS listeners.

To enable sticky sessions using the console
  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the navigation pane, under Load Balancing, choose Target Groups.

  3. Choose the name of the target group to open its details page.

  4. On the Attributes tab, choose Edit.

  5. Under Target selection configuration, turn on Stickiness.

  6. Choose Save changes.

To enable sticky sessions using the AWS CLI

Use the modify-target-group-attributes command with the stickiness.enabled attribute.

Cross-zone load balancing for target groups

The nodes for your load balancer distribute requests from clients to registered targets. When cross-zone load balancing is on, each load balancer node distributes traffic across the registered targets in all registered Availability Zones. When cross-zone load balancing is off, each load balancer node distributes traffic across only the registered targets in its Availability Zone. This could be used if zonal failure domains are preferred over regional, ensuring that a healthy zone isn't impacted by an unhealthy zone, or for overall latency improvements.

With Network Load Balancers, cross-zone load balancing is off by default at the load balancer level, but you can turn it on at any time. For target groups, the default is to use the load balancer setting, but you can override the default by explicitly turning cross-zone load balancing on or off at the target group level.

Considerations
  • When enabling cross-zone load balancing for a Network Load Balancer, EC2 data transfer charges apply. For more information, see Understanding data transfer charges in the AWS Data Exports User Guide

  • The target group setting determines the load balancing behavior for the target group. For example, if cross-zone load balancing is enabled at the load balancer level and disabled at the target group level, traffic sent to the target group is not routed across Availability Zones.

  • When cross-zone load balancing is off, ensure that you have enough target capacity in each of the load balancer Availability Zones, so that each zone can serve its associated workload.

  • When cross-zone load balancing is off, ensure that all target groups participate in the same Availability Zones. An empty Availability Zone is considered unhealthy.

Modify cross-zone load balancing for a load balancer

You can turn cross-zone load balancing on or off at the load balancer level at any time.

To modify cross-zone load balancing for a load balancer using the console
  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, under Load Balancing, choose Load Balancers.

  3. Select the name of the load balancer to open its details page.

  4. On the Attributes tab, choose Edit.

  5. On the Edit load balancer attributes page, turn Cross-zone load balancing on or off.

  6. Choose Save changes.

To modify cross-zone load balancing for your load balancer using the AWS CLI

Use the modify-load-balancer-attributes command with the load_balancing.cross_zone.enabled attribute.

Modify cross-zone load balancing for a target group

The cross-zone load balancing setting at the target group level overrides the setting at the load balancer level.

You can turn cross-zone load balancing on or off at the target group level if the target group type is instance or ip. If the target group type is alb, the target group always inherits the cross-zone load balancing setting from the load balancer.

To modify cross-zone load balancing for a target group using the console
  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the navigation pane, under Load Balancing, select Target Groups.

  3. Select the name of the target group to open its details page.

  4. On the Attributes tab, choose Edit.

  5. On the Edit target group attributes page, select On for Cross-zone load balancing.

  6. Choose Save changes.

To modify cross-zone load balancing for a target group using the AWS CLI

Use the modify-target-group-attributes command with the load_balancing.cross_zone.enabled attribute.

Connection termination for unhealthy targets

Connection termination is enabled by default. When the target of a Network Load Balancer fails the configured health checks and is deemed unhealthy, the load balancer terminates established connections and stops routing new connections to the target. With connection termination disabled the target is still considered unhealthy and won't receive new connections, but established connections are kept active, allowing them to gracefully close.

Connection termination for unhealthy targets can be set individually for each target group.

To modify the connection termination setting using the console
  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, under Load Balancing, choose Target Groups.

  3. Choose the name of the target group to open its details page.

  4. On the Attributes tab, choose Edit.

  5. Under Target unhealthy state management, choose whether Terminate connections when targets become unhealthy is enabled or disabled.

  6. Choose Save changes.

To modify the connection termination setting using the AWS CLI

Use the modify-target-group-attributes command with the target_health_state.unhealthy.connection_termination.enabled attribute.

Unhealthy draining interval

Important

Connection termination must be disabled before enabling unhealthy draining interval.

Targets in the unhealthy.draining state are considered unhealthy, do not receive new connections, but retain established connections for the configured interval. The unhealthy connection interval determines the amount of time the target remains in the unhealthy.draining state before it's state becomes unhealthy. If the target passes health checks during the unhealthy connection interval, it's state becomes healthy again. If a deregistration is triggered, the targets state becomes draining and the deregistration delay timeout begins.

The unhealthy draining interval can be set individually for each target group.

To modify the unhealthy draining interval using the console
  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, under Load Balancing, choose Target Groups.

  3. Choose the name of the target group to open its details page.

  4. On the Attributes tab, choose Edit.

  5. Under Target unhealthy state management, make sure Terminate connections when targets become unhealthy is turned off.

  6. Enter a value for Unhealthy draining interval.

  7. Choose Save changes.

To modify the unhealthy draining interval using the AWS CLI

Use the modify-target-group-attributes command with the target_health_state.unhealthy.draining_interval_seconds attribute.