Help improve this page
To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.
Learn how to configure Network Load Balancers (NLB) in Amazon EKS using Kubernetes service annotations. This topic explains the annotations supported by EKS Auto Mode for customizing NLB behavior, including internet accessibility, health checks, SSL/TLS termination, and IP targeting modes.
When you create a Kubernetes service of type LoadBalancer in EKS Auto Mode, EKS automatically provisions and configures an AWS Network Load Balancer based on the annotations you specify. This declarative approach allows you to manage load balancer configurations directly through your Kubernetes manifests, maintaining infrastructure as code practices.
EKS Auto Mode handles Network Load Balancer provisioning by default for all services of type LoadBalancer - no additional controller installation or configuration is required. The loadBalancerClass: eks.amazonaws.com/nlb specification is automatically set as the cluster default, streamlining the deployment process while maintaining compatibility with existing Kubernetes workloads.
Note
EKS Auto Mode requires subnet tags to identify public and private subnets.
If you created your cluster with eksctl, you already have these tags.
Learn how to Tag subnets for EKS Auto Mode.
Sample Service
For more information about the Kubernetes Service resource, see the Kubernetes Documentation
Review the sample Service resource below:
apiVersion: v1
kind: Service
metadata:
name: echoserver
annotations:
# Specify the load balancer scheme as internet-facing to create a public-facing Network Load Balancer (NLB)
service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
spec:
selector:
app: echoserver
ports:
- port: 80
targetPort: 8080
protocol: TCP
type: LoadBalancer
# Specify the new load balancer class for NLB as part of EKS Auto Mode feature
# For clusters with Auto Mode enabled, this field can be omitted as it's the default
loadBalancerClass: eks.amazonaws.com/nlbCommonly used annotations
The following table lists commonly used annotations supported by EKS Auto Mode. Note that EKS Auto Mode may not support all annotations.
Tip
All of the following annotations need to be prefixed with service.beta.kubernetes.io/
| Field | Description | Example |
|---|---|---|
|
|
Specifies the load balancer type. Use |
|
|
|
Specifies whether to route traffic to node instances or directly to pod IPs. Use |
|
|
|
Controls whether the load balancer is internal or internet-facing. |
|
|
|
Health check protocol for target group. Common options are |
|
|
|
The HTTP path for health checks when using HTTP/HTTPS protocol. |
|
|
|
Port used for health checks. Can be a specific port number or |
|
|
|
Specifies which subnets to create the load balancer in. Can use subnet IDs or names. |
|
|
|
ARN of the SSL certificate from AWS Certificate Manager for HTTPS/TLS. |
|
|
|
Specifies which ports should use SSL/TLS. |
|
|
|
CIDR ranges allowed to access the load balancer. |
|
|
|
Additional AWS tags to apply to the load balancer and related resources. |
|
|
|
Specifies whether the load balancer uses IPv4 or dual-stack (IPv4 + IPv6). |
|
Considerations
-
You must update the Cluster IAM Role to enable tag propagation from Kubernetes to AWS Load Balancer resources. For more information, see Custom AWS tags for EKS Auto resources.
-
For information about associating resources with either EKS Auto Mode or the self-managed AWS Load Balancer Controller, see Migration Reference.
-
For information about fixing issues with load balancers, see Troubleshoot EKS Auto Mode.
-
For more considerations about using the load balancing capability of EKS Auto Mode, see Load balancing.
When migrating to EKS Auto Mode for load balancing, several changes in service annotations and resource configurations are necessary. The following tables outline key differences between previous and new implementations, including unsupported options and recommended alternatives.
Service annotations
| Previous | New | Description |
|---|---|---|
|
|
Not supported |
Use |
|
|
Not supported |
Use |
|
|
Not supported |
Use |
|
Various load balancer attributes |
Not supported |
Use |
|
|
Not supported |
Use |
|
|
Not supported |
Use |
|
|
Not supported |
Use |
|
|
Not supported |
Use |
|
|
Not supported |
Use |
To migrate from deprecated load balancer attribute annotations, consolidate these settings into the service.beta.kubernetes.io/aws-load-balancer-attributes annotation. This annotation accepts a comma-separated list of key-value pairs for various load balancer attributes. For example, to specify proxy protocol, access logging, and cross-zone load balancing, use the following format:
service.beta.kubernetes.io/aws-load-balancer-attributes: |
access_logs.s3.enabled=true
access_logs.s3.bucket=my-bucket
access_logs.s3.prefix=my-prefix
load_balancing.cross_zone.enabled=trueservice.beta.kubernetes.io/aws-load-balancer-target-group-attributes: |
proxy_protocol_v2.enabled=trueThis consolidated format provides a more consistent and flexible way to configure load balancer attributes while reducing the number of individual annotations needed. Review your existing Service configurations and update them to use this consolidated format.
TargetGroupBinding
| Previous | New | Description |
|---|---|---|
|
|
|
API version change |
|
|
|
Explicit target type specification |
|
|
Not supported |
No longer supports NLB without security groups |
