Merge pull request #2225 from tomdee/ipam-docs

IPAM docs

master/reference/calicoctl/resources/ippool.md

@@ -35,11 +35,13 @@ spec:
 
 | Field       | Description                 | Accepted Values   | Schema | Default    |
 |-------------|-----------------------------|-------------------|--------|------------|
-| cidr     | IP range to use for this pool.  | A valid IPv4 or IPv6 CIDR. Subnet length must be `/26` or less for IPv4 and `/122` or less for IPv6. Must not overlap with the Link Local range `169.254.0.0/16` or `fe80::/10`. | string | |
+| cidr     | IP range to use for this pool.  | A valid IPv4 or IPv6 CIDR. Subnet length must be at least big enough to fit a single block (by default `/26` for IPv4 or `/122` for IPv6). Must not overlap with the Link Local range `169.254.0.0/16` or `fe80::/10`. | string | |
+| blockSize | The CIDR size of allocation blocks used by this pool. Blocks are allocated on demand to hosts and are used to aggregate routes. The value can only be set when the pool is created. | 20 to 32 (inclusive) for IPv4 and 116 to 128 (inclusive) for IPv6 | int| `26` for IPv4 pools and `122` for IPv6 pools. |
 | ipipMode | The IPIP mode defining when IPIP will be used. | Always, CrossSubnet, Never | string| `Never` |
 | natOutgoing | When enabled, packets sent from {{site.prodname}} networked containers in this pool to destinations outside of this pool will be masqueraded. | true, false | boolean | `false` |
 | disabled | When set to true, {{site.prodname}} IPAM will not assign addresses from this pool. | true, false | boolean | `false` |
 
+#### IPIP
 Routing of packets using IP-in-IP will be used when the destination IP address
 is in an IP Pool that has IPIP enabled.  In addition, if the `ipipMode` is set to `CrossSubnet`,
 {{site.prodname}} will only route using IP-in-IP if the IP address of the destination node is in a different
@@ -56,6 +58,12 @@ Hosts running {{site.prodname}} is asymmetric and may cause traffic to be filter
 [RPF](https://en.wikipedia.org/wiki/Reverse_path_forwarding) checks failing.
 {: .alert .alert-info}
 
+#### Block Sizes
+The default block sizes of `26` for IPv4 and `122` for IPv6 provide blocks of 64 addresses. This allows addresses to be allocated in groups to workloads running on the same host. By grouping addresses, fewer routes need to be exchanged between hosts and to other BGP peers. If a host allocates all of the addresses in a block then it will be allocated an additional block. If there are no more blocks available then the host can take addresses from blocks allocated to other hosts. Specific routes are added for the borrowed addresses which has an impact on route table size.
+
+Increasing the block size from the default (e.g., using `24` for IPv4 to give 256 addresses per block) means fewer blocks per host, and potentially fewer routes. But try to ensure that there are at least as many blocks in the pool as there are hosts.
+
+Reducing the block size from the default (e.g., using `28` for IPv4 to give 16 addresses per block) means more blocks per host and therefore potentially more routes. This can be beneficial if it allows the blocks to be more fairly distributed amongst the hosts.
 
 ### Supported operations
 

master/reference/cni-plugin/configuration.md

@@ -100,8 +100,8 @@ By default, {{site.prodname}} IPAM will assign IP addresses from all the availab
 
 Optionally, the list of possible IPv4 and IPv6 pools can also be specified via the following properties:
 
-* `ipv4_pools`: An array of CIDR strings (e.g. `"ipv4_pools": ["10.0.0.0/24", "20.0.0.0/16"]`)
-* `ipv6_pools`: An array of CIDR strings (e.g. `"ipv6_pools": ["2001:db8::1/120"]`)
+* `ipv4_pools`: An array of CIDR strings or pool names. (e.g., `"ipv4_pools": ["10.0.0.0/24", "20.0.0.0/16", "default-ipv4-ippool"]`)
+* `ipv6_pools`: An array of CIDR strings or pool names.  (e.g., `"ipv6_pools": ["2001:db8::1/120", "namedpool"]`)
 
 Example CNI config:
 
@@ -114,8 +114,8 @@ Example CNI config:
         "type": "calico-ipam",
         "assign_ipv4": "true",
         "assign_ipv6": "true",
-        "ipv4_pools": ["10.0.0.0/24", "20.0.0.0/16"],
-        "ipv6_pools": ["2001:db8::1/120"]
+        "ipv4_pools": ["10.0.0.0/24", "20.0.0.0/16", "default-ipv4-ippool"],
+        "ipv6_pools": ["2001:db8::1/120", "default-ipv6-ippool"]
     }
 }
 ```
@@ -254,17 +254,17 @@ When making use of the `usePodCidr` option, the {{site.prodname}} CNI plugin req
 
 ### IPAM Manipulation with Kubernetes Annotations
 
-#### Specifying IP pools on a per-Pod basis
+#### Specifying IP pools on a per-namespace or per-pod basis
 
-In addition to specifying IP pools in the CNI config as discussed above, {{site.prodname}} IPAM supports specifying IP pools per-Pod using the following [Kubernetes annotations](https://kubernetes.io/docs/user-guide/annotations/).
+In addition to specifying IP pools in the CNI config as discussed above, {{site.prodname}} IPAM supports specifying IP pools per-namespace or per-pod using the following [Kubernetes annotations](https://kubernetes.io/docs/user-guide/annotations/).
 
 - `cni.projectcalico.org/ipv4pools`: A list of configured IPv4 Pools from which to choose an address for the Pod.
 
    Example:
 
    ```yaml
    annotations:
-      "cni.projectcalico.org/ipv4pools": "[\"192.168.0.0/16\"]"
+      "cni.projectcalico.org/ipv4pools": "[\"default-ipv4-ippool\"]"
    ```
 
 - `cni.projectcalico.org/ipv6pools`: A list of configured IPv6 Pools from which to choose an address for the Pod.
@@ -278,7 +278,6 @@ In addition to specifying IP pools in the CNI config as discussed above, {{site.
 
 If provided, these IP pools will override any IP pools specified in the CNI config.
 
-
 > **Note**: This requires the IP pools to exist before `ipv4pools` or
 > `ipv6pools` annotations are used. Requesting a subset of an IP pool
 > is not supported. IP pools requested in the annotations must exactly