Annotations - AWS Load Balancer Controller (original) (raw)

Service annotations¶

• Annotation keys and values can only be strings. All other types below must be string-encoded, for example:
  • boolean: "true"
  • integer: "42"
  • stringList: "s1,s2,s3"
  • stringMap: "k1=v1,k2=v2"
  • json: "{ \"key\": \"value\" }"

Annotations¶

Warning

These annotations are specific to the kubernetes service resources reconciled by the AWS Load Balancer Controller. Although the list was initially derived from the k8s in-tree kube-controller-manager, this documentation is not an accurate reference for the services reconciled by the in-tree controller.

EKS Auto Mode users

If you are using EKS Auto Mode, please see theEKS Auto Mode documentationfor key differences between the load balancing capability of EKS Auto Mode and the open source load balancer controller.

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.
  limitations
  • If you modify this annotation after service creation, there is no effect.
    Example
    service.beta.kubernetes.io/aws-load-balancer-name: custom-name
• 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.
  Tip
  This annotation specifies the controller used to provision LoadBalancers (as specified in legacy-cloud-provider). Refer to lb-scheme to specify whether the LoadBalancer is internet-facing or internal.
  • [Deprecated] For type nlb-ip, the controller will provision an NLB with targets registered by IP address. This value is supported for backwards compatibility.
  • For type external, the NLB target type depends on the nlb-target-type annotation.
    limitations
  • This annotation should not be modified after service creation.
    Example
    service.beta.kubernetes.io/aws-load-balancer-type: external
• service.beta.kubernetes.io/aws-load-balancer-nlb-target-type specifies the target type to configure for NLB. You can choose betweeninstance 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.
    * service must be of type NodePort or LoadBalancer for instance targets
    * for k8s 1.22 and later if spec.allocateLoadBalancerNodePorts is set to false, NodePort must be allocated manually

  default value
  If you configure spec.loadBalancerClass, the controller defaults to instance target type
  NodePort allocation
  k8s version 1.22 and later support disabling NodePort allocation by setting the service field spec.allocateLoadBalancerNodePorts to false. If the NodePort is not allocated for a service port, the controller will fail to reconcile instance mode NLB.

  • 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.
    * ip target mode supports pods running on AWS EC2 instances and AWS Fargate
    * network plugin must use native AWS VPC networking configuration for pod IP, for example Amazon VPC CNI plugin.

Example
service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: instance

• service.beta.kubernetes.io/aws-load-balancer-subnets specifies the Availability Zonethe NLB will route traffic to. See Network Load Balancers for more details.
  Tip
  Subnets are auto-discovered if this annotation is not specified, see Subnet Discovery for further details.
  You must specify at least one subnet in any of the AZs, both subnetID or subnetName(Name tag on subnets) can be used.
  limitations
  • Each subnets must be from a different Availability Zone
  • Similar to any delete operation, removing an Availability Zone can be a potentially disruptive operation. We recommend you evaluate for any potential impact on existing connections, traffic flows, or production workloads. Refer to product documentation for prescriptive guidance on how to use this capability in a safe manner.
    Example
    service.beta.kubernetes.io/aws-load-balancer-subnets: subnet-xxxx, mySubnet
• service.beta.kubernetes.io/aws-load-balancer-alpn-policy allows you to configure the ALPN policieson the load balancer.
  supported policies
  • HTTP1Only Negotiate only HTTP/1.*. The ALPN preference list is http/1.1, http/1.0.
  • HTTP2Only Negotiate only HTTP/2. The ALPN preference list is h2.
  • HTTP2Optional Prefer HTTP/1.* over HTTP/2 (which can be useful for HTTP/2 testing). The ALPN preference list is http/1.1, http/1.0, h2.
  • HTTP2Preferred Prefer HTTP/2 over HTTP/1.*. The ALPN preference list is h2, http/1.1, http/1.0.
  • None Do not negotiate ALPN. This is the default.
    Example
    service.beta.kubernetes.io/aws-load-balancer-alpn-policy: HTTP2Preferred
• service.beta.kubernetes.io/aws-load-balancer-target-node-labels specifies which nodes to include in the target group registration for instance target type.
  Example
  service.beta.kubernetes.io/aws-load-balancer-target-node-labels: label1=value1, label2=value2
