IP Address Management (IPAM)

Infrahub provides a full-featured IPAM system for managing IP addresses, prefixes, and namespaces with automatic hierarchy reconciliation.

IPAM Hierarchy

Infrahub IPAM uses a parent-child hierarchy:

Namespace: default
├── 10.0.0.0/8 (parent)
│   ├── 10.0.0.0/16 (child)
│   │   ├── 10.0.1.0/24 (child)
│   │   │   ├── 10.0.1.1/32 (IP address)
│   │   │   ├── 10.0.1.2/32 (IP address)
│   │   │   └── 10.0.1.3/32 (IP address)
│   │   └── 10.0.2.0/24 (child)
│   └── 10.1.0.0/16 (child)

The IPAM reconciler automatically maintains this hierarchy when you create, update, or delete prefixes.

IP Namespaces

Namespaces provide isolation for overlapping IP space (e.g., multi-tenant, VRFs, environments).

Creating a Namespace

UI
GraphQL
Python SDK

Navigate to IPAM → Namespaces
Click Add Namespace
Set Name and Description
Click Save

mutation {
  IpamNamespaceCreate(
    data: {
      name: { value: "production" }
      description: { value: "Production network namespace" }
    }
  ) {
    ok
    object {
      id
      display_label
    }
  }
}

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

namespace = await client.create(
    kind="IpamNamespace",
    name="production",
    description="Production network namespace"
)
await namespace.save()

The default namespace is created automatically during Infrahub initialization.

IP Prefixes

Prefixes represent network subnets (e.g., 10.0.1.0/24, 2001:db8::/32).

Creating a Prefix

UI
GraphQL
Python SDK

Navigate to IPAM → Prefixes
Click Add Prefix
Set:
- Prefix: CIDR notation (e.g., 10.0.1.0/24)
- IP Namespace: Select namespace
- Status: Active, reserved, deprecated, etc.
- Member Type: Prefix or pool
- Description: Purpose of the prefix
Click Save

The IPAM reconciler automatically sets the parent-child relationships.

mutation {
  IpamIPPrefixCreate(
    data: {
      prefix: { value: "10.0.1.0/24" }
      ip_namespace: { hfid: ["default"] }
      status: { value: "active" }
      member_type: { value: "prefix" }
      description: { value: "Atlanta site network" }
    }
  ) {
    ok
    object {
      id
      prefix { value }
      parent { id }  # Automatically set
      is_top_level { value }  # Auto-calculated
    }
  }
}

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

# Get the namespace
namespace = await client.get(
    kind="IpamNamespace",
    name__value="default"
)

# Create prefix
prefix = await client.create(
    kind="IpamIPPrefix",
    prefix="10.0.1.0/24",
    ip_namespace=namespace.id,
    status="active",
    member_type="prefix",
    description="Atlanta site network"
)
await prefix.save()

# Reconcile the IPAM hierarchy
from infrahub.core.ipam.reconciler import IpamReconciler
import ipaddress

reconciler = IpamReconciler(db=db, branch=branch)
await reconciler.reconcile(
    ip_value=ipaddress.ip_network("10.0.1.0/24"),
    namespace=namespace.id,
    node_uuid=prefix.id
)

IPAM Reconciliation

The IpamReconciler automatically maintains the parent-child hierarchy:

from infrahub.core.ipam.reconciler import IpamReconciler
import ipaddress

reconciler = IpamReconciler(db=db, branch=branch)

# Reconcile after creating/updating a prefix
await reconciler.reconcile(
    ip_value=ipaddress.ip_network("10.0.1.0/24"),
    namespace=namespace_id,
    node_uuid=prefix_id
)

Reconciliation:

Finds the closest parent prefix (longest prefix match)
Sets the parent relationship
Updates is_top_level flag
Moves orphaned children to the new parent
Updates children and ip_addresses relationships

Prefix Queries

Find prefixes by various criteria:

query {
  IpamIPPrefix(
    prefix__value: "10.0.1.0/24"
    ip_namespace: { name: { value: "default" } }
  ) {
    edges {
      node {
        id
        prefix { value }
        parent {
          id
          prefix { value }
        }
        children {
          edges {
            node {
              prefix { value }
            }
          }
        }
        ip_addresses {
          edges {
            node {
              address { value }
            }
          }
        }
      }
    }
  }
}

