Allocate IP addresses

IP address pools (CoreIPAddressPool) dynamically allocate individual IP addresses from source prefixes.

Prerequisites

• A running Infrahub instance

Schema used in this guide

The examples on this page use the following schema nodes. Adapt the type names to match your own schema.

nodes:
  - name: IPPrefix
    namespace: Ipam
    inherit_from:
      - "BuiltinIPPrefix"

  - name: IPAddress
    namespace: Ipam
    inherit_from:
      - "BuiltinIPAddress"

  - name: Device
    namespace: Infra
    human_friendly_id: ["name__value"]
    attributes:
      - name: name
        kind: Text
        unique: true
    relationships:
      - name: primary_ip
        peer: IpamIPAddress
        kind: Attribute
        cardinality: one

Step 1: Create an IP prefix object

Create the IP prefix that serves as the allocation source:

Web interface

Navigate to IPAM → IP Prefixes and create a new prefix with:

• Prefix: 10.100.0.0/24
• Member Type: address

GraphQL

mutation {
  IpamIPPrefixCreate(data: {
    prefix: {value: "10.100.0.0/24"},
    member_type: {value: "address"}
  })
  {
    ok
    object {
      id
    }
  }
}

important

Save the prefix ID for the next step!

Step 2: Create the IP address pool

Create a CoreIPAddressPool Resource Manager:

Web interface

Navigate to Object Management → Resource Managers and create a new IP Address Pool with:

• Name: My IP address pool
• Default Address Type: IpamIPAddress
• Default Prefix Length: 24
• Resources: Select the 10.100.0.0/24 prefix
• IP Namespace: default

GraphQL

mutation {
  CoreIPAddressPoolCreate(data: {
    name: {value: "My IP address pool"},
    default_address_type: {value: "IpamIPAddress"},
    default_prefix_length: {value: 24},
    resources: [{id: "<prefix-id>"}],
    ip_namespace: {id: "default"}
  })
  {
    ok
    object {
      id
      hfid
    }
  }
}

important

Save the pool ID for allocation operations!

Step 3: Allocate IP addresses

You can allocate IP addresses in two ways: direct allocation or allocation during node creation.

Direct allocation

Allocate an IP address directly from the pool:

Web interface

Create an IP address. Next to the Address field, click the pool button, labeled "select a pool", and choose My IP address pool, then save. Infrahub allocates the next available address from the pool and creates the IP address with it.

Infrahub allocates a new address on each save. To get the same address back when a script or a Generator runs again, use the GraphQL method with an identifier.

GraphQL

mutation {
  InfrahubIPAddressPoolGetResource(
    data: {
      hfid: ["My IP address pool"]
      data: {description: "my first allocated ip"}
    }
  ) {
    ok
    node {
      id
      display_label
    }
  }
}

Idempotent allocation

Include an identifier field, and repeated calls with the same identifier return the same IP address:

mutation {
  InfrahubIPAddressPoolGetResource(
    data: {
      hfid: ["My IP address pool"]
      data: {description: "my first allocated ip"}
      identifier: "my-allocated-ip"
    }
  ) {
    ok
    node {
      id
      display_label
    }
  }
}

This is essential for Generators and automated workflows. On another branch that cannot read the allocated address yet, a request with the same identifier gets a different address. See Idempotent allocation for the rules.

success

You have created an IP address record from the pool!

Allocation during node creation

Allocate an IP address when creating a device:

Web interface

Navigate to Devices → Add Device. Next to the Primary IP Address field, click the pool button, labeled "select a pool", and choose your resource pool.

GraphQL

mutation {
  InfraDeviceCreate(
    data: {
      name: {value: "dev-123"}
      primary_ip: {from_pool: {id: "<POOL-ID>"}}
    }
  ) {
    ok
    object {
      display_label
      primary_ip {
        node {
          address {
            value
          }
        }
      }
    }
  }
}

success

The device is created with primary IP address allocated from the pool!

Allocate on a branch

When you allocate from the pool on a branch, Infrahub uses the pool's IP namespace and source prefixes as they exist on that branch. Infrahub skips a source prefix that does not exist on the branch, for example a prefix created on another branch that is not merged yet.

Infrahub does not allocate an address that any branch still holds, unless that branch is being deleted. For example, if you delete an allocated address on the default branch after you create a branch, Infrahub does not allocate that address again while the branch still holds it. See Releasing an allocated resource.

The allocation fails with one of these errors when the branch does not have what the pool needs:

• Pool '<pool>' cannot allocate on branch '<branch>': its namespace '<namespace>' does not exist on this branch.
  • The pool's IP namespace does not exist on the branch, for example because it was created on another branch that is not merged yet, or deleted on this branch.
  • When the pool no longer links to a namespace, for example because the branch that held the namespace was deleted, the message does not include the name of the namespace: Pool '<pool>' cannot allocate on branch '<branch>': its namespace does not exist on this branch.
  • Allocate on a branch where the namespace exists. If the namespace was created on another branch, merge that branch and rebase this one first.
• Pool '<pool>' cannot allocate on branch '<branch>': none of its resources exist on this branch.
  • None of the pool's source prefixes exist on the branch.
  • Allocate on a branch where at least one source prefix exists, or add a source prefix that exists on this branch to the pool.

When the source prefixes exist on the branch but none has a free address left, the allocation fails with There are no more addresses available in this pool.

Next

• Allocate IP prefixes
• Allocate numbers
• Weighted allocation to control which source prefixes are preferred