• service.beta.kubernetes.io/aws-load-balancer-eip-allocations specifies a list of elastic IP address configuration for an internet-facing NLB.
  Note
  • This configuration is optional, and you can use it to assign static IP addresses to your NLB
  • You must specify the same number of eip allocations as load balancer subnets annotation
  • NLB must be internet-facing
    Example
    service.beta.kubernetes.io/aws-load-balancer-eip-allocations: eipalloc-xyz, eipalloc-zzz
• service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses specifies a list of private IPv4 addresses for an internal NLB.
  Note
  • NLB must be internal
  • This configuration is optional, and you can use it to assign static IPv4 addresses to your NLB
  • You must specify the same number of private IPv4 addresses as load balancer subnets annotation
  • You must specify the IPv4 addresses from the load balancer subnet IPv4 ranges
    Example
    service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses: 192.168.10.15, 192.168.32.16
• service.beta.kubernetes.io/aws-load-balancer-ipv6-addresses specifies a list of IPv6 addresses for an dualstack NLB.
  Note
  • NLB must be dualstack
  • This configuration is optional, and you can use it to assign static IPv6 addresses to your NLB
  • You must specify the same number of private IPv6 addresses as load balancer subnets annotation
  • You must specify the IPv6 addresses from the load balancer subnet IPv6 ranges
    Example
    service.beta.kubernetes.io/aws-load-balancer-ipv6-addresses: 2600:1f13:837:8501::1, 2600:1f13:837:8504::1
• 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.
  Example
  service.beta.kubernetes.io/aws-load-balancer-enable-icmp-for-path-mtu-discovery: "on"
  • service.beta.kubernetes.io/actions.${protocol}-${port} provides a method for configuring the action on a listener on the specified port. It supports configuring weighted target groups.
    Note
  • Weighted target groups are supported for the following protocols: TCP, TLS, UDP, TCP_UDP
  • The baseServiceWeight is the weight of the target group associated with the implicit service
    Note
  • Forward actions on listeners can specify whether to enable target group stickiness. When enabled, target group stickiness causes subsequent connections from the same source IP address to prefer the previously chosen target group.
  • For listeners, if a forward action contains multiple target groups and any of them have stickiness enabled, then the forward action must also have target group stickiness enabled.
  • For TLS listeners, target group stickiness is not supported.
  • For TLS listeners, you can't add both TCP target groups and TLS target groups to the action. All target groups in the default action must use the same protocol.
  • For dualstack load balancers, you can't add both IPv4 target groups and IPv6 target groups to the same action. All target groups in the default action must use the same IP address type.
    Example
    service.beta.kubernetes.io/actions.TCP-80: { "type": "forward", "forwardConfig": { "baseServiceWeight": 10, "targetGroups": [ { "serviceName": "service-1", "servicePort": 81, "weight": 20 }, { "serviceName": "service-2", "servicePort": 82, "weight": 30 } ], "targetGroupStickinessConfig": { "enabled": true } } }

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.
  Example
  service.beta.kubernetes.io/aws-load-balancer-ip-address-type: ipv4

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.
  Note
  • Applicable to Network Load Balancers using dualstack IP address type.
  • This configuration is optional, and you can use it to enable UDP support over IPv6.
  • Allowed values are either “on” or “off”
  • Once the source prefix for source NATing is enabled, it cannot be disabled if load balancer has a UDP listener attached.
  • Steps to disable the aws-load-balancer-enable-prefix-for-ipv6-source-nat after it is enabled and UDP listeners already attached.
  • You will have to first remove the UDP listeners and apply the manifest.
  • Update the manifest to set source NATing to "off" and then apply the manifest again.
    Example
  • Enable prefix for IPv6 Source NAT
    service.beta.kubernetes.io/aws-load-balancer-enable-prefix-for-ipv6-source-nat: "on"
• 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.
  Note
  • Applicable to Network Load Balancers using dualstack IP address type.
  • This annotation can be specified only if service.beta.kubernetes.io/aws-load-balancer-enable-prefix-for-ipv6-source-nat annotation is set to “on”.
  • This configuration is optional and it can be used to specify custom IPv6 prefixes for IPv6 source NATing to support UDP based services routing in Network Load Balancers using dualstack IP address type.
  • If service.beta.kubernetes.io/aws-load-balancer-enable-prefix-for-ipv6-source-nat annotation is set to “on”, and you don’t specify this annotation, then IPv6 prefix/CIDR for source NATing will be auto-assigned to each subnet.
  • If you are specifying this annotation, you must specify the same number of items in the list as the load balancer subnets annotation and following the same order. Each item in the list can have value of either “auto_assigned” or a valid IPv6 prefix/CIDR with prefix length of 80 and it should be in range of the corresponding subnet CIDR.
  • Once the source NAT IPv6 prefixes are set, the IPv6 prefixes cannot be updated if the load balancer has a UDP listener attached.
    Example
    service.beta.kubernetes.io/aws-load-balancer-source-nat-ipv6-prefixes: 1025:0223:0009:6487:0001::/80, auto_assigned, 1025:0223:0010:6487:0001::/80

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-attributesfor proxy protocol v2 configuration.
  The only valid value for this annotation is *.
