Clarify documentation for IPPool and ExternalIPPool CRDs (#6183)

When defining a pool with a CIDR, the first and the last IP address will
usually be excluded. The last IP address (broadcast) is only excluded
for IPv4, and, for IPPool, only if the prefix length matches the CIDR
mask size.

Signed-off-by: Antonin Bas <[email protected]>

docs/antrea-ipam.md

@@ -439,7 +439,17 @@ spec:
 ## `IPPool` CRD
 
 Antrea IP pools are defined with the `IPPool` CRD. The following two examples
-define an IPv4 and an IPv6 IP pool respectively.
+define an IPv4 and an IPv6 IP pool respectively. The first example (IPv4) uses a
+CIDR to define the range of allocatable IPs, while the second example uses a
+"range", with a start and end IP address. When using a CIDR, it is important to
+keep in mind that the first IP in the CIDR will be excluded and will never be
+allocated. When the CIDR represents a traditional subnet, the first IP is
+typically the "network IP". Additionally, for IPv4, when the `prefixLength`
+matches the CIDR mask size, the last IP in the CIDR, which traditionally
+represents the "broadcast IP", will also be excluded. The provided gateway IP
+will of course always be excluded. On the other hand, when using a range with a
+start and end IP address, both of these IPs will be allocatable (except if one
+of them corresponds to the gateway).
 
 ```yaml
 apiVersion: "crd.antrea.io/v1alpha2"
@@ -449,9 +459,10 @@ metadata:
 spec:
   ipVersion: 4
   ipRanges:
+  # 61 different IPs can be allocated from this pool: 64 (2^6) - 3 (network IP, broadcast IP, gateway IP).
   - cidr: "10.10.1.0/26"
     gateway: "10.10.1.1"
-    prefixLength: 24
+    prefixLength: 26
 ```
 
 ```yaml
@@ -462,6 +473,7 @@ metadata:
 spec:
   ipVersion: 6
   ipRanges:
+  # 257 different IPs can be allocated from this pool: 0x200 - 0x100 + 1.
   - start: "3ffe:ffff:1:01ff::0100"
     end: "3ffe:ffff:1:01ff::0200"
     gateway: "3ffe:ffff:1:01ff::1"

docs/egress.md

@@ -199,6 +199,15 @@ The `ipRanges` field contains a list of IP ranges representing the available IPs
 of this IP pool. Each IP range may consist of a `cidr` or a pair of `start` and
 `end` IPs (which are themselves included in the range).
 
+When using a CIDR to define an IP range, it is important to keep in mind that
+the first IP in the CIDR will be excluded and will never be allocated. This is
+because when the CIDR represents a traditional subnet, the first IP is typically
+the "network IP". Additionally, for IPv4, the last IP in the CIDR, which
+traditionally represents the "broadcast IP", will also be excluded. As a result,
+providing a /32 CIDR or a /31 CIDR will yield an empty pool of IP addresses. A
+/28 CIDR will yield 14 allocatable IP addresses. In the future we may make this
+behavior configurable, so that the full CIDR can be used if desired.
+
 ### SubnetInfo
 
 By default, it's assumed that the IPs allocated from an ExternalIPPool are in