IP address management
IP address management, also known as IPAM, is a critical part of any infrastructure involving IP network and address allocations. Depending on the scale of networks, it can be challenging to keep track of all IP resources, how they are used, and which ones remain available.
Building an IPAM serves a different purpose as using the IPHost or IPNetwork attribute kinds in other node definitions. In fact, the IPAM feature leverage those attribute kinds.
IPAM generics
To keep things extensible, Infrahub provides generics that users can inherit their nodes from in their own schemas and build their own IPAM:
BuiltinIPNamespace: used to model a namespace to manage IP resources, this is a generic representation of what could be, for examples, a routing table, a routing instance or a VRFBuiltinIPPrefix: used to model a network, sometimes referred as supernet/subnetBuiltinIPAddress: used to model a single IP address
By default, Infrahub comes with a node inheriting from the BuiltinIPNamespace generic. This node is called IpamNamespace. A object of this kind of node, called "default", is also automatically created when starting Infrahub for the first time.
IP Namespaces
IP Namespaces are logical containers that segment and isolate IPAM resources. They allow you to manage separate pools of IP prefixes and addresses within the same Infrahub instance, preventing conflicts and enabling organizational separation of IP resources.
Understanding IP Namespaces
If you are familiar with networking concepts, an IP Namespace is analogous to:
- A VRF (Virtual Routing and Forwarding) instance
- A routing table or routing instance
- A separate IP address space in a multi-tenant environment
Just as a VRF allows a single router to maintain multiple independent routing tables, IP Namespaces allow Infrahub to manage multiple independent sets of IP resources. Each namespace acts as a boundary: IP prefixes and addresses within one namespace are completely separate from those in another.
The default namespace
When Infrahub starts for the first time, it automatically creates a namespace called "default". This namespace serves as the home for all IP resources when no specific namespace is designated.
For many deployments, particularly those managing a single network or organization, the default namespace is sufficient. You can begin creating IP prefixes and addresses immediately without worrying about namespace configuration.
When to use multiple namespaces
Multiple namespaces become valuable when you need to manage IP resources that would otherwise conflict or need logical separation:
- Multi-tenant environments: Service providers managing IP addresses for multiple customers can create a namespace per customer. Each customer might use the same RFC1918 ranges (like 10.0.0.0/8) without conflict.
- Overlapping IP ranges: Organizations with multiple isolated networks that use the same IP ranges can track each network in its own namespace.
- Organizational boundaries: Large enterprises might create namespaces per business unit, region, or data center to maintain clear ownership and separation.
- Network segmentation: Networks with separate routing domains, such as production versus lab environments, can be modeled as distinct namespaces.
How namespaces work
Every IP prefix and IP address in Infrahub belongs to exactly one namespace. When you create an IP resource without specifying a namespace, it is assigned to the default namespace.
Within a namespace:
- IP prefixes form hierarchical trees based on their network containment
- IP addresses are automatically associated with their most specific containing prefix
- Parent-child relationships between prefixes are managed automatically
Namespaces provide isolation: a prefix like 10.0.0.0/24 can exist in multiple namespaces simultaneously without conflict. The same is true for IP addresses.
Deleting a namespace removes all IP prefixes and IP addresses contained within it. This cascade delete behavior ensures referential integrity but means you should exercise caution when removing namespaces.
Practical example
Consider an Internet Service Provider (ISP) that provides managed network services to three customers. Each customer uses the 10.0.0.0/8 private address range internally.
Without namespaces, the ISP could not track these overlapping ranges in a single IPAM system. With namespaces, the ISP creates three namespaces (one per customer) and manages each customer's IP space independently:
- customer-a namespace: Contains Customer A's 10.0.0.0/8 and its subnets
- customer-b namespace: Contains Customer B's 10.0.0.0/8 and its subnets
- customer-c namespace: Contains Customer C's 10.0.0.0/8 and its subnets
Each namespace maintains its own hierarchy, utilization calculations, and address assignments. The ISP can query, report on, and manage each customer's IP space without any overlap or confusion.
Building an IPAM
As mentioned in the previous section, an IPAM namespace is already provided with Infrahub, so there is no need to redefine this unless more attributes are required. The default implementation is very minimal and attributes only include a name and a description.
The below schema defines two nodes: one for IP prefixes IpamIPPrefix and one for IP addresses IpamIPAddress. Both of these nodes inherit from the built-in generics.
# yaml-language-server: $schema=https://schema.infrahub.app/develop/schema.schema.json
---
version: "1.0"
nodes:
- name: "IPPrefix"
namespace: "Ipam"
inherit_from:
- "BuiltinIPPrefix"
description: "IPv4 or IPv6 network"
icon: "mdi:ip-network"
label: "IP Prefix"
menu_placement: "IpamNamespace"
- name: "IPAddress"
namespace: "Ipam"
inherit_from:
- "BuiltinIPAddress"
description: "IPv4 or IPv6 address"
icon: "mdi:ip"
label: "IP Address"
menu_placement: "IpamNamespace"
How IPAM works
IPAM generics and nodes that inherit from them have relationships and a hierarchy. This means that an IP prefix can be related to other prefixes (as parent or as child), an IP address can be related to an IP prefix, and, finally, both of these objects are related to an IP namespace.
To simplify day-to-day usage and prevent from doing many operations via the user interface or the GraphQL API, relationships for IP prefixes and IP addresses are automatically managed. This implies that when an IP prefix is created, relations with a parent prefix, children prefixes and IP addresses that belong to it will be discovered automatically. Same goes when an IP address is created, the more specific prefix it belongs to will be automatically discovered. This will result in trees of IP prefixes and IP addresses being built. Building these hierarchies/trees allows Infrahub to determine how IP prefixes and IP addresses are nested as well as computing utilization of the recorded IP spaces.
Prefix utilization
By default, IP prefixes have a read-only field called utilization. This field value is computed on the fly based on the value of the member_type field. Member type refers to the kind of objects that an IP prefix serves as a container of. It can be either other prefixes or IP addresses.
When the member type value is set to "prefix", the utilization of the IP prefix will be computed using the children prefixes and their sizes. For example, if 192.0.2.0/24 has one subnet, 192.0.2.0/26, it's utilization will report 25%.
When the member type value is set to "address", the utilization of the IP prefix will be computed using the number of IP addresses it contains. For example, subnet 192.0.2.0/26 can have up to 62 IP addresses once network and broadcast addresses excluded. So if this subnet has 20 IP addresses, its utilization will report 32%. Broadcast and network addresses can be taken into account while computing utilization for IPv4 prefixes if the is_pool value is set to true (checkbox checked) or if the prefix' length is 31 as defined in RFC 3021.
GraphQL queries and mutations
Creating a schema inheriting the IPAM generics will generate GraphQL queries and mutations related to the defined schema. For example, the schema defined in a previous section will generate the following queries:
IpamIPPrefixIpamIPAddress
The following mutations will also be available after schema load:
IpamIPPrefixCreateIpamIPPrefixUpdateIpamIPPrefixUpsertIpamIPPrefixDeleteIpamIPAddressCreateIpamIPAddressUpdateIpamIPAddressUpsertIpamIPAddressDelete
As mentioned previously, IP prefixes are organised as a hierarchy. Hierarchical nodes have special relationships called parent, children, ancestors and descendants. These relationships can be used in the queries. However, in the case of IPAM, they cannot be used in mutations due to the fact that Infrahub manage them automatically.
IP prefixes also have default read-only attributes which can be queried and can bring details about a particular networks. These attributes are:
utilization, utilization of an IP prefix in percentnetmask, network mask of an IP prefix like255.255.255.0hostmask, host mask of an IP prefix like0.0.0.255network_address, network address of an IP prefix, usually the first IP address of the prefixbroadcast_address, broadcast address of an IP prefix, usually the last IP address of the prefix