• service.beta.kubernetes.io/aws-load-balancer-target-group-attributes specifies theTarget Group Attributes to be configured. You can specify attributes globally for all target groups or override them for specific ports using port-specific annotations.
  Example
  • set the deregistration delay to 120 seconds (available range is 0-3600 seconds)
    `# Global attributes for all target groups
    service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: deregistration_delay.timeout_seconds=120

  Port-specific attributes (overrides global attributes for port 3306)

  service.beta.kubernetes.io/aws-load-balancer-target-group-attributes.3306: proxy_protocol_v2.client_to_server.header_placement=on_first_ack
  `

  • Port-specific attributes with empty values
    `# Global attributes for all target groups
    service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: target.group-attr-1=80

  Port-specific attributes (empty values don't override global attributes)

  service.beta.kubernetes.io/aws-load-balancer-target-group-attributes.3306: target.group-attr-1=
  `
  Note: When a port-specific attribute value is empty, it will not override the global attribute value. This allows you to selectively remove attributes for specific ports without affecting other ports that should inherit the global value.

  • enable source IP affinity
    service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: stickiness.enabled=true,stickiness.type=source_ip
  • enable proxy protocol version 2
    service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: proxy_protocol_v2.enabled=true
  • enable connection termination on deregistration
    service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: deregistration_delay.connection_termination.enabled=true
  • enable client IP preservation
    service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: preserve_client_ip.enabled=true
  • disable immediate connection termination for unhealthy targets and configure a 30s draining interval (available range is 0-360000 seconds)
    service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: target_health_state.unhealthy.connection_termination.enabled=false,target_health_state.unhealthy.draining_interval_seconds=30
• service.beta.kubernetes.io/aws-load-balancer-attributes specifies Load Balancer Attributes that should be applied to the NLB.
  Only attributes defined in the annotation will be updated. To unset any AWS defaults(e.g. Disabling access logs after having them enabled once), the values need to be explicitly set to the original values(access_logs.s3.enabled=false) and omitting them is not sufficient. Custom attributes set in this annotation's config map will be overriden by annotation-specific attributes. For backwards compatibility, existing annotations for the individual load balancer attributes get precedence in case of ties.
  • If deletion_protection.enabled=true is in the annotation, the controller will not be able to delete the NLB during reconciliation. Once the attribute gets edited to deletion_protection.enabled=false during reconciliation, the deployer will force delete the resource.
  • Please note, if the deletion protection is not enabled via annotation (e.g. via AWS console), the controller still deletes the underlying resource.
    Example
  • enable access log to s3
    service.beta.kubernetes.io/aws-load-balancer-attributes: access_logs.s3.enabled=true,access_logs.s3.bucket=my-access-log-bucket,access_logs.s3.prefix=my-app
  • enable NLB deletion protection
    service.beta.kubernetes.io/aws-load-balancer-attributes: deletion_protection.enabled=true
  • enable cross zone load balancing
    service.beta.kubernetes.io/aws-load-balancer-attributes: load_balancing.cross_zone.enabled=true
  • enable client availability zone affinity
    service.beta.kubernetes.io/aws-load-balancer-attributes: dns_record.client_routing_policy=availability_zone_affinity
• service.beta.kubernetes.io/aws-load-balancer-listener-attributes.${Protocol}-${Port} specifies listener attributes that should be applied to the listener.
  Only attributes defined in the annotation will be updated. To reset any AWS defaults, the values need to be explicitly set to the original values and omitting it is not sufficient.
  Example
  • configure TCP idle timeout value.
    service.beta.kubernetes.io/aws-load-balancer-listener-attributes.TCP-80: tcp.idle_timeout.seconds=400
• 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.
  • 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"
