Managing Overlapping IP Space in NetBox with VRFs

The Problem: The Duplicate IP Conflict

In a standard IP Address Management (IPAM) system, the database enforces a strict uniqueness constraint: you cannot have the same IP prefix defined twice. This works for a single corporate network, but it fails immediately in multi‑tenant environments, merger‑and‑acquisition scenarios, or when managing customer VPNs. If two different customers both use 192.168.1.0/24, a traditional IPAM will reject the second entry as a duplicate.

The solution is to move away from a single global routing table and implement Virtual Routing and Forwarding (VRF). In NetBox, VRFs allow you to create isolated routing domains, enabling the same IP address or prefix to exist multiple times across the system, provided each instance resides in a different VRF.

How NetBox Handles Routing Isolation

NetBox implements VRFs not just as labels, but as a fundamental scoping mechanism for its IPAM objects. When you assign a Prefix or an IP Address to a VRF, NetBox changes how it validates uniqueness. Instead of checking the entire database for a duplicate, it checks for duplicates within that specific VRF.

There are two primary states for routing in NetBox:

• Global: This is the default. Any object not assigned to a VRF exists in the global routing table. Only one instance of a prefix can exist here.
• VRF‑Specific: Objects assigned to a named VRF (e.g., Customer_A) are isolated. You can have a 10.0.0.0/24 in Customer_A and an identical 10.0.0.0/24 in Customer_B without any validation errors.

Implementation Workflow

To implement overlapping space, you must follow a specific object hierarchy. You cannot assign a prefix to a VRF after it has been created in the Global space if a conflicting prefix already exists in another VRF; the validation will trigger before the move is complete.

1. Define the VRF: Create the VRF object first. This establishes the routing domain.
2. Assign the Prefix: When creating the Prefix, select the VRF from the dropdown. This tells NetBox to scope the uniqueness check to that VRF.
3. Populate IP Addresses: Create IP addresses within that prefix. These will automatically inherit the VRF association from their parent prefix.

Worked Example: Multi‑Tenant Isolation

Imagine you are managing two clients, Client‑Alpha and Client‑Beta, both using the same internal subnet. Here is how you would structure this via the NetBox API or UI:

Step	Action	Object / Value	Expected Result
1	Create VRF	VRF_Alpha	Routing domain created.
2	Create VRF	VRF_Beta	Second routing domain created.
3	Create Prefix	192.168.1.0/24 → VRF_Alpha	Prefix accepted.
4	Create Prefix	192.168.1.0/24 → VRF_Beta	Prefix accepted (no duplicate error).

Trade‑offs and Limitations

While VRFs solve the overlap problem, they introduce management overhead. The most significant limitation is that VRFs are logical boundaries, not physical ones. NetBox does not automatically know how these VRFs are routed across your physical hardware (e.g., via MPLS or VLANs) unless you manually map them to the corresponding device configurations.

Additionally, moving an existing Prefix from the Global VRF to a specific VRF can be high‑friction. If you have already populated that Prefix with hundreds of IP addresses, you must ensure that no other object in the destination VRF conflicts with those addresses before performing the move, or the database transaction will fail.

Verification and Testing

To verify your VRF configuration is working as intended, perform these three checks:

• Overlap Test: Attempt to create the exact same prefix in two different VRFs. If both are saved successfully, isolation is active.
• Collision Test: Attempt to create the same prefix twice within the same VRF. NetBox should return a validation error.
• API Validation: Run a GET request to /api/ipam/prefixes/ and filter by the VRF ID to ensure the objects are correctly scoped.