Allocate IPs and prefixes

When to allocate from a pool

Allocate from a Resource Pool when something other than a person assigns the address — a provisioning pipeline creating devices, a Generator rendering configuration, a CI/CD job reserving space for a new service. If you are only recording and querying IP data that already exists, the IPAM nodes alone are enough.

Use a resource pool

Resource Pool is the recommended way to allocate IP addresses and prefixes. A CoreIPAddressPool or CoreIPPrefixPool takes your IPAM prefixes as its resources and returns the next available address or subnet on request.

mutation {
  CoreIPAddressPoolCreate(data: {
    name: {value: "Management IP Pool"},
    default_address_type: {value: "IpamIPAddress"},
    default_prefix_length: {value: 24},
    resources: [{id: "<IpamIPPrefix-id>"}],
    ip_namespace: {id: "default"}
  }) {
    ok
    object {
      id
    }
  }
}

The resources field references the IpamIPPrefix objects the pool allocates from, and is the connection point between IPAM and Resource Manager. When you pass the same identifier on repeated allocation requests through the GraphQL API, Infrahub returns the existing allocation instead of creating a new one, on any branch that can read that allocation. A provisioning script can then run more than once without allocating a second address or subnet for the same object. Infrahub also handles one allocation request at a time for each pool, across every Infrahub worker, so two concurrent requests against the same pool never get the same resource. The Resource Manager page has the full identifier rules.

For the full allocation walkthrough — creating the source prefix, creating the pool, and allocating directly or during node creation — see Allocate IP addresses and Allocate IP prefixes.

Allocate from generators

A Generator has the same Python SDK client available anywhere else, so allocating from a Resource Pool inside a Generator is a regular SDK call:

device_loopback = await client.allocate_next_ip_address(
    resource_pool=loopback_pool,
    identifier=device_name,
    data={"interface": interface.id},
    branch=branch,
)

interconnect_subnet = await client.allocate_next_ip_prefix(
    resource_pool=interconnection_pool,
    kind=IpamIPPrefix,
    identifier=network.identifier,
    branch=branch,
)

allocate_next_ip_address and allocate_next_ip_prefix take the same resource_pool and identifier arguments as the underlying InfrahubIPAddressPoolGetResource and InfrahubIPPrefixPoolGetResource mutations — passing a stable identifier (for example, the device name) keeps a Generator idempotent across reruns. The infrastructure-edge topology model is a worked example that allocates loopback and management addresses, and interconnection subnets, this way.

Advanced: next-available GraphQL primitives

InfrahubIPAddressGetNextAvailable and InfrahubIPPrefixGetNextAvailable are read-only GraphQL queries that return the next free address or subnet from a given prefix. Unlike a Resource Pool allocation, they don't create a record, and they don't provide the pool's cross-branch allocation guarantee — two callers on different branches can compute the same "next available" value independently and collide.

Use Resource Pool for production workflows. Use these queries only to look up a value without persisting it.