Skip to main content
Calico Enterprise 3.21 (early preview) documentation

LoadBalancer IP address management

Understanding Calico Enterprise LoadBalancer IP address management​

You might want to utilize Service of type LoadBalancer in your cluster to provide stable long-lasting IP address to access your deployed application. Calico Enterprise can help you with providing and managing IP addresses to your Services in your cluster. Calico Enterprise comes with LoadBalancer IPAM deployed as part of Calico Enterprise Kube-controllers.

Before you begin...​

Ensure that you have a cluster with Calico Enterprise installed, and kube-controllers configured and running.

IP Pool for Service of type LoadBalancer​

Calico Enterprise does not automatically provide default IP Pool for LoadBalancer IP address management. You will need to create an IP Pool with allowedUses LoadBalancer for Calico Enterprise to start assigning Service IPs.

apiVersion: projectcalico.org/v3
kind: IPPool
metadata:
 name: loadbalancerIPPool
spec:
 cidr: 192.210.0.0/20
 blockSize: 24
 natOutgoing: true
 disabled: false
 assignmentMode: Automatic
 allowedUses:
  - LoadBalancer
note

You can create multiple IP Pools with allowedUses LoadBalancer as long as there are no CIDR conflicts. By setting assignmentMode to Manual you can reserve the IP Pool for manual assignments only. Explore more about manual assignment

Automatic Service IP address assignment​

When you create Service of type LoadBalancer Calico Enterprise kube-controller will automatically detect the new Service and assign an IP address from available IP Pool. If no address is available, the Service will remain in pending state until an address is available.

apiVersion: v1
kind: Service
metadata:
  name: service-loadbalancer
spec:
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
      name: default
  type: LoadBalancer

Manual Service IP address assignment​

There are cases where you would like to be more specific about what IP address Calico Enterprise assigns to your Service. With annotations, you can specify how IP address should be assigned. The annotations can be added and removed as needed during the lifetime of the Service. When you remove an annotation Calico Enterprise kube-controller will check if the assigned IP is still valid and potentially assign a new one.

Specify IP Pool​

IPv4 Pool​

Annotate the Service with projectcalico.org/ipv4pools to assign IP address from the selected IP Pools. You can specify multiple IP Pools in this annotation, Calico Enterprise will pick an available IP address to assign.

"projectcalico.org/ipv4pools": '["loadBalancerIPv4Pool"]'
IPv6 Pool​

Annotate the Service with projectcalico.org/ipv6pools to assign IP address from the selected IP Pools. You can specify multiple IP Pools in this annotation, Calico Enterprise will pick an available IP address to assign.

"projectcalico.org/ipv6pools": '["loadBalancerIPv6Pool"]'
note

In dual-stack environment you don't have to specify both annotations. If IP Pool was not specified for IP family, Calico Enterprise will automatically assign available IP address from available IP Pool

Specifying IP address​

Annotate the Service with projectcalico.org/loadBalancerIPs to assign specific IP address. The address must be available otherwise Calico Enterprise will not be able to assign the address. Currently you can only specify one IPv4 and one IPv6 address at the same time.

"projectcalico.org/loadBalancerIPs": '["x.x.x.x"]'
note

If Service contains "projectcalico.org/loadBalancerIPs" annotation and either "projectcalico.org/ipv6pools" or "projectcalico.org/ipv4pools" are present, Calico Enterprise will favour projectcalico.org/loadBalancerIPs annotation and try to assign that IP address. There is no fall back to an IP Pool if the specified address is not available.

Manage LoadBalancer kube-controller assignment mode​

In certain cases you might not wish for Calico Enterprise to automatically assign IP addresses to your Service. This can be useful in case you have multiple Service IPAM solutions in your cluster. LoadBalancer kube-controller is able to operate in two distinct modes Automatic in which Calico Enterprise assigns IP address to each Service in your cluster and RequestedServicesOnly in which Calico Enterprise only assigns IP addresses to Service with annotations mentioned above. You can change the mode at any point, but note that switching to RequestedServicesOnly will unassign any addresses from Services that do not contain the above annotations.

kubectl patch kubecontrollersconfiguration default --patch '{"spec": {"controllers":{"loadBalancer":{"AssignIPs": "RequestedServicesOnly"}}}}'

Additional resources​

Calico LoadBalancer IP address management works in conjunction with other Calico Enterprise components. Calico Enterprise kube-controllers provides only the IP address management, to advertise LoadBalancer IPs you will have to update your BGP configuration. You can find out more information at: