Annotations

Service annotations

Annotations

Name	Type	Default	Notes
service.beta.kubernetes.io/load-balancer-source-ranges	stringList
service.beta.kubernetes.io/aws-load-balancer-security-group-prefix-lists	stringList
service.beta.kubernetes.io/aws-load-balancer-type	string
service.beta.kubernetes.io/aws-load-balancer-nlb-target-type	string		default instance in case of LoadBalancerClass
service.beta.kubernetes.io/aws-load-balancer-name	string
service.beta.kubernetes.io/aws-load-balancer-internal	boolean	false	deprecated, in favor of aws-load-balancer-scheme
service.beta.kubernetes.io/aws-load-balancer-scheme	string	internal
service.beta.kubernetes.io/aws-load-balancer-proxy-protocol	string		Set to "*" to enable
service.beta.kubernetes.io/aws-load-balancer-proxy-protocol-per-target-group	string		If specified,configures proxy protocol for the target groups corresponding to the ports mentioned and disables for the rest. For example, if you have services deployed on ports "80, 443 and 22", the annotation value "80, 443" will enable proxy protocol for ports 80 and 443 only, and disable for port 22. This annotation is overriden by "service.beta.kubernetes.io/aws-load-balancer-proxy-protocol"
service.beta.kubernetes.io/aws-load-balancer-ip-address-type	string	ipv4	ipv4 | dualstack
service.beta.kubernetes.io/aws-load-balancer-access-log-enabled	boolean	false	deprecated, in favor of aws-load-balancer-attributes
service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name	string		deprecated, in favor of aws-load-balancer-attributes
service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix	string		deprecated, in favor of aws-load-balancer-attributes
service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled	boolean	false	deprecated, in favor of aws-load-balancer-attributes
service.beta.kubernetes.io/aws-load-balancer-ssl-cert	stringList
service.beta.kubernetes.io/aws-load-balancer-ssl-ports	stringList
service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy	string	ELBSecurityPolicy-2016-08
service.beta.kubernetes.io/aws-load-balancer-backend-protocol	string
service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags	stringMap
service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol	string	TCP
service.beta.kubernetes.io/aws-load-balancer-healthcheck-port	integer | traffic-port	traffic-port
service.beta.kubernetes.io/aws-load-balancer-healthcheck-path	string	"/" for HTTP(S) protocols
service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold	integer	3
service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold	integer	3
service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout	integer	10
service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval	integer	10
service.beta.kubernetes.io/aws-load-balancer-healthcheck-success-codes	string	200-399
service.beta.kubernetes.io/aws-load-balancer-eip-allocations	stringList		internet-facing lb only. Length must match the number of subnets
service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses	stringList		internal lb only. Length must match the number of subnets
service.beta.kubernetes.io/aws-load-balancer-ipv6-addresses	stringList		dualstack lb only. Length must match the number of subnets
service.beta.kubernetes.io/aws-load-balancer-target-group-attributes	stringMap
service.beta.kubernetes.io/aws-load-balancer-subnets	stringList
service.beta.kubernetes.io/aws-load-balancer-alpn-policy	string
service.beta.kubernetes.io/aws-load-balancer-target-node-labels	stringMap
service.beta.kubernetes.io/aws-load-balancer-attributes	stringMap
service.beta.kubernetes.io/aws-load-balancer-security-groups	stringList
service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules	boolean	true	If service.beta.kubernetes.io/aws-load-balancer-security-groups is specified, this must also be explicitly specified otherwise it defaults to false.
service.beta.kubernetes.io/aws-load-balancer-inbound-sg-rules-on-private-link-traffic	string
service.beta.kubernetes.io/aws-load-balancer-listener-attributes.${Protocol}-${Port}	stringMap
service.beta.kubernetes.io/aws-load-balancer-multi-cluster-target-group	boolean	false	If specified, the controller will only operate on targets that exist within the cluster, ignoring targets from other sources.
service.beta.kubernetes.io/aws-load-balancer-enable-prefix-for-ipv6-source-nat	string	off	Optional annotation. dualstack lb only. Allowed values - on and off
service.beta.kubernetes.io/aws-load-balancer-source-nat-ipv6-prefixes	stringList		Optional annotation. dualstack lb only. This annotation is only applicable when user has to set the service.beta.kubernetes.io/aws-load-balancer-enable-prefix-for-ipv6-source-nat to "on". Length must match the number of subnets
service.beta.kubernetes.io/aws-load-balancer-minimum-load-balancer-capacity	stringMap
service.beta.kubernetes.io/aws-load-balancer-enable-icmp-for-path-mtu-discovery	string		If specified, a security group rule is added to the managed security group to allow explicit ICMP traffic for Path MTU discovery for IPv4 and dual-stack VPCs. Creates a rule for each source range if service.beta.kubernetes.io/load-balancer-source-ranges is present.
service.beta.kubernetes.io/aws-load-balancer-enable-tcp-udp-listener	boolean	false	If specified, the controller will attempt to try TCP_UDP Listeners when the service defines a TCP and UDP port on the same port number.

