Load Balancers: Introduction

Civo Load Balancers are external to your cluster, but created and managed as part of your cluster's service definitions. In terms of Kubernetes, a Civo Load Balancer is a Service object with rules much like other Service type objects in Kubernetes, with the key difference that its state is handled by the Cloud Controller Manager that speaks to the Civo API. This means that by creating a Load Balancer, you can manage traffic routing externally to your cluster. In other words, Civo Load Balancers are our implementation of the Kubernetes External Load Balancer, which allow you to balance traffic to your Kubernetes cluster nodes.

Load balancer objects are chargeable as part of your monthly billing. This means if you create a Service object of type LoadBalancer the Civo API will detect this, and on assigning the load balancer a public IP address will start to account for its usage. You will see the charges on your current month's usage, and eventually on that month's invoice.

Creating a Load Balancer

Creating a Load Balancer relies on the Civo Cloud Controller Manager sending the appropriate request to the Civo API to handle the creation and configuration of the Load Balancer according to your specification. This system means that if you create any Service with type LoadBalancer, it will be picked up by the Civo API and appear on your cluster's dashboard showing its new public IP address:

You will also be able to see the Load Balancer in your Civo account on the cluster's page as soon as you create it on your cluster, showing the name you specified:

Load Balancer on Civo dashboard showing the name, algorithm as round-robin, the public IP, the private IP and state

Load Balancer configuration options

The Civo Load Balancer specification allows optional configuration elements. These are detailed below. Configuration options for your Load Balancer are to be specified in the spec block of your LoadBalancer service definition.


The load balancing algorithm, if provided, is one of round_robin or least_connections. The default, if not provided, is round_robin. This is specified in an annotation prefixed by kubernetes.civo.com/ as follows:

    kubernetes.civo.com/loadbalancer-algorithm: least_connections


    kubernetes.civo.com/loadbalancer-algorithm: round_robin

External traffic policy

The external traffic policy, if provided, is one of Cluster or Local. Cluster, the default, means routing of external traffic to cluster-wide endpoints and ensures evenness of the request load across . Local is only for HTTP traffic, and preserves the client source IP using a X-Forwarded-For header added to the request, with the side effect of less efficient load balancing.

externalTrafficPolicy: Cluster


externalTrafficPolicy: Local

Session affinity configuration

You can ensure that all requests from a particular client IP get routed to the same Pod within a given time frame by setting the optional session affinity configuration. The structure of this optional configuration is as follows.

sessionAffinity: ClientIP

If you include the first line, you can also optimally set the timeout of a session in seconds on subsequent lines. The default value of timeoutSeconds is 10800, i.e. 3 hours, which will be used if not provided.

sessionAffinity: ClientIP
      timeoutSeconds: 480

Firewall ID

The firewall configuration for your Load Balancer is specified in an annotation kubernetes.civo.com/firewall-id that takes the ID of your chosen firewall as input, such as:

    kubernetes.civo.com/firewall-id: 3eb6534a-4f81-4bb9-9d91-a382391f18ad

The firewall must be specified using its ID, rather than displayed name.

If a firewall is not specified in an annotation, the Load Balancer will use the default firewall and not close any ports.

Proxy Protocol

Civo Load Balancers support the HAProxy Proxy Protocol. Use of the Proxy Protocol allows for the preservation of client IP information to supporting services such as NginX. Not enabled by default. Supported values are send-proxy and send-proxy-v2.

Proxy Protocol can be enabled with:

   kubernetes.civo.com/loadbalancer-enable-proxy-protocol: send-proxy

Reserved IP address

If you have reserved a public IP address you can assign it to a Kubernetes load balancer to ensure public routing into a service remains constant even if you change the service itself. The annotation for your service definition is as follows:

    kubernetes.civo.com/ipv4-address: "value of reserved IP address"

Charges for Load Balancers

Each Kubernetes cluster on Civo is assigned a public IP address on creation. This IP address can receive traffic, and route it according to NodePort ingress rules or another Service object. Each Load Balancer object you create will claim another public IP address that is assigned by the Civo API, your account will be charged for second and subsequent Load Balancers. You can check up-to-date pricing on the Pricing page.

The charge for the Load Balancer and additional public IP will end when the Service object is deleted.

Deleting a Load Balancer

The Cloud Controller Manager (CCM) running in your cluster will handle the deletion of a Civo Load Balancer once the accompanying Service is deleted from your cluster. You can delete the load balancer, and stop billing for the load balancer, by either deleting the service definition using the manifest file as in the example below, or by deleting the service from the cluster itself:

$ kubectl delete -f loadbalancer.yaml
service "civo-lb-service" deleted

$ kubectl get svc
NAME                TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)          AGE
kubernetes          ClusterIP       <none>          443/TCP          5d22h
my-app              ClusterIP   <none>          5000/TCP         4d18h

You will be able to see the load balancer is removed both from the services list as shown in the output above, and from the Civo dashboard page for your cluster. The public IP address will cease to route to your cluster immediately.