Doc: Improve network load-balancer instructions and add examples (#14654

)

The existing doc says that if target ports are not provided, "the listen
ports for the backend" will be used. This is incorrect (or at least,
incomplete) as the backend specification does not define listen ports;
the ports specification associated with that backend does. This PR
clarifies and expands on how this works, including what happens if
target ports are not provided _and_ no ports specification associated
with that backend exists.

Also:
* Adds command syntax examples
* Removes redundancy in explaining how allocate flag is used
* Minor grammar/formatting improvements
* Shows example YAML configuration file

doc/howto/network_load_balancers.md

@@ -9,9 +9,9 @@ discourse: lxc:14317
 Network load balancers are currently available for the {ref}`network-ovn`.
 ```
 
-Network load balancers are similar to forwards in that they allow specific ports on an external IP address to be forwarded to specific ports on internal IP addresses in the network that the load balancer belongs to. The difference between load balancers and forwards is that load balancers can be used to share ingress traffic between multiple internal backend addresses.
+Network load balancers are similar to forwards in that they allow specific ports on an external IP address to be forwarded to specific ports on internal IP addresses in the network that the load balancer belongs to.
 
-This feature can be useful if you have limited external IP addresses or want to share a single external address and ports over multiple instances.
+The difference between load balancers and forwards is that load balancers can be used to share ingress traffic between multiple internal backend addresses. This feature can be useful if you have limited external IP addresses or want to share a single external address and ports over multiple instances.
 
 A load balancer is made up of:
 
@@ -27,9 +27,21 @@ Use the following command to create a network load balancer:
 lxc network load-balancer create <network_name> [<listen_address>] [--allocate=ipv{4,6}] [configuration_options...]
 ```
 
+Example with a specified listen address:
+
+```bash
+lxc network load-balancer create my-ovn-network 192.0.2.178
+```
+
+Example with an allocated listen address:
+
+```bash
+lxc network load-balancer create my-ovn-network --allocate=ipv4
+```
+
 Each load balancer is assigned to a network.
-Listen addresses are subject to restrictions (see {ref}`network-load-balancers-listen-addresses` for more information about which addresses can be load-balanced).
-If a listen address is not given, the `--allocate` flag must be provided.
+
+Listen addresses are subject to restrictions. If a listen address is not specified, the `--allocate` flag must be provided. See {ref}`network-load-balancers-listen-addresses` for more information about which addresses can be load-balanced, as well as how to use the `--allocate` flag.
 
 ### Load balancer properties
 
@@ -46,24 +58,33 @@ Network load balancers have the following properties:
 
 The following requirements must be met for valid listen addresses:
 
-- Allowed listen addresses must be defined in the uplink network's `ipv{n}.routes` settings or the project's {config:option}`project-restricted:restricted.networks.subnets` setting (if set).
+- Allowed listen addresses must be defined in the uplink network's `ipv{n}.routes` settings or the project's {config:option}`project-restricted:restricted.networks.subnets` setting.
+   - If you specify a listen address when creating a load balancer, it must be within the range of allowed addresses.
+   - If you do not specify a listen address, you must use either `--allocate ipv4` or `--allocate ipv6`. This will allocate a listen address from the range of allowed addresses.
 - The listen address must not overlap with a subnet that is in use with another network or entity in that network.
-- If the `--allocate` flag is provided, an IP address will be allocated from the uplink network's `ipv{n}.routes` or the project's {config:option}`project-restricted:restricted.networks.subnets` setting (if set).
 
 (network-load-balancers-backend-specifications)=
 ## Configure backends
 
 You can add backend specifications to the network load balancer to define target addresses (and optionally ports).
-The backend target address must be within the same subnet as the network that the load balancer is associated to.
+The backend target address must be within the same subnet as the network associated with the load balancer.
 
 Use the following command to add a backend specification:
 
 ```bash
 lxc network load-balancer backend add <network_name> <listen_address> <backend_name> <target_address> [<target_ports>]
 ```
 
-The target ports are optional.
-If not specified, the load balancer will use the listen ports for the backend for the backend target ports.
+Example:
+
+```bash
+lxc network load-balancer backend add my-ovn-network 192.0.2.178 test-backend 10.41.211.5
+```
+
+If no target ports are specified when adding the backend:
+
+- The load balancer uses the listen ports defined in the [port specification](#port-properties) associated with that backend, if any.
+- If no such listen ports are defined, the backend has no target ports and is inactive. You must either [add a port specification](#port-properties) or [edit the load balancer configuration](#edit-a-network-load-balancer) to include a `target_port` value in the backend specification or a `listen_port` value in the ports specification.
 
 If you want to forward the traffic to different ports, you have two options:
 
@@ -91,6 +112,12 @@ Use the following command to add a port specification:
 lxc network load-balancer port add <network_name> <listen_address> <protocol> <listen_ports> <backend_name>[,<backend_name>...]
 ```
 
+Example:
+
+```bash
+lxc network load-balancer port add my-ovn-network 192.0.2.178 tcp 80 test-backend
+```
+
 You can specify a single listen port or a set of ports.
 The backend(s) specified must have target port(s) settings compatible with the port's listen port(s) setting.
 
@@ -113,7 +140,27 @@ lxc network load-balancer edit <network_name> <listen_address>
 ```
 
 This command opens the network load balancer in YAML format for editing.
-You can edit both the general configuration, backend and the port specifications.
+You can edit the general configuration, as well as the backend and port specifications.
+
+Example load balancer configuration YAML file:
+
+```yaml
+listen_address: 192.0.2.178
+location: ""
+description: ""
+config: {}
+backends:
+- name: test-backend
+  description: ""
+  target_port: ""
+  target_address: 10.41.211.5
+ports:
+- description: ""
+  protocol: tcp
+  listen_port: 70,80-90
+  target_backend:
+  - test-backend
+```
 
 ## Delete a network load balancer