Traffic Routing

Traffic Routing can be controlled with following annotations:

• service.beta.kubernetes.io/aws-load-balancer-name specifies the custom name to use for the load balancer. Name longer than 32 characters will be treated as an error.

• service.beta.kubernetes.io/aws-load-balancer-type specifies the load balancer type. This controller reconciles those service resources with this annotation set to either nlb-ip or external.

• service.beta.kubernetes.io/aws-load-balancer-nlb-target-type specifies the target type to configure for NLB. You can choose between instance and ip.

  • instance mode will route traffic to all EC2 instances within cluster on the NodePort opened for your service. The kube-proxy on the individual worker nodes sets up the forwarding of the traffic from the NodePort to the pods behind the service.

  • ip mode will route traffic directly to the pod IP. In this mode, AWS NLB sends traffic directly to the Kubernetes pods behind the service, eliminating the need for an extra network hop through the worker nodes in the Kubernetes cluster.

• service.beta.kubernetes.io/aws-load-balancer-subnets specifies the Availability Zone the NLB will route traffic to. See Network Load Balancers for more details.

• service.beta.kubernetes.io/aws-load-balancer-alpn-policy allows you to configure the ALPN policies on the load balancer.

• service.beta.kubernetes.io/aws-load-balancer-target-node-labels specifies which nodes to include in the target group registration for instance target type.

• service.beta.kubernetes.io/aws-load-balancer-eip-allocations specifies a list of elastic IP address configuration for an internet-facing NLB.

• service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses specifies a list of private IPv4 addresses for an internal NLB.

• service.beta.kubernetes.io/aws-load-balancer-ipv6-addresses specifies a list of IPv6 addresses for an dualstack NLB.

• service.beta.kubernetes.io/aws-load-balancer-enable-icmp-for-path-mtu-discovery enables the creation of security group rules to the managed security group to allow explicit ICMP traffic for Path MTU discovery for IPv4 and dual-stack VPCs. Creates a rule for each source range if service.beta.kubernetes.io/load-balancer-source-ranges is present.

Traffic Listening

Traffic Listening can be controlled with following annotations:

• service.beta.kubernetes.io/aws-load-balancer-ip-address-type specifies the IP address type of NLB.

Support UDP-based services over IPv6

You can configure dualstack NLB to support UDP-based services over IPv6 via the following annotations:

• service.beta.kubernetes.io/aws-load-balancer-enable-prefix-for-ipv6-source-nat specifies whether Prefix for IPv6 source NAT is enabled or not. UDP-based support can be enabled for dualstack NLBs only if Prefix for IPv6 source NAT is enabled.

• service.beta.kubernetes.io/aws-load-balancer-source-nat-ipv6-prefixes specifies a list of IPv6 prefixes that should be used for IPv6 source NATing.

Resource attributes

NLB resource attributes can be controlled via the following annotations:

• service.beta.kubernetes.io/aws-load-balancer-proxy-protocol specifies whether to enable proxy protocol v2 on the target group. Set to '*' to enable proxy protocol v2. This annotation takes precedence over the annotation service.beta.kubernetes.io/aws-load-balancer-target-group-attributes for proxy protocol v2 configuration.

• service.beta.kubernetes.io/aws-load-balancer-target-group-attributes specifies the Target Group Attributes to be configured.

• service.beta.kubernetes.io/aws-load-balancer-attributes specifies Load Balancer Attributes that should be applied to the NLB.

• service.beta.kubernetes.io/aws-load-balancer-listener-attributes.${Protocol}-${Port} specifies listener attributes that should be applied to the listener.

• service.beta.kubernetes.io/aws-load-balancer-enable-tcp-udp-listener allows creation of TCP_UDP listener type when the service defines a TCP and UDP port on the same port number.

!!!note "" - To change the default from false to true, use the controller flag --feature-gates=EnableTCPUDPListener=true to allow creation of TCP_UDP listeners for all services. !!!example - Allow for the creation of TCP_UDP listeners for a service.

service.beta.kubernetes.io/aws-load-balancer-enable-tcp-udp-listener: "true"

• the following annotations are deprecated in v2.3.0 release in favor of service.beta.kubernetes.io/aws-load-balancer-attributes

