This page explains what IP resource pools are, which named pools exist, what each pool is used for, how to size them correctly for a site, and how to inspect and grow them at runtime.
It is intended for operations engineers deploying or scaling a NICo-managed site who need to configure IP address pools in the API server configuration.
The NICo API server manages several distinct IP address pools. Each pool is drawn down as the system allocates addresses for a specific purpose. When a pool is exhausted, the operations that depend on it are blocked immediately — there is no fallback or queuing behavior.
Pool capacity planning is therefore a pre-deployment concern. Pools can be extended at runtime without a restart, but running out of addresses causes provisioning failures that must be resolved before work can continue.
Note: Tenant instance IP addresses — the addresses that instances see on their network interfaces — are not managed through IP resource pools. The pools described on this page are infrastructure addresses, not tenant workload addresses.
The following IP pools are recognized by the API server.
lo-ip — DPU Loopback IPsEach managed DPU receives a loopback IP address from this pool. The loopback is advertised over BGP and serves as the VTEP address for the VXLAN underlay. It is also used for BGP peering identification.
One address is consumed per DPU at the time the DPU is first registered with the system. If a DPU is decommissioned, its address is returned to the pool.
vpc-dpu-lo — VPC DPU Loopback IPsWhen a VPC is created and an instance is placed on a DPU for the first time, a loopback IP is allocated for that specific (VPC, DPU) pair. This IP is used as the per-VPC VTEP in the VPC overlay network.
Consumption is demand-driven: addresses are allocated as instances spread across DPUs, and deallocated when all instances for a VPC are removed from a given DPU.
IP pools are defined in the [pools.<name>] section of the API server TOML configuration.
Every pool definition requires a type field and either a prefix or a ranges list. Providing both, or providing neither, is a configuration error that prevents startup.
The pool contains all usable host addresses within the given CIDR prefix. Broadcast and network addresses are excluded automatically.
The pool contains exactly the addresses specified. Multiple ranges may be listed; they are additive.
Both IP pools described on this page use type = "ipv4".
lo-ipOne address is consumed per managed DPU. For a site with H hosts, each having D DPUs:
For example, 100 hosts with 2 DPUs each require 200 addresses.
docs/manuals/networking_requirements.md states the combined IPv4 prefix requirement as (expected number of servers + expected number of DPUs) × 2 + 2. The lo-ip pool supplies the per-DPU loopback portion of that allocation. The remainder of the formula covers admin and other infrastructure addresses.
vpc-dpu-loConsumption depends on the number of VPCs and how broadly their instances are distributed across DPUs. In the worst case, every DPU participates in every VPC:
In practice, consumption is typically lower because tenant workloads are not spread uniformly across the entire fleet. Plan for the worst case unless site-specific workload data supports a smaller estimate.
docs/manuals/networking_requirements.md notes that a separate IPv4 prefix is required for these addresses, with a total allocation of expected number of DPUs × 2 at minimum. Size the vpc-dpu-lo pool within that allocation, leaving headroom for VPC growth.
Plan for fleet growth and leave headroom in all pools. Growing a pool requires only a grow operation (described below) with no service restart, but an exhausted pool blocks provisioning immediately. A reasonable starting margin is 20–25% above the expected peak allocation for the initial site scale.
At startup, the API server registers every pool defined in [pools.*] into the database.
This operation is additive only. Existing pools can be extended with new ranges or a larger prefix; they cannot be shrunk. This means a misconfigured range that was once registered cannot be removed by changing the config — it persists in the database. New ranges defined in the config are added to the existing pool on the next startup.
If listen_only = true is set in the API server configuration, pool registration is skipped on that instance. It assumes another instance has already populated the pools.
This queries the API server for current pool state. The output is a table with the following columns:
Monitor pools that are approaching their limit. When Used is near Size, the next provisioning operation that needs that pool will fail. Grow the pool before that point.
The file must contain a TOML snippet using the same [pools.<name>] format as the API server configuration. Any pool definitions in the file that introduce new ranges or a larger prefix are applied immediately. The operation does not require a service restart.
Constraints:
Example grow file (grow-lo-ip.toml):
If the original pool was prefix-based, the grow file may also provide additional ranges using ranges — the two forms are not mutually exclusive when growing.
docs/manuals/vpc/vni_resource_pools.md — companion page covering VNI and VLAN ID resource poolsdocs/manuals/vpc/vpc_network_virtualization.md — end-to-end VPC network virtualization overview that ties VNI pools, IP pools, and routing profiles togetherdocs/manuals/networking_requirements.md — site-level networking requirements including IPv4 prefix sizing formulasdocs/manuals/vpc/vpc_routing_profiles.md — VPC routing profile configuration, which governs the VPC overlay network configuration and therefore drives vpc-dpu-lo consumption