• service.beta.kubernetes.io/aws-load-balancer-disable-nlb-sg disables creation and management of SGs for the NLB. Note: This value shouldn't be changed after initial service creation. Once an NLB has been created, SGs can not be removed likewise, SGs can not be added to an existing NLB without an SG attached.
  • This is a fine-grained way of setting the controller level feature flag --feature-gates=NLBSecurityGroup=false to disable SG management for a specific service.
    Example
    service.beta.kubernetes.io/aws-load-balancer-disable-nlb-sg: "true"
• service.beta.kubernetes.io/aws-load-balancer-quic-enabled-ports Upgrades the UDP protocol to QUIC.
  This annotation only applies to UDP ports. The annotation is ignored when the specified port is NOT UDP based.
  Ensure that the pods belonging to the service have been QUIC enabled. See QUIC use-case for more information.
  Example
  service.beta.kubernetes.io/aws-load-balancer-quic-enabled-ports: "443"
• 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-access-log-enabled service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled
• 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.
    Example
    service.beta.kubernetes.io/aws-load-balancer-multi-cluster-target-group: "true"

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.
  • you cannot override the default controller tags mentioned above or the tags specified in the --default-tags controller flag
  • if any of the tag conflicts with the ones configured via --external-managed-tags controller flag, the controller fails to reconcile the service
    Example
    service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags: Environment=dev,Team=test

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.
  • you can specify tcp, or http or https, tcp is the default
  • tcp is the default health check protocol if the service spec.externalTrafficPolicy is Cluster, http if Local
  • if the service spec.externalTrafficPolicy is Local, do not use tcp for health check
  • Supports only single protocol per service
    Example
    service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol: http
• service.beta.kubernetes.io/aws-load-balancer-healthcheck-port specifies the TCP port to use for target group health check.
  accepted values
  • traffic-port - use the same port as the target group traffic (default when externalTrafficPolicy=Cluster)
  • Integer string (e.g., "80") - use this specific port number
  • Service port name (e.g., "http") - resolves based on target type:
    * Instance targets: uses the Service port's NodePort
    * IP targets: uses the Service port's targetPort (must be numeric, not a named port)
  • Default: spec.healthCheckNodePort when externalTrafficPolicy=Local, otherwise traffic-port
    Example
  • set the health check port to traffic-port
service.beta.kubernetes.io/aws-load-balancer-healthcheck-port: traffic-port
  • set the health check port to port 80
service.beta.kubernetes.io/aws-load-balancer-healthcheck-port: "80"
  • set the health check port to a named Service port
    service.beta.kubernetes.io/aws-load-balancer-healthcheck-port: "http"
• service.beta.kubernetes.io/aws-load-balancer-healthcheck-path specifies the http path for the health check in case of http/https protocol.
  Example
  service.beta.kubernetes.io/aws-load-balancer-healthcheck-path: /healthz
• service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold specifies the consecutive health check successes required before a target is considered healthy.
  Example
  service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold: "3"
• service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold specifies the consecutive health check failures before a target gets marked unhealthy.
  Example
  service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold: "3"
• service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval specifies the interval between consecutive health checks.
  Example
  service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval: "10"
• 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.
  Example
  service.beta.kubernetes.io/aws-load-balancer-healthcheck-success-codes: "200-399"
• 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.
  Example
  service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout: "10"

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.
  The first certificate in the list is the default certificate and remaining certificates are for the optional certificate list. See Server Certificates for further details.
  Example
  • single certificate
    service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:us-west-2:xxxxx:certificate/xxxxxxx
  • multiple certificates
    service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:us-west-2:xxxxx:certificate/cert1,arn:aws:acm:us-west-2:xxxxx:certificate/cert2,arn:aws:acm:us-west-2:xxxxx:certificate/cert3
• service.beta.kubernetes.io/aws-load-balancer-ssl-ports specifies the frontend ports with TLS listeners.
  • You must configure at least one certificate for TLS listeners
  • You can specify a list of port names or port values, * does not match any ports
  • If you don't specify this annotation, controller creates TLS listener for all the service ports
  • Specify this annotation if you need both TLS and non-TLS listeners on the same load balancer
    Example
    service.beta.kubernetes.io/aws-load-balancer-ssl-ports: 443, custom-port
• 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.
  Example
  service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy: ELBSecurityPolicy-TLS13-1-2-2021-06