• service.beta.kubernetes.io/aws-load-balancer-multi-cluster-target-group Allows you to share the created Target Group ARN with other Load Balancer Controller managed clusters.

  This feature does not offer any Deletion Protection. Deleting the service will still delete the Target Group. If you need to support Target Groups shared with multiple clusters, it's recommended to use an out-of-band Target Group that is not managed by a Load Balancer Controller.

  • It is not recommended to change this value frequently, if ever. The recommended way to set this value is on creation of the service.

  service.beta.kubernetes.io/aws-load-balancer-multi-cluster-target-group: "true"
  

AWS Resource Tags

The AWS Load Balancer Controller automatically applies following tags to the AWS resources it creates (NLB/TargetGroups/Listener/ListenerRule):

• elbv2.k8s.aws/cluster: ${clusterName}
• service.k8s.aws/stack: ${stackID}
• service.k8s.aws/resource: ${resourceID}

In addition, you can use annotations to specify additional tags

• service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags specifies additional tags to apply to the AWS resources.

Health Check

Health check on target groups can be configured with following annotations:

• service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol specifies the target group health check protocol.

• service.beta.kubernetes.io/aws-load-balancer-healthcheck-port specifies the TCP port to use for target group health check.

• service.beta.kubernetes.io/aws-load-balancer-healthcheck-path specifies the http path for the health check in case of http/https protocol.

• service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold specifies the consecutive health check successes required before a target is considered healthy.

• service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold specifies the consecutive health check failures before a target gets marked unhealthy.

• service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval specifies the interval between consecutive health checks.

• service.beta.kubernetes.io/aws-load-balancer-healthcheck-success-codes specifies the http success codes for the health check in case of http/https protocol.

• service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout specifies the target group health check timeout. The target has to respond within the timeout for a successful health check.

TLS

You can configure TLS support via the following annotations:

• service.beta.kubernetes.io/aws-load-balancer-ssl-cert specifies the ARN of one or more certificates managed by the AWS Certificate Manager.

• service.beta.kubernetes.io/aws-load-balancer-ssl-ports specifies the frontend ports with TLS listeners.

• service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy specifies the Security Policy for NLB frontend connections, allowing you to control the protocol and ciphers.

• service.beta.kubernetes.io/aws-load-balancer-backend-protocol specifies whether to use TLS for the backend traffic between the load balancer and the kubernetes pods.

Access control

Load balancer access can be controlled via following annotations:

• service.beta.kubernetes.io/load-balancer-source-ranges specifies the CIDRs that are allowed to access the NLB.

• service.beta.kubernetes.io/aws-load-balancer-security-group-prefix-lists specifies the managed prefix lists that are allowed to access the NLB.

• service.beta.kubernetes.io/aws-load-balancer-scheme specifies whether the NLB will be internet-facing or internal. Valid values are internal, internet-facing. If not specified, default is internal.

• service.beta.kubernetes.io/aws-load-balancer-internal specifies whether the NLB will be internet-facing or internal.

  • service.beta.kubernetes.io/aws-load-balancer-security-groups specifies the frontend securityGroups you want to attach to an NLB.

• service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules specifies whether the controller should automatically add the ingress rules to the instance/ENI security group.

• service.beta.kubernetes.io/aws-load-balancer-inbound-sg-rules-on-private-link-traffic specifies whether to apply security group rules to traffic sent to the load balancer through AWS PrivateLink.

Capacity Unit Reservation

Load balancer capacity unit reservation can be configured via following annotations:

• service.beta.kubernetes.io/aws-load-balancer-minimum-load-balancer-capacity specifies the Capacity Unit Reservation to be configured.

Legacy Cloud Provider

The AWS Load Balancer Controller manages Kubernetes Services in a compatible way with the AWS cloud provider's legacy service controller.

• For users on v2.5.0+, The AWS LBC provides a mutating webhook for service resources to set the spec.loadBalancerCLass field for Serive of type LoadBalancer, effectively making the AWS LBC the default controller for Service of type LoadBalancer. Users can disable this feature and revert to using the AWS Cloud Controller Manager as the default service controller by setting the helm chart value enableServiceMutatorWebhook to false with --set enableServiceMutatorWebhook=false .
• For users on older versions, the annotation service.beta.kubernetes.io/aws-load-balancer-type is used to determine which controller reconciles the service. If the annotation value is nlb-ip or external, recent versions of the legacy cloud provider ignore the Service resource so that the AWS LBC can take over. For all other values of the annotation, the legacy cloud provider will handle the service. Note that this annotation should be specified during service creation and not edited later. Support for the annotation was added to the legacy cloud provider in Kubernetes v1.20, and is backported to v1.18.18+ and v1.19.10+.