docs: Clarity on how the load-balancer feature allows for adjusting IPAddress pools

[106106]

Please describe the question or issue you're facing with "How to use the default load balancer".

We received customer feedback in a support case that:

The documentation doesn't provide clear examples, only conceptual and superficial information.

Would it be possible to provide more / clearer examples and information on how to configure the IP address pool that will be used by the load balancer?

---

Reported from: https://documentation.ubuntu.com/canonical-kubernetes/latest/snap/howto/networking/default-loadbalancer/

[addyess]

Thanks for reporting the issue, A card has been added to the backlog to address and provide more clear examples.

Do you have anything you'd like specifically to see in the docs that could make it better.

I believe you're asking for more a clear example of how to set the IP Address Pool based on the "cidrs" argument

sudo k8s set load-balancer.cidrs="????"

[106106]

Yes, exactly. Maybe just a toy example using l2-mode to get a developer testing out Canonical Kubernetes starter. I'm thinking along the lines of:

Enable the load balancer

sudo k8s enable load-balancer

Check the status

sudo k8s get load-balancer
sudo k8s status

Sample output

sudo k8s status
enabled: true
cidrs: []
l2-mode: true
l2-interfaces: []
bgp-mode: false
bgp-local-asn: 0
bgp-peer-address: ""
bgp-peer-asn: 0
bgp-peer-port: 0

cluster status:           ready
control plane nodes:      10.35.84.247:6400 (voter), 10.35.84.12:6400 (voter), 10.35.84.164:6400 (voter)
high availability:        yes
datastore:                k8s-dqlite
network:                  enabled
dns:                      enabled at 10.152.183.48
ingress:                  disabled
load-balancer:            enabled, L2 mode
local-storage:            enabled at /var/snap/k8s/common/rawfile-storage
gateway                   enabled

Since these are multipass VMs and they are available locally, we should be able to test with unused IPs on 10.35.84.247/24

Name                    State             IPv4             Image
k8s-ctrl-01             Running           10.35.84.247     Ubuntu 24.04 LTS
                                          10.1.0.19
k8s-ctrl-02             Running           10.35.84.12      Ubuntu 24.04 LTS
                                          10.1.1.127
k8s-ctrl-03             Running           10.35.84.164     Ubuntu 24.04 LTS
                                          10.1.2.155
k8s-wrk-01              Running           10.35.84.42      Ubuntu 24.04 LTS
                                          10.1.3.170
k8s-wrk-02              Running           10.35.84.223     Ubuntu 24.04 LTS
                                          10.1.4.4

Since we are using l2-mode this is relatively straight forward. See Advertising IP address externally for more details

Lets use 10.35.84.100-10.35.84.110. Note: this will depend on your network setup and available IPs for your cluster.

sudo k8s set load-balancer.cidrs="10.35.84.100-10.35.84.110"

Check status

sudo k8s get load-balancer

sample output

enabled: true
cidrs:
- 10.35.84.100-10.35.84.110
l2-mode: true
l2-interfaces: []
bgp-mode: false
bgp-local-asn: 0
bgp-peer-address: ""
bgp-peer-asn: 0
bgp-peer-port: 0

Test

Create a nginx deployment

sudo k8s kubectl create deployment nginx --image=nginx --replicas 5

Check the pods are deployed

sudo k8s kubectl get pods -o wide

Sample output

NAME                     READY   STATUS    RESTARTS   AGE     IP           NODE          NOMINATED NODE   READINESS GATES
nginx-5869d7778c-hcvm8   1/1     Running   0          2m28s   10.1.1.232   k8s-ctrl-02   <none>           <none>
nginx-5869d7778c-jd5pc   1/1     Running   0          2m28s   10.1.2.93    k8s-ctrl-03   <none>           <none>
nginx-5869d7778c-kqwls   1/1     Running   0          2m28s   10.1.0.31    k8s-ctrl-01   <none>           <none>
nginx-5869d7778c-vhwbg   1/1     Running   0          2m28s   10.1.3.57    k8s-wrk-01    <none>           <none>
nginx-5869d7778c-zzq7p   1/1     Running   0          2m28s   10.1.4.154   k8s-wrk-02    <none>           <none>

Expose the deployment

sudo k8s kubectl expose deployment nginx --port=80 --target-port=80 --type=LoadBalancer

Check the service

sudo  k8s kubectl get service nginx

Sample output

NAME    TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)        AGE
nginx   LoadBalancer   10.152.183.37   10.35.84.100   80:31344/TCP   23s

You should now be able to curl the address

curl 10.35.84.100

And

sudo  k8s kubectl describe service nginx

sample output

Name:                     nginx
Namespace:                default
Labels:                   app=nginx
Annotations:              metallb.io/ip-allocated-from-pool: metallb-loadbalancer-ck-loadbalancer
Selector:                 app=nginx
Type:                     LoadBalancer
IP Family Policy:         SingleStack
IP Families:              IPv4
IP:                       10.152.183.37
IPs:                      10.152.183.37
LoadBalancer Ingress:     10.35.84.100 (VIP)
Port:                     <unset>  80/TCP
TargetPort:               80/TCP
NodePort:                 <unset>  31344/TCP
Endpoints:                10.1.0.31:80,10.1.3.57:80,10.1.1.232:80 + 2 more...
Session Affinity:         None
External Traffic Policy:  Cluster
Internal Traffic Policy:  Cluster
Events:
  Type    Reason        Age    From                Message
  ----    ------        ----   ----                -------
  Normal  IPAllocated   3m40s  metallb-controller  Assigned IP ["10.35.84.100"]
  Normal  nodeAssigned  3m40s  metallb-speaker     announcing from node "k8s-ctrl-02" with protocol "layer2"