• 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.
  • If you specify ssl as the backend protocol, NLB uses TLS connections for the traffic to your kubernetes pods in case of TLS listeners
  • You can specify ssl or tcp (default)
    Example
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: ssl

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.
  Tip
  • We recommend specifying CIDRs in the service spec.loadBalancerSourceRanges instead
  • For enhanced security with internal network load balancers, we recommend limiting access by specifying allowed source IP ranges. This can be done using either the service.beta.kubernetes.io/load-balancer-source-ranges annotation or the spec.loadBalancerSourceRanges field.
    Default
  • 0.0.0.0/0 will be used if the IPAddressType is "ipv4"
  • 0.0.0.0/0 and ::/0 will be used if the IPAddressType is "dualstack"
    This annotation will be ignored in case preserve client IP is not enabled. - preserve client IP is disabled by default for IP targets - preserve client IP is enabled by default for instance targets
    Preserve client IP has no effect on traffic converted from IPv4 to IPv6 and 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. - This could cause the clients that have their traffic converted to bypass the specified CIDRs that are allowed to access the NLB.
    this annotation will be ignored if service.beta.kubernetes.io/aws-load-balancer-security-groups is specified.
    Example
    service.beta.kubernetes.io/load-balancer-source-ranges: 10.0.0.0/24
• service.beta.kubernetes.io/aws-load-balancer-security-group-prefix-lists specifies the managed prefix lists that are allowed to access the NLB.
  this annotation will be ignored if service.beta.kubernetes.io/aws-load-balancer-security-groups is specified.
  If you'd like to use this annotation, make sure your security group rule quota is enough. If you'd like to know how the managed prefix list affects your quota, see the reference in the AWS documentation for more details.
  If you only use this annotation without load-balancer-source-ranges, the controller managed security group would ignore the load-balancer-source-ranges default settings.
  Example
  service.beta.kubernetes.io/aws-load-balancer-security-group-prefix-lists: pl-00000000, pl-1111111
• 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.
  Example
  service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"
• service.beta.kubernetes.io/aws-load-balancer-internal specifies whether the NLB will be internet-facing or internal.
  deprecation note
  This annotation is deprecated starting v2.2.0 release in favor of the new aws-load-balancer-scheme annotation. It will be supported, but in case of ties, the aws-load-balancer-scheme gets precedence.
  Example
  service.beta.kubernetes.io/aws-load-balancer-internal: "true"
  • service.beta.kubernetes.io/aws-load-balancer-security-groups specifies the frontend securityGroups you want to attach to an NLB.
    When this annotation is not present, the controller will automatically create one security group. The security group will be attached to the LoadBalancer and allow access from load-balancer-source-ranges and aws-load-balancer-security-group-prefix-lists to the listen-ports. Also, the securityGroups for target instances/ENIs will be modified to allow inbound traffic from this securityGroup.
    If you specify this annotation, you need to configure the security groups on your target instances/ENIs to allow inbound traffic from the load balancer. You could also set the manage-backend-security-group-rules if you want the controller to manage the security group rules.
    Both name and ID of securityGroups are supported. Name matches a Name tag, not the groupName attribute.
    Example
    service.beta.kubernetes.io/aws-load-balancer-security-groups: sg-xxxx, nameOfSg1, nameOfSg2
• 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.
  If you disable the automatic management of security group rules for an NLB (e.g.: by setting service.beta.kubernetes.io/aws-load-balancer-security-groups), you will need to manually add appropriate ingress rules to your EC2 instance or ENI security groups to allow access to the traffic and health check ports.
  Example
  service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules: "false"
• 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.
  Example
  service.beta.kubernetes.io/aws-load-balancer-inbound-sg-rules-on-private-link-traffic: "off"

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 theCapacity Unit Reservation to be configured.
  Example
  • set the capacity unit reservation to 1000
    service.beta.kubernetes.io/aws-load-balancer-minimum-load-balancer-capacity: CapacityUnits=3000
  • reset the capacity unit reservation
    service.beta.kubernetes.io/aws-load-balancer-minimum-load-balancer-capacity: CapacityUnits=0
    Notes
  • If you specify this annotation, but remove it later, the capacity unit reservation is not reset. You need to reset the capacity by setting the capacity units to zero as show in the example above.
  • If users do not want the controller to manage the capacity unit reservation on load balancer, they can disable the feature by setting controller command line feature gate flag --feature-gates=LBCapacityReservation=true

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+.