Skip to content

Annotations

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

Name Type Default Notes
service.beta.kubernetes.io/load-balancer-source-ranges stringList
service.beta.kubernetes.io/aws-load-balancer-type string
service.beta.kubernetes.io/aws-load-balancer-nlb-target-type string
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-ip-address-type string ipv4 ipv4 | dualstack
service.beta.kubernetes.io/aws-load-balancer-access-log-enabled boolean false
service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name string
service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix string
service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled boolean false
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-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-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-eip-allocations stringList Public Facing lb only. Length/order must match subnets
service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses stringList Internal lb only. Length/order must match 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 stringList
service.beta.kubernetes.io/aws-load-balancer-target-node-labels stringMap

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.

    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.

    • For nlb-ip type, controller will provision NLB with IP targets. This value is supported for backwards compatibility
    • For external type, NLB target type depend on the annotation nlb-target-type

    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 between instance and ip.

    • instance mode will route traffic to all EC2 instances within cluster on the NodePort opened for your service.

      service must be of type NodePort or LoadBalancer for instance targets

    • ip mode will route traffic directly to the pod IP.

      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 Zone the 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
    • AWS has restrictions on disabling existing subnets for NLB. As a result, you might not be able to edit this annotation once the NLB gets provisioned.

    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 policies on the load balancer.

    requirements

    TLS listener forwarding to a TLS target group

    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

Traffic Listening

Traffic Listening can be controlled with following annotations:

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.

    The only valid value for this annotation is *.

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

    Example

    • set the deregistration delay to 120 seconds (available range is 0-3600 seconds) 
      service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: deregistration_delay.timeout_seconds=120
    • 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

Access control

Load balancer access can be controllerd 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

    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

    Example

    service.beta.kubernetes.io/load-balancer-source-ranges: 10.0.0.0/24

  • 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 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"

Legacy Cloud Provider

The AWS Load Balancer Controller manages Kubernetes Services in a compatible way with the legacy aws cloud provider. 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, legacy cloud provider ignores the service resource (provided it has the correct patch) so that the AWS Load Balancer controller 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.

The legacy cloud provider patch was added in Kubernetes v1.20 and is backported to Kubernetes v1.18.18+, v1.19.10+.