Use Service Annotations to configure Network Load Balancers
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.
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/nlb
Commonly 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: | proxy_protocol.v2.enabled=true access_logs.s3.enabled=true access_logs.s3.bucket=my-bucket access_logs.s3.prefix=my-prefix load_balancing.cross_zone.enabled=true
This 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 |