Service Annotations

March 27, 2026 · View on GitHub

Overview

Service annotations allow you to customize the behavior of your LoadBalancer services. All Service annotations must be prefixed with: service.beta.kubernetes.io/linode-loadbalancer-

For implementation details, see:

NOTE: The keys and the values in annotations must be strings. In other words, you cannot use numeric, boolean, list or other types for either the keys or the values. Hence, one should double quote them when specifying in annotations to convert them to string.

Available Annotations

Basic Configuration

Annotation (Suffix)	Values	Default	Description
`throttle`	`0`-`20` (`0` to disable)	`0`	Client Connection Throttle, which limits the number of subsequent new connections per second from the same client IP
`default-protocol`	`tcp`, `udp`, `http`, `https`	`tcp`	This annotation is used to specify the default protocol for Linode NodeBalancer
`default-proxy-protocol`	`none`, `v1`, `v2`	`none`	Specifies whether to use a version of Proxy Protocol on the underlying NodeBalancer
`default-algorithm`	`roundrobin`, `leastconn`, `source`, `ring_hash`	`roundrobin`	This annotation is used to specify the default algorithm for Linode NodeBalancer
`default-stickiness`	`none`, `session`, `table`, `http_cookie`, `source_ip`	`session` (for UDP), `table` (for HTTP/HTTPs)	This annotation is used to specify the default stickiness for Linode NodeBalancer
`port-*`	json object		Specifies port specific NodeBalancer configuration. See Port Configuration
`check-type`	`none`, `connection`, `http`, `http_body`	`none` for UDP, else `connection`	The type of health check to perform against back-ends. See Health Checks
`check-path`	string		The URL path to check on each back-end during health checks
`check-body`	string		Text which must be present in the response body to pass the health check
`check-interval`	int	`5`	Duration, in seconds, to wait between health checks
`check-timeout`	int (1-30)	`3`	Duration, in seconds, to wait for a health check to succeed
`check-attempts`	int (1-30)	`2`	Number of health check failures necessary to remove a back-end
`check-passive`	bool	`false`	When `true`, `5xx` status codes will cause the health check to fail
`udp-check-port`	int	`80`	Specifies health check port for UDP nodebalancer
`preserve`	bool	`false`	When `true`, deleting a `LoadBalancer` service does not delete the underlying NodeBalancer
`nodebalancer-id`	int		The ID of the NodeBalancer to front the service
`hostname-only-ingress`	bool	`false`	When `true`, the LoadBalancerStatus will only contain the Hostname
`tags`	string		A comma separated list of tags to be applied to the NodeBalancer instance
`firewall-id`	int		An existing Cloud Firewall ID to be attached to the NodeBalancer instance. See Firewall Setup
`firewall-acl`	string		The Firewall rules to be applied to the NodeBalancer. See Firewall Configuration
`nodebalancer-type`	string		The type of NodeBalancer to create (options: common, premium, premium_40gb). See NodeBalancer Types. Note: NodeBalancer types should always be specified in lowercase.
`enable-ipv6-ingress`	bool	`false`	When `true`, both IPv4 and IPv6 addresses will be included in the LoadBalancerStatus ingress
`enable-ipv6-backends`	bool	`false`	When `true`, NodeBalancer services use node public IPv6 addresses as backend targets. VPC IPv6 backend addresses are not supported.
`backend-ipv4-range`	string		The IPv4 range from VPC subnet to be applied to the NodeBalancer backend. See Nodebalancer VPC Configuration
`backend-vpc-name`	string		VPC which is connected to the NodeBalancer backend. See Nodebalancer VPC Configuration
`backend-subnet-name`	string		Subnet within VPC which is connected to the NodeBalancer backend. See Nodebalancer VPC Configuration
`backend-subnet-id`	string		Subnet ID within VPC which is connected to the NodeBalancer backend. See Nodebalancer VPC Configuration
`frontend-subnet-id`	string		Subnet ID for the NodeBalancer frontend VPC configuration. See Nodebalancer VPC Configuration
`frontend-vpc-name`	string		Frontend VPC name for the NodeBalancer frontend VPC configuration. See Nodebalancer VPC Configuration
`frontend-subnet-name`	string		Frontend subnet name for the NodeBalancer frontend VPC configuration. See Nodebalancer VPC Configuration
`frontend-ipv4-range`	string		Optional IPv4 CIDR range from the frontend subnet. See Nodebalancer VPC Configuration
`frontend-ipv6-range`	string		Optional IPv6 CIDR range from the frontend subnet. See Nodebalancer VPC Configuration
`reserved-ipv4`	string		An existing Reserved IPv4 address that wil be used to initialize the NodeBalancer instance. See LoadBalancer Configuration)

Port Specific Configuration

The port-* annotation allows per-port configuration, encoded in JSON. For detailed examples, see LoadBalancer SSL/TLS Setup.

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-port-443: |
      {
        "protocol": "https",
        "tls-secret-name": "my-tls-secret",
        "proxy-protocol": "v2",
        "algorithm": "leastconn",
        "stickiness": "http_cookie"
      }

Available port options:

protocol: Protocol for this port (tcp, http, https)
tls-secret-name: Name of TLS secret for HTTPS. The secret type should be kubernetes.io/tls
proxy-protocol: Proxy protocol version for this port
algorithm: Algorithm for this port
stickiness: Stickiness for this port
udp-check-port: UDP health check port for this port

Deprecated Annotations

Annotation (Suffix)	Values	Default	Description	Scheduled Removal
`proxy-protocol`	`none`, `v1`, `v2`	`none`	Specifies whether to use a version of Proxy Protocol on the underlying NodeBalancer	Q4 2021

Annotation Boolean Values

For annotations with bool value types, the following string values are interpreted as true:

"1"
"t"
"T"
"true"
"True"
"TRUE"

Any other values will be interpreted as false. For more details, see strconv.ParseBool.

Examples

Basic HTTP Service

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-default-protocol: "http"
    service.beta.kubernetes.io/linode-loadbalancer-check-type: "http"
    service.beta.kubernetes.io/linode-loadbalancer-check-path: "/healthz"

HTTPS Service with TLS

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-port-443: |
      {
        "protocol": "https",
        "tls-secret-name": "my-tls-secret"
      }

Firewall Configuration

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-firewall-acl: |
      {
        "allowList": {
          "ipv4": ["192.168.0.0/16"],
          "ipv6": ["2001:db8::/32"]
        }
      }

NodeBalancer Type

Linode supports nodebalancers of different types: common, premium, and premium_40gb. By default, nodebalancers of type common are provisioned. If an account is allowed to provision premium nodebalancers and one wants to use them, it can be achieved by specifying the annotation:

Note: NodeBalancer types should always be specified in lowercase. The controller will automatically convert uppercase values to lowercase for safety.

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-nodebalancer-type: premium

Nodebalancer VPC Configuration

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-backend-ipv4-range: "10.100.0.0/30"
    service.beta.kubernetes.io/linode-loadbalancer-backend-vpc-name: "vpc1"
    service.beta.kubernetes.io/linode-loadbalancer-backend-subnet-name: "subnet1"

Frontend VPC configuration:

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-frontend-subnet-id: "169341"
    # Optional:
    # service.beta.kubernetes.io/linode-loadbalancer-frontend-ipv4-range: "10.0.0.0/24"
    # service.beta.kubernetes.io/linode-loadbalancer-frontend-ipv6-range: "2001:db8::/64"

Service with IPv6 Address

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-ingress: "true"

For more examples and detailed configuration options, see: