DigitalOcean cloud controller manager watches for Services of type LoadBalancer and will create corresponding DigitalOcean Load Balancers matching the Kubernetes service. The Load Balancer can be configured by applying annotations to the Service resource. The annotations listed below can be used.
See example Kubernetes Services using LoadBalancers here.
Specifies a custom name for the Load Balancer. Existing Load Balancers will be renamed. The name must adhere to the following rules:
- it must not be longer than 255 characters
- it must start with an alphanumeric character
- it must consist of alphanumeric characters or the '.' (dot) or '-' (dash) characters
- except for the final character which must not be '-' (dash)
If no custom name is specified, a default name is chosen consisting of the character a appended by the Service UID.
The default protocol for DigitalOcean Load Balancers. Options are tcp, http, https, http2, http3. Defaults to tcp.
Certain annotations may override the default protocol. See the more specific descriptions below.
If https, http2, or http3 is specified, then either service.beta.kubernetes.io/do-loadbalancer-certificate-id or service.beta.kubernetes.io/do-loadbalancer-tls-passthrough must be specified as well.
Note: digitalocean-cloud-controller-manager automatically chooses a proper health check port. In general, the parameter does not need to be specified. For a specified value to become effective, the annotation service.beta.kubernetes.io/do-loadbalancer-override-health-check must be set explicitly.
The service port used to check if a backend droplet is healthy. Defaults to the first port in a service. A NodePort must not be defined.
Note: digitalocean-cloud-controller-manager automatically chooses a proper health check path. In general, the parameter does not need to be specified. For a specified value to become effective, the annotation service.beta.kubernetes.io/do-loadbalancer-override-health-check must be set additionally.
The path used to check if a backend droplet is healthy. Defaults to "/".
Note: digitalocean-cloud-controller-manager automatically chooses a proper health check protocol. In general, the parameter does not need to be specified. For a specified value to become effective, the annotation service.beta.kubernetes.io/do-loadbalancer-override-health-check must be set additionally.
The health check protocol to use to check if a backend droplet is healthy. Defaults to tcp if not specified. Options are tcp, http, and https.
The first node port on the service is used as health check port.
Note that while UDP is not a supported healthcheck protocol, if your load balancer has UDP service ports you must configure a TCP service as a health check for the load balancer to work properly.
The number of seconds between between two consecutive health checks. The value must be between 3 and 300. If not specified, the default value is 3.
The number of seconds the Load Balancer instance will wait for a response until marking a health check as failed. The value must be between 3 and 300. If not specified, the default value is 5.
The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool for the given service. The vaule must be between 2 and 10. If not specified, the default value is 3.
The number of times a health check must pass for a backend Droplet to be marked "healthy" for the given service and be re-added to the pool. The vaule must be between 2 and 10. If not specified, the default value is 5.
digitalocean-cloud-controller-manager automatically chooses proper values for the health check port, path, and protocol. In order to set any of these explicitly, this annotation must be specified additionally and set to any value.
If the annotation is set, then all of the following annotations (either any implicit or explicit values) will become effective as well:
service.beta.kubernetes.io/do-loadbalancer-healthcheck-portservice.beta.kubernetes.io/do-loadbalancer-healthcheck-pathservice.beta.kubernetes.io/do-loadbalancer-healthcheck-protocol
Specify which ports of the loadbalancer should use the HTTP protocol. This is a comma separated list of ports (e.g. 80,8080).
Ports must not be shared between this annotation, service.beta.kubernetes.io/do-loadbalancer-tls-ports, service.beta.kubernetes.io/do-loadbalancer-http2-ports, and service.beta.kubernetes.io/do-loadbalancer-http3-port.
Specify which ports of the loadbalancer should use the HTTPS protocol. This is a comma separated list of ports (e.g. 443,6443,7443).
If specified, exactly one of service.beta.kubernetes.io/do-loadbalancer-tls-passthrough and service.beta.kubernetes.io/do-loadbalancer-certificate-id must also be provided.
If no HTTPS port is specified but one of service.beta.kubernetes.io/do-loadbalancer-tls-passthrough or service.beta.kubernetes.io/do-loadbalancer-certificate-id is, then port 443 is assumed to be used for HTTPS. This does not hold if service.beta.kubernetes.io/do-loadbalancer-http2-ports or service.beta.kubernetes.io/do-loadbalancer-http3-port already specifies 443.
Ports must not be shared between this annotation, service.beta.kubernetes.io/do-loadbalancer-http-ports, service.beta.kubernetes.io/do-loadbalancer-http2-ports, and service.beta.kubernetes.io/do-loadbalancer-http3-port.
Specify which ports of the loadbalancer should use the HTTP2 protocol. This is a comma separated list of ports (e.g. 443,6443,7443).
If specified, exactly one of service.beta.kubernetes.io/do-loadbalancer-tls-passthrough and service.beta.kubernetes.io/do-loadbalancer-certificate-id must also be provided.
The annotation is required for implicit HTTP2 usage, i.e., when service.beta.kubernetes.io/do-loadbalancer-protocol is not set to http2. (Unlike service.beta.kubernetes.io/do-loadbalancer-tls-ports, no default port is assumed for HTTP2 in order to retain compatibility with the semantics of implicit HTTPS usage.)
Ports must not be shared between this annotation, service.beta.kubernetes.io/do-loadbalancer-http-ports, service.beta.kubernetes.io/do-loadbalancer-http3-port, and service.beta.kubernetes.io/do-loadbalancer-tls-ports.
Specify which port of the loadbalancer should use the HTTP3 protocol. Unlike other annotations, this is a single value, NOT multiple comma-separated values.
If specified, service.beta.kubernetes.io/do-loadbalancer-certificate-id must also be provided. In addition, either service.beta.kubernetes.io/do-loadbalancer-tls-ports OR service.beta.kubernetes.io/do-loadbalancer-http2-ports must be provided.
The annotation is required for implicit HTTP3 usage, i.e., when service.beta.kubernetes.io/do-loadbalancer-protocol is not set to http3. (Unlike service.beta.kubernetes.io/do-loadbalancer-tls-ports, no default port is assumed for HTTP3 in order to retain compatibility with the semantics of implicit HTTPS usage.)
Specify whether the DigitalOcean Load Balancer should pass encrypted data to backend droplets. This is optional. Options are "true" or "false". Defaults to "false".
Note
You have to supply the value as string (ex. "true", not true), otherwise you might run into a k8s bug that throws away all annotations on your Service resource.
Specifies the certificate ID used for https. To list available certificates and their IDs, install doctl and run doctl compute certificate list. Either
service.beta.kubernetes.io/do-loadbalancer-certificate-id OR service.beta.kubernetes.io/do-loadbalancer-certificate-name can be supplied, with the former
taking precedence if both are provided.
Specifies the certificate name used for https. To list available certificates and their IDs, install doctl and run doctl compute certificate list. Either
service.beta.kubernetes.io/do-loadbalancer-certificate-id OR service.beta.kubernetes.io/do-loadbalancer-certificate-name can be supplied, with the former
taking precedence if both are provided.
If using Let's Encrypt certificate, we suggest using the name of the certificate since the ID of the certificate will update each time it is rotated. The name of the certificate is required to be unique within the scope of an account.
Specifies the hostname used for the Service status.Hostname instead of assigning status.IP directly. This can be used to workaround the issue of kube-proxy adding external LB address to node local iptables rule, which will break requests to an LB from in-cluster if the LB is expected to terminate SSL or proxy protocol. See the examples/README for more detail.
Specifies which algorithm the Load Balancer should use. Options are round_robin, least_connections. Defaults to round_robin.
DEPRECATED: Specifying this annotation does nothing, as the algorithm field on the API is ignored.
Specifies which size the Load Balancer should be created with. Options are lb-small, lb-medium, and lb-large. Only one of do-loadbalancer-size-slug and do-loadbalancer-size-unit can be specified. Defaults to lb-small.
DEPRECATED: Use do-loadbalancer-size-unit instead.
Specifies the number of nodes to create the load balancer with. Options are numbers greater than or equal to 1. Only one of do-loadbalancer-size-unit and do-loadbalancer-size-slug can be specified. Defaults to 1.
Specifies which stick session type the loadbalancer should use. Options are none or cookies.
Note
- Sticky sessions will route consistently to the same nodes, not pods, so you should avoid having more than one pod per node serving requests.
- Sticky sessions require your Service to configure
externalTrafficPolicy: Localto avoid NAT confusion on the way in. - Using sticky sessions with only a TCP forwarding rule will not work as expected. Sticky sessions requires HTTP to function properly.
Specifies what cookie name to use for the DO load balancer sticky session. This annotation is required if service.beta.kubernetes.io/do-loadbalancer-sticky-sessions-type is set to cookies.
Specifies the TTL of cookies used for loadbalancer sticky sessions. This annotation is required if service.beta.kubernetes.io/do-loadbalancer-sticky-sessions-type is set to cookies.
Indicates whether or not http traffic should be redirected to https. Options are "true" or "false". Defaults to "false".
Note
You have to supply the value as string (ex. "true", not true), otherwise you might run into a k8s bug that throws away all annotations on your Service resource.
Specifies whether automatic DNS record creation should be disabled when a Let's Encrypt cert is added to a load balancer. Defaults to "false".
Indicates whether PROXY protocol should be enabled. Options are "true" or "false". Defaults to "false".
Note
You have to supply the value as string (ex. "true", not true), otherwise you might run into a k8s bug that throws away all annotations on your Service resource.
Indicates whether HTTP keepalive connections should be enabled to backend target droplets. Options are "true" or "false". Defaults to "false".
Note
You have to supply the value as string (ex. "true", not true), otherwise you might run into a k8s bug that throws away all annotations on your Service resource.
Indicates whether the managed load-balancer should be disowned. Disowned load-balancers are not mutated anymore, including creates, updates, and deletes. This can be employed to manage the load-balancer by a different cluster. Options are "true" or "false". Defaults to "false".
Warning Disowned load-balancers do not necessarily work correctly anymore because needed load-balancer updates (in terms of target nodes or configuration annotations) stop being propagated to the DigitalOcean load-balancer. Similarly, the Service status field may not reflect the right state anymore. Consequently, users should assign disowned load-balancers to a new Service without much delay.
See also the elaborate example.
Note
You have to supply the value as string (ex. "true", not true), otherwise you might run into a k8s bug that throws away all annotations on your Service resource.
Specifies the HTTP idle timeout configuration in seconds. If not specified, the default is 60 seconds.
Specifies the comma separated DENY firewall rules for the load-balancer
Note
Rules must be in the format {type}:{source} (ex. ip:1.2.3.4,cidr:2.3.0.0/16)
Specifies the comma separated ALLOW firewall rules for the load-balancer
Note
Rules must be in the format {type}:{source} (ex. ip:1.2.3.4,cidr:2.3.0.0/16).
These rules will be ignored if LoadBalancerSourceRanges is set, which is the preferred way to enter allow rules.