linode-cloud-controller-manager

LoadBalancer Services Configuration

Overview

The CCM supports two types of LoadBalancer implementations:

Linode NodeBalancers (default)
BGP-based IP sharing

For implementation examples, see Basic Service Examples.

NodeBalancer Implementation

When using NodeBalancers, the CCM automatically:

Creates and configures a NodeBalancer
Sets up backend nodes
Manages health checks
Handles SSL/TLS configuration

For more details, see Linode NodeBalancer Documentation.

IPv6 Support

NodeBalancers support both IPv4 and IPv6 ingress addresses. By default, the CCM uses only IPv4 address for LoadBalancer services.

You can enable IPv6 addresses globally for all services by setting the enable-ipv6-for-loadbalancers flag:

spec:
  template:
    spec:
      containers:
        - name: ccm-linode
          args:
            - --enable-ipv6-for-loadbalancers=true

Alternatively, you can enable IPv6 addresses for individual services using the annotation:

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

When IPv6 is enabled (either globally or per-service), both IPv4 and IPv6 addresses will be included in the service's LoadBalancer status.

Basic Configuration

Create a LoadBalancer service:

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  type: LoadBalancer
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: my-app

See Advanced Configuration Examples for more complex setups.

NodeBalancer Settings

Protocol Configuration

Available protocols:

tcp (default)
http
https

Set the default protocol:

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

See Service Annotations for all protocol options.

Health Checks

Configure health checks using annotations:

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-check-type: "http"
    service.beta.kubernetes.io/linode-loadbalancer-check-path: "/healthz"
    service.beta.kubernetes.io/linode-loadbalancer-check-interval: "5"
    service.beta.kubernetes.io/linode-loadbalancer-check-timeout: "3"
    service.beta.kubernetes.io/linode-loadbalancer-check-attempts: "2"

Available check types:

none: No health check
connection: TCP connection check
http: HTTP status check
http_body: HTTP response body check

For more details, see Health Check Configuration.

SSL/TLS Configuration

Create a TLS secret:

apiVersion: v1
kind: Secret
metadata:
  name: my-tls-secret
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-cert>
  tls.key: <base64-encoded-key>

Reference in service annotation:

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

Connection Throttling

Limit connections from the same client IP:

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-throttle: "5"

Proxy Protocol

Enable proxy protocol for client IP preservation:

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-default-proxy-protocol: "v2"

BGP-based IP sharing provides a more cost-effective solution for multiple LoadBalancer services. For detailed setup instructions, see Cilium BGP Documentation.

Prerequisites

Cilium CNI with BGP control plane enabled
Additional IP provisioning enabled on your account (contact Linode Support)
Nodes labeled for BGP peering

Configuration

Enable BGP in CCM deployment:

args:
  - --load-balancer-type=cilium-bgp
  - --bgp-node-selector=cilium-bgp-peering=true
  - --ip-holder-suffix=mycluster

Label nodes that should participate in BGP peering:

kubectl label node my-node cilium-bgp-peering=true

Create LoadBalancer services as normal - the CCM will automatically use BGP-based IP sharing instead of creating NodeBalancers.

Environment Variables

BGP_CUSTOM_ID_MAP: Use your own map instead of default region map for BGP
BGP_PEER_PREFIX: Use your own BGP peer prefix instead of default one

For more details, see Environment Variables.

Configuring NodeBalancers directly with VPC

NodeBalancers can be configured to have VPC specific ips configured as backend nodes. It requires:

VPC with a subnet and Linodes in VPC
Each NodeBalancer created within that VPC needs a free /30 or bigger subnet from the subnet to which Linodes are connected

Specify NodeBalancer backend ipv4 range when creating service:

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-backend-ipv4-range: "10.100.0.0/30"

By default, CCM uses first VPC and Subnet name configured with it to attach NodeBalancers to that VPC subnet. To overwrite those, use:

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

If CCM is started with --nodebalancer-backend-ipv4-subnet flag, then it will not allow provisioning of nodebalancer unless subnet specified in service annotation lie within the subnet specified using the flag. This is to prevent accidental overlap between nodebalancer backend ips and pod CIDRs.

Advanced Configuration

Using Existing NodeBalancers

Specify an existing NodeBalancer:

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-nodebalancer-id: "12345"

NodeBalancer Preservation

Prevent NodeBalancer deletion when service is deleted:

metadata:
  annotations:
    service.beta.kubernetes.io/linode-loadbalancer-preserve: "true"

Port Configuration

Configure individual ports:

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