IP Addresses

IP addresses are specific IPs within prefixes (e.g., 10.0.1.5/32).

Creating an IP Address

UI
GraphQL
Python SDK

Navigate to IPAM → IP Addresses
Click Add IP Address
Set:
- Address: IP with prefix length (e.g., 10.0.1.5/32)
- IP Namespace: Select namespace
- Status: Active, reserved, etc.
- Description: What uses this IP
Click Save

The IPAM reconciler automatically links the IP to its parent prefix.

mutation {
  IpamIPAddressCreate(
    data: {
      address: { value: "10.0.1.5/32" }
      ip_namespace: { hfid: ["default"] }
      status: { value: "active" }
      description: { value: "Web server" }
    }
  ) {
    ok
    object {
      id
      address { value }
      ip_prefix { id }  # Automatically set by reconciler
    }
  }
}

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

namespace = await client.get(
    kind="IpamNamespace",
    name__value="default"
)

ip_address = await client.create(
    kind="IpamIPAddress",
    address="10.0.1.5/32",
    ip_namespace=namespace.id,
    status="active",
    description="Web server"
)
await ip_address.save()

Assigning IPs to Interfaces

Link IP addresses to device interfaces:

mutation {
  IpamIPAddressUpdate(
    data: {
      id: "<ip-address-uuid>"
      interface: { id: "<interface-uuid>" }
    }
  ) {
    ok
  }
}

Or create the IP with the interface:

mutation {
  IpamIPAddressCreate(
    data: {
      address: { value: "10.0.1.5/32" }
      ip_namespace: { hfid: ["default"] }
      interface: { id: "<interface-uuid>" }
    }
  ) {
    ok
    object {
      id
    }
  }
}

Resource Allocator

The IPAMResourceAllocator finds the next available prefix or IP address.

Allocating Prefixes

from infrahub.core.ipam.resource_allocator import IPAMResourceAllocator
import ipaddress

allocator = IPAMResourceAllocator(
    db=db,
    namespace=namespace,
    branch=branch,
    branch_agnostic=True  # Search across all branches
)

# Get next available /24 from 10.0.0.0/16
parent_prefix = ipaddress.ip_network("10.0.0.0/16")
next_prefix = await allocator.get_next_prefix(
    ip_prefix=parent_prefix,
    target_prefix_length=24
)

print(f"Next available /24: {next_prefix}")
# Output: 10.0.1.0/24 (if 10.0.0.0/24 is already used)

The allocator:

Queries all child prefixes using IPPrefixSubnetFetchFree
Calculates gaps in the address space
Returns the first available prefix of the requested length

Allocating IP Addresses

from infrahub.core.ipam.resource_allocator import IPAMResourceAllocator
import ipaddress

allocator = IPAMResourceAllocator(db=db, namespace=namespace, branch=branch)

# Get next available IP from 10.0.1.0/24
prefix = ipaddress.ip_network("10.0.1.0/24")
next_ip = await allocator.get_next_address(ip_prefix=prefix)

print(f"Next available IP: {next_ip}")
# Output: 10.0.1.1 (skips network address 10.0.1.0)

By default, the allocator skips:

Network address (first IP)
Broadcast address (last IP)

For pools where these are usable:

next_ip = await allocator.get_next_address(
    ip_prefix=prefix,
    is_pool=True  # Allow network and broadcast
)

IPv6 Support

The allocator handles IPv6’s 128-bit address space using binary string operations:

import ipaddress

# Allocate IPv6 prefix
parent = ipaddress.ip_network("2001:db8::/32")
next_prefix = await allocator.get_next_prefix(
    ip_prefix=parent,
    target_prefix_length=48
)

# Allocate IPv6 address
prefix = ipaddress.ip_network("2001:db8:1::/64")
next_ip = await allocator.get_next_address(ip_prefix=prefix)

Prefix Utilization

Query prefix utilization to monitor capacity:

query {
  IpamIPPrefix(prefix__value: "10.0.0.0/16") {
    edges {
      node {
        prefix { value }
        utilization
        children {
          count
        }
        ip_addresses {
          count
        }
      }
    }
  }
}

Or use the utilization API:

from infrahub.core.ipam.utilization import get_prefix_utilization

