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\" }"
- boolean:
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 eithernlb-ip
orexternal
.- 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
- For
-
service.beta.kubernetes.io/aws-load-balancer-nlb-target-type
specifies the target type to configure for NLB. You can choose betweeninstance
andip
.-
instance
mode will route traffic to all EC2 instances within cluster on the NodePort opened for your service.service must be of type
NodePort
orLoadBalancer
forinstance
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 forinstance
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:
-
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
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
- set the deregistration delay to 120 seconds (available range is 0-3600 seconds)
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
insteadDefault
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 forinstance
targetsExample
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 areinternal
,internet-facing
. If not specified, default isinternal
.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+.