Managing Route Domains

Route Domains provide a way to define and manage Layer 3 routing isolation boundaries across your network fabric. They group together the VRF, L3 VLAN and L3 VNI resources needed for inter-subnet routing and control how these resources are allocated to infrastructures.

What is a Route Domain?

A Route Domain is a logical construct that encapsulates:

• VRF allocation — how VRF instances are assigned to infrastructures within the domain
• L3 VLAN allocation — how Layer 3 VLANs (used for inter-VLAN routing interfaces such as SVIs) are assigned
• L3 VNI allocation — how Layer 3 VNIs (used in VXLAN-based overlays for symmetric IRB) are assigned

By grouping these resources together, Route Domains ensure consistent L3 isolation across all logical networks and infrastructures that reference them.

Route Domain kinds

When creating a Route Domain you must select its kind, which determines the routing architecture:

Kind	Description
VRF Lite	Traditional VRF-based routing without an overlay protocol. Suitable for single-site deployments where L3 isolation is needed between tenants without MPLS or EVPN.
MPLS L3VPN	Uses MPLS Label Switched Paths to carry L3VPN traffic between sites. Suitable for service provider and enterprise WAN environments with existing MPLS infrastructure.
EVPN L3VPN	Uses EVPN type-5 routes with a VXLAN data plane for L3 inter-subnet routing. This is the most common choice for modern VXLAN-EVPN data center fabrics using symmetric IRB gateways.

The kind cannot be changed after creation.

Creating a Route Domain

Using the Admin UI

1. Navigate to Fabrics and select the fabric where you want to create the Route Domain
2. Go to the Route Domains tab
3. Click Add Route Domain
4. Fill in the required fields:
   • Name — a human-readable name for the Route Domain
   • Label — a unique identifier (max 63 characters)
   • Kind — select one of VRF Lite, MPLS L3VPN or EVPN L3VPN
5. Configure at least one VRF allocation strategy (see below)
6. Optionally configure L3 VLAN and L3 VNI allocation strategies
7. Click Create

Using the API

curl -X POST "https://<your-server>/api/v2/route-domains" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my-route-domain",
    "name": "Production Route Domain",
    "kind": "evpn_l3vpn",
    "vrfAllocationStrategies": [
      {
        "kind": "manual",
        "name": "vrf-prod-01",
        "scope": {
          "kind": "fabric",
          "resourceId": 1
        }
      }
    ]
  }'

Using the CLI

metalcloud route-domain create \
  --label my-route-domain \
  --name "Production Route Domain" \
  --kind evpn_l3vpn

Allocation strategies

Route Domains use allocation strategies to control how VRFs, L3 VLANs and L3 VNIs are distributed. Each strategy type can be either manual (you specify the value) or automatic (the system allocates from configured ranges).

VRF allocation strategies

VRF allocation strategies determine how VRF instances are assigned within the Route Domain. Currently only manual allocation is supported for VRFs, meaning you must specify the VRF name explicitly.

Each VRF allocation strategy has:

• kind — manual
• name — the VRF name to assign
• scope — where the VRF applies (see Scopes below)

Adding a VRF allocation strategy

Via the API:

curl -X POST "https://<your-server>/api/v2/route-domains/{id}/config/vrf-allocation-strategies" \
  -H "Content-Type: application/json" \
  -H "If-Match: <revision>" \
  -d '{
    "kind": "manual",
    "name": "vrf-tenant-a",
    "scope": {
      "kind": "fabric",
      "resourceId": 1
    }
  }'

L3 VLAN allocation strategies

L3 VLAN allocation strategies control how VLANs are assigned for Layer 3 routing interfaces (such as SVIs for symmetric IRB gateways). Both manual and automatic allocation are supported.

• Manual — you provide a specific vlanId
• Automatic — the system allocates from the VRF VLAN ranges configured on the fabric

Each L3 VLAN strategy also has an optional granularity level that controls at which level the VLAN is unique:

• fabric — the VLAN ID is unique across the entire fabric
• network_device — the VLAN ID is unique per network device

Adding an L3 VLAN allocation strategy

Via the API:

# Automatic allocation
curl -X POST "https://<your-server>/api/v2/route-domains/{id}/config/l3-vlan-allocation-strategies" \
  -H "Content-Type: application/json" \
  -H "If-Match: <revision>" \
  -d '{
    "kind": "auto",
    "scope": {
      "kind": "fabric",
      "resourceId": 1
    }
  }'

