The Service Controller
The service controller is responsible for watch for service and node object changes, so that it can create, update, or delete cloud load balancers corresponding to load balanced services. Like the other controllers, we import the cloud-provider provided utility functions for managing the controller itself, which calls into cloud provider defined methods GetLoadBalancer, GetLoadBalancerName, EnsureLoadBalancer, UpdateLoadBalancer, and EnsureLoadBalancerDeleted.
| Annotation | Valid Values | Default | Valid for | Description |
|---|---|---|---|---|
| service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval | [5|60] | - | ELB | How frequently the load balancer emits access logs, in minutes. |
| service.beta.kubernetes.io/aws-load-balancer-access-log-enabled | [true|false] | - | ELB | If true, access logs is enabled. |
| service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name | - | - | ELB | Access log S3 bucket name. |
| service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix | - | - | ELB | Access log S3 bucket prefix. |
| service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags | Comma-separated list of key=value | - | ELB,NLB | A comma-separated list of key-value pairs which will be recorded as additional tags in the ELB. For example: "Key1=Val1,Key2=Val2,KeyNoVal1=,KeyNoVal2" |
| service.beta.kubernetes.io/aws-load-balancer-backend-protocol | [http|https|ssl|tcp] | tcp | ELB | Specifies the protocol spoken by the backend (pod) behind a listener. If set to http and the aws-load-balancer-ssl-cert annotation is missing or its value is empty (""), an HTTP listener is created; if set to http or https and the aws-load-balancer-ssl-certannotation is also present, an HTTPS listener is created to terminate SSL and parse headers. If set to ssl or tcp, a "raw" SSL/TCP listener is used. if the annotation is missing, its value is empty (""), or set to https without the aws-load-balancer-ssl-certannotation also being present, the default protocol is assumed to be tcp. |
| service.beta.kubernetes.io/aws-load-balancer-connection-draining-enabled | [true|false] | - | ELB | Enable connection draining. |
| service.beta.kubernetes.io/aws-load-balancer-connection-draining-timeout | [1-3600] | 300 | ELB | The maximum time (in seconds) for the load balancer to keep connections alive before reporting the instance as de-registered. The maximum timeout value can be set between 1 and 3,600 seconds (the default is 300 seconds). When the maximum time limit is reached, the load balancer forcibly closes connections to the de-registering instance. |
| service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout | [1-4000] | 60 | ELB | The load balancer has a configured idle timeout period (in seconds) that applies to its connections. If no data has been sent or received by the time that the idle timeout period elapses, the load balancer closes the connection. |
| service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled | [true|false] | - | ELB | With cross-zone load balancing, each load balancer node for your Classic Load Balancer distributes requests evenly across the registered instances in all enabled Availability Zones. If cross-zone load balancing is disabled, each load balancer node distributes requests evenly across the registered instances in its Availability Zone only. |
| service.beta.kubernetes.io/aws-load-balancer-extra-security-groups | Comma-separated list | - | ELB | Specifies additional security groups to be added to ELB. |
| service.beta.kubernetes.io/aws-load-balancer-security-groups | Comma-separated list | - | ELB | Specifies the security groups to be added to ELB. Differently from the annotation "service.beta.kubernetes.io/aws-load-balancer-extra-security-groups", this replaces all other security groups previously assigned to the ELB. |
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold | [2-10] | - | NLB | Specifies the number of successive successful health checks required for a backend to be considered healthy for traffic. For NLB, healthy-threshold and unhealthy-threshold must be equal. |
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval | [5-300] | 30 | NLB | Specifies, in seconds, the interval between health checks. |
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout | [2-60] | 5 | NLB | The amount of time to wait when receiving a response from the health check, in seconds. |
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold | [2-10] | 2 | NLB | The number of consecutive failed health checks that must occur before declaring an EC2 instance unhealthy. |
| service.beta.kubernetes.io/aws-load-balancer-internal | [true|false] | - | ELB,NLB | Indicates that the load balancer should be internal. |
| service.beta.kubernetes.io/aws-load-balancer-proxy-protocol | [*] | - | ELB | Enables the proxy protocol on an ELB. Right now we only accept the value "*" which means enable the proxy protocol on all ELB backends. In the future we could adjust this to allow setting the proxy protocol only on certain backends. |
| service.beta.kubernetes.io/aws-load-balancer-ssl-cert | IAM or ACM ARN | - | ELB,NLB | Requests a secure listener. Value is a valid certificate ARN. For more, see the elb listener config guide. CertARN is an IAM or CM certificate ARN. |
| service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy | - | ELBSecurityPolicy-2016-08 | ELB,NLB | Specifies SSL negotiation settings for the HTTPS/SSL listeners of your load balancer. Defaults to the default ELB policy. |
| service.beta.kubernetes.io/aws-load-balancer-ssl-ports | Comma-separated list | * | ELB,NLB | Specifies a comma-separated list of ports that will use SSL/HTTPS listeners. Defaults to all. |
| service.beta.kubernetes.io/aws-load-balancer-type | [nlb] | - | ELB,NLB | Indicates the type of Load Balancer. The only valid value is nlb, this means that leaving this field blank or omitting the annotation is equivalent to selecting ELB. When selecting nlb, the backend protocol is automatically derived from the protocol defined in the Kubernetes Service, as long as that protocol is supported by NLB (supported protocols include TCP, the default for a Kubernetes Service, and UDP). If the protocol is TCP and the aws-load-balancer-ssl-cert annotation is also present, the NLB protocol will be set to TLS. |
| service.beta.kubernetes.io/aws-load-balancer-eip-allocations | Comma-separated list | - | NLB | List of EIP allocations to associate with a internet-facing load balancer. Only valid for NLB. |
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-path | - | / | NLB | Specifies the http path for the health check in case of http/https protocol. |
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-port | [traffic-port|1-65535] | traffic-port | NLB | Specifies the TCP target port for the target group health check. |
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol | [tcp|http|https] | tcp | NLB | Specifies the protocol to use for the target group health check. |
| service.beta.kubernetes.io/aws-load-balancer-subnets | Comma-separated list | - | ELB,NLB | Specifies the Availability Zone configuration for the load balancer. The values are comma separated list of subnetID or subnetName from different AZs. |
| service.beta.kubernetes.io/aws-load-balancer-target-node-labels | Comma-separated list of key=value | - | ELB,NLB | Specifies a comma-separated list of key-value pairs which will be used to select the target nodes for the load balancer. |
| service.beta.kubernetes.io/aws-load-balancer-target-group-attributes | Comma-separated list of key=value | - | NLB | Specifies a comma-separated list of key-value pairs which will be applied as target group attributes. For example: "preserve_client_ip.enabled=false". The list of supported values is available here. |
Target group attributes for Service type-loadBalancer NLB
The following target group attributes are supported by the controller using the annotation service.beta.kubernetes.io/aws-load-balancer-target-group-attributes:
| Attribute | Values | Description |
|---|---|---|
| preserve_client_ip.enabled | [true|false] | Whether to preserve client IP addresses when terminating connections at the target group level |
| proxy_protocol_v2.enabled | [true|false] | Whether to enable proxy protocol v2 on the target group |
Format: Attributes are specified as key=value pairs, separated by commas.
Example:
service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: preserve_client_ip.enabled=true,proxy_protocol_v2.enabled=false
Usage Example 1 - working with hairpin connection on internal NLB
The following Service example changes the Target Group Traffic Control attribute "Preserve client IP addresses" from the default (true, when target type is instance) to false:
apiVersion: v1
kind: Service
metadata:
name: $SVC_NAME
namespace: ${APP_NAMESPACE}
annotations:
service.beta.kubernetes.io/aws-load-balancer-type: nlb
service.beta.kubernetes.io/aws-load-balancer-internal: true
service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: preserve_client_ip.enabled=false
[...]
Usage Example 2 - working with hairpin connection on internal NLB tracking source IP address
The following example allow users to fine tune the Services for a backend which requires tracking the original source IP address of internal Load Balancers NLB with support of hairpin connections:
apiVersion: v1
kind: Service
metadata:
name: $SVC_NAME
namespace: ${APP_NAMESPACE}
annotations:
service.beta.kubernetes.io/aws-load-balancer-type: nlb
service.beta.kubernetes.io/aws-load-balancer-internal: true
service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: preserve_client_ip.enabled=false,proxy_protocol_v2.enabled=true
[...]