util = await get_prefix_utilization(
    db=db,
    prefix_id=prefix_id,
    branch=branch
)

print(f"Utilization: {util.percentage:.1f}%")
print(f"Used: {util.used} / {util.total}")

IPAM with Resource Manager

Combine IPAM with Resource Manager for automatic allocation (see Resource Manager guide):

# Create IP Prefix Pool
pool = await client.create(
    kind="CoreIPPrefixPool",
    name="Site Subnets",
    ip_namespace=namespace.id,
    default_prefix_length=24,
    resources=[parent_prefix.id]
)
await pool.save()

# Allocate from pool
prefix = await pool.get_resource(
    db=db,
    branch=branch,
    identifier="site-atl1",
    prefixlen=24
)

This creates the prefix and reconciles the IPAM hierarchy automatically.

Best Practices

Use namespaces: Isolate IP space by tenant, environment, or VRF
Let reconciliation work: Don’t manually set parent relationships
Allocate top-down: Create large prefixes first, then subdivide
Track assignments: Link IPs to interfaces for visibility
Monitor utilization: Set alerts at 80% capacity
Use pools: Automate allocation with Resource Manager pools
Reserve network IPs: Mark .0 and .255 as reserved
Document prefixes: Use description to explain purpose

Common Patterns

Hierarchical Allocation

# 1. Create regional prefix
regional = await client.create(
    kind="IpamIPPrefix",
    prefix="10.0.0.0/16",
    description="US East region"
)

# 2. Create site prefixes
site1 = await client.create(
    kind="IpamIPPrefix",
    prefix="10.0.1.0/24",
    description="Atlanta site"
)

# 3. Allocate IPs for devices
ip1 = await client.create(
    kind="IpamIPAddress",
    address="10.0.1.1/32",
    description="Gateway"
)

The reconciler automatically links: regional → site1 → ip1

Multi-Tenant IPAM

# Create namespace per tenant
for tenant in ["acme", "globex", "initech"]:
    ns = await client.create(
        kind="IpamNamespace",
        name=tenant
    )
    await ns.save()

    # Each tenant can use the same IP space
    prefix = await client.create(
        kind="IpamIPPrefix",
        prefix="10.0.0.0/16",
        ip_namespace=ns.id
    )
    await prefix.save()

Next Steps

Use Resource Manager for automatic IP allocation
Organize prefixes with Groups
Apply IPAM settings with Profiles

Get Started

Core Concepts

Schema & Data Modeling

Data Management

Version Control & Branching

Transformations & Artifacts

Integration & Automation

Deployment & Operations

IP Address Management (IPAM)

IPAM Hierarchy

IP Namespaces

Creating a Namespace

IP Prefixes

Creating a Prefix

IPAM Reconciliation

Prefix Queries

IP Addresses

Creating an IP Address

Assigning IPs to Interfaces

Resource Allocator

Allocating Prefixes

Allocating IP Addresses

IPv6 Support

Prefix Utilization

IPAM with Resource Manager

Best Practices

Common Patterns

Hierarchical Allocation

Multi-Tenant IPAM

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Schema & Data Modeling

Data Management

Version Control & Branching

Transformations & Artifacts

Integration & Automation

Deployment & Operations

​IPAM Hierarchy

​IP Namespaces

​Creating a Namespace

​IP Prefixes

​Creating a Prefix

​IPAM Reconciliation

​Prefix Queries

​IP Addresses

​Creating an IP Address

​Assigning IPs to Interfaces

​Resource Allocator

​Allocating Prefixes

​Allocating IP Addresses

​IPv6 Support

​Prefix Utilization

​IPAM with Resource Manager

​Best Practices

​Common Patterns

​Hierarchical Allocation

​Multi-Tenant IPAM

​Next Steps

Build docs developers (and LLMs) love

IPAM Hierarchy

IP Namespaces

Creating a Namespace

IP Prefixes

Creating a Prefix

IPAM Reconciliation

Prefix Queries

IP Addresses

Creating an IP Address

Assigning IPs to Interfaces

Resource Allocator

Allocating Prefixes

Allocating IP Addresses

IPv6 Support

Prefix Utilization

IPAM with Resource Manager

Best Practices

Common Patterns

Hierarchical Allocation

Multi-Tenant IPAM

Next Steps