# Manual allocation
curl -X POST "https://<your-server>/api/v2/route-domains/{id}/config/l3-vlan-allocation-strategies" \
  -H "Content-Type: application/json" \
  -H "If-Match: <revision>" \
  -d '{
    "kind": "manual",
    "vlanId": 100,
    "scope": {
      "kind": "fabric",
      "resourceId": 1
    }
  }'

L3 VNI allocation strategies

L3 VNI allocation strategies control how VNIs are assigned for VXLAN-based L3 routing. This is primarily relevant for EVPN L3VPN Route Domains where symmetric IRB requires a dedicated L3 VNI per VRF.

Both manual and automatic allocation are supported:

• Manual — you provide a specific vni value
• Automatic — the system allocates from the L3 VNI prefix configured on the fabric

Each L3 VNI strategy also has an optional granularity level (fabric) that controls the uniqueness scope.

Adding an L3 VNI allocation strategy

Via the API:

# Automatic allocation
curl -X POST "https://<your-server>/api/v2/route-domains/{id}/config/l3-vni-allocation-strategies" \
  -H "Content-Type: application/json" \
  -H "If-Match: <revision>" \
  -d '{
    "kind": "auto",
    "scope": {
      "kind": "fabric",
      "resourceId": 1
    }
  }'

Scopes

Every allocation strategy is tied to a scope that determines where the allocated resource applies. Available scope kinds are:

Scope	Description
global	Applies across all fabrics and sites
site_group	Applies to a group of sites
site	Applies to a single site
fabric_group	Applies to a group of fabrics
fabric	Applies to a single fabric
rack	Applies to a single rack
device_group	Applies to a group of network devices
network_device	Applies to a single network device

When creating a scope, provide the kind and the resourceId of the target resource.

Route Domain configuration

Each Route Domain has a config object that tracks the deployment state and the desired allocation strategies. The config includes:

• deployType — the current deployment intent (create, edit, delete, start, stop, suspend)
• deployStatus — the current deployment progress (not_started, ongoing, finished)
• kind — mirrors the Route Domain kind

Viewing Route Domain config

curl "https://<your-server>/api/v2/route-domains/{id}/config"

Service status lifecycle

Route Domains follow the standard MetalSoft service status lifecycle:

ordered → active → suspended / stopped / deleted

Updating a Route Domain

You can update the name, label and annotations of an existing Route Domain. The kind cannot be changed after creation.

Using the API

curl -X PATCH "https://<your-server>/api/v2/route-domains/{id}" \
  -H "Content-Type: application/json" \
  -H "If-Match: <revision>" \
  -d '{
    "name": "Updated Route Domain Name",
    "label": "updated-label"
  }'

The If-Match header must contain the current revision of the Route Domain to prevent concurrent modification conflicts.

Deleting a Route Domain

Before deleting a Route Domain, ensure that no logical networks or infrastructures are still referencing it.

Using the API

curl -X DELETE "https://<your-server>/api/v2/route-domains/{id}" \
  -H "If-Match: <revision>"

Listing and filtering Route Domains

The list endpoint supports pagination, filtering and sorting.

Using the API

# List all Route Domains
curl "https://<your-server>/api/v2/route-domains"

# Filter by kind
curl "https://<your-server>/api/v2/route-domains?filter.kind=\$eq:evpn_l3vpn"

# Filter by fabric
curl "https://<your-server>/api/v2/route-domains?filter.fabricId=\$eq:1"

# Filter by infrastructure
curl "https://<your-server>/api/v2/route-domains?filter.infrastructureId=\$eq:5"

# Sort by ID descending
curl "https://<your-server>/api/v2/route-domains?sortBy=id:DESC"

Relationship to VRFs

Route Domains extend the existing VRF functionality by providing a higher-level abstraction. While VRFs in the IPAM section deal with individual VRF-VLAN mappings, Route Domains manage the complete L3 isolation lifecycle including VRF, VLAN and VNI allocation as a single unit.

If you are migrating from the existing VRF setup, consider creating a Route Domain that matches your current VRF configuration and allocation patterns.

Typical use cases

Single-site EVPN fabric with symmetric IRB

For a data center running VXLAN-EVPN with symmetric IRB gateways, create an evpn_l3vpn Route Domain with:

• A manual VRF allocation strategy per tenant
• An automatic L3 VLAN allocation strategy (allocated from the fabric’s VRF VLAN ranges)
• An automatic L3 VNI allocation strategy (allocated from the fabric’s L3 VNI prefix)

Multi-tenant VRF Lite

For a simpler environment without overlay networking, create a vrf_lite Route Domain with:

• A manual VRF allocation strategy per tenant
• A manual or automatic L3 VLAN allocation strategy