Virtual Routing and Forwarding¶
Equinix Metal™ Virtual Routing and Forwarding (VRF) provides a virtual router for Layer 3 network connectivity between a Metal Gateway Layer 2 private network and remote destinations.
To create and configure Virtual Routing and Forwarding, you need three components:
Limitations¶
Before you create a VRF, consider the following limitations:
- There is a limit of 8 VRFs per Project.
- Only IPv4 addresses are supported. There is no IPv6 address support.
Preparing for Your VRF¶
Before you create a VRF, be aware of the subnets you plan to use and how you are going to use them. This information is important because you will need to specify the IP address range when you create a VRF.
The subnets specified in "ip_ranges"
should include:
- The subnets from which you will create the IP addresses reservations that your Metal Gateway and the servers connected to the Metal Gateway will use. A VRF's IP address ranges must be defined in order to create the VRF IP address reservations, which are then used to create the VRF's Metal Gateways.
- The subnets of size
/31
or/30
which contain the address of the VRF and the address of the remote side of the connection.
Creating a Virtual Router¶
To create a VRF, open the Project's Virtual Routing and Forwarding page found in the Project's Networking section. Click Create Virtual Router.
In the Create Virtual Router pane, enter a name for your router and an optional description. Select the Metro where your servers, VLANs, the Metal Gateway, and this VRF are all located. All of these are required to be in the same Metro.
In the Allowed IP Ranges field, enter a list of CIDR network addresses. The IPv4 address blocks must be between /8
and /29
in size. You can also optionally specify a local ASN.
Click Create Virtual Router.
To create a VRF, send a POST
request to the /projects/{id}/vrfs
endpoint.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/vrfs" \
-d '{
"name": "<string>",
"description": "<string>",
"metro": "<metro_slug>",
"ip_ranges": [
"<cidr_address>"
],
"local_asn": <integer>
}'
Body Parameters:
"name"
(required) - An easy to remember name for your VRF."description"
- An optional description of the VRF."metro"
(required) - The UUID or metro code for the Metro in which to create the VRF."ip_ranges"
(required) - A list of CIDR network addresses. The IPv4 address blocks must be between/8
and/29
in size. Example: ["10.0.0.0/16"
]."local_asn"
- Optional field. You can specify the Local ASN of the VRF as a 32-bit integer.
In the response, be sure to note the VRF's ID -- you will need this for creating your VRF-specific IP address reservations.
Creating a VRF IP Address Reservation¶
Next, create an IP address reservation specifically for your VRF that you will assign to your Metal Gateway. The subnet must be from a block that you specified in the ip_ranges
when you created the VRF.
Click on the VRF you want to reserve IP addresses for. From the Overview tab, click Add IP Reservation.
In the panel, enter the subnet in CIDR notation. The maximum size subnet is /22
and the minimum size subnet is /29
.
The Metro for the IP address reservation is inferred from the associated VRF. Click Submit Request.
As a result, you will get a subnet of reserved IP addresses in the same Metro as your VRF that is ready to be used by your VRF's Metal Gateway.
Send a POST
request the the /projects/{id}/ips
endpoint.
curl -X POST \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/ips" \
-d '{
"cidr": <integer>,
"network": "<ip_address>",
"type": "vrf",
"vrf_id": "<UUID>"
}'
Body Parameters:
"cidr"
(required) - The size of the VRF IP Reservation's subnet, expressed as an integer with a maximum size of 22 and a minimum size of 29."network"
(required) - The starting IP address for this VRF IP Reservation's subnet."type"
(required) - The type of IP address reservation. Must be set to"vrf"
."vrf_id"
(required) - The ID of the VRF in which this VRF IP Reservation is created. The VRF must have an existing IP Range that contains the requested subnet. This field may be aliased as just"vrf"
.
A full listing of body parameter fields and options is available in the API reference.
The Metro for the IP address reservation is inferred from the associated VRF. As a result, you will get a subnet of reserved IP addresses in the same Metro as your VRF that is ready to be used by your VRF's Metal Gateway. The response to your request will contain the IP address reservation's ID. You will need the ID to create your Metal Gateway.
Creating the VRF Metal Gateway¶
Note: If you have not already created one, you will need to create a VLAN in the same Metro as your VRF. This VLAN provides the Layer 2 Network between your VRF's Metal Gateway and your servers.
Create a Metal Gateway in the same Metro as your VRF, selecting the VLAN you'll use to connect the gateway and your servers.
In the IP Block section, select VRF IP. Click the drop-downs to select the VRF and the VRF IP Address Reservation to associate with this Metal Gateway. Click Create Gateway.
As a result, you will get a Metal Gateway in the same Metro as your VRF, which uses the IP addresses in your VRF IP address reservation that you can assign to servers connected to the Metal Gateway's VLAN.
Now that you have your Network IP Address Blocks, create your VRF's Metal Gateways, using the IP address reservation's ID and your Metal Gateway's VLAN's ID. Send a POST
request to the /projects/{project_id}/metal-gateways
endpoint.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/metal-gateways" \
-d '{
"ip_reservation_id": "<UUID>",
"virtual_network_id": "<UUID>"
}'
Body Parameters:
"ip_reservation_id"
(required) - The ID of a VRF IP Reservation that is in the same Project and Metro as the VRF, that will be used by the Metal Gateway."virtual_network_id"
(required) - The ID of a VLAN in the same Project and Metro as the VRF, which will be used by the Metal Gateway
The Metro and VRF for the Metal Gateway is inferred during creation by the specified by the IP reservation and VLAN. As a result, you will get a Metal Gateway in the same Metro as your VRF, which uses the IP addresses in your VRF IP address reservation that you can assign to servers connected to the Metal Gateway's VLAN.
Connecting to Your VRF¶
Once you have your VRF, its subnets, and your Metal Gateway you can:
- Provision a Fabric Virtual Connection to connect it to, so that the Fabric VC is the remote side of the connection.
- Create a new Virtual Circuit on a Dedicated Port to connect it to, so that any destination of your Dedicated Port is the remote side of the connection.
Managing VRF¶
Once provisioned, your VRFs are listed on the Virtual Routing and Forwarding page, under your Project's Networking.
Click on a VRF to view its Overview tab with its name, Metro, ASN, and a list of its IP Ranges.
To list all the VRFs in a Project send a GET
request to the /projects/{id}/vrfs
endpoint.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/projects/{id}/vrfs
To list a VRF's IP reservation blocks, send a GET
request to the /vrfs/{id}/ips
endpoint.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/vrfs/{id}/ips
To get the details of a specific IP reservation block in a VRF, send a GET
request to the vrfs/{vrf_id}/ips/{id}
endpoint.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/vrfs/{vrf_id}/ips/{id}
To update a VRF, send a PUT
request to the /vrfs/{id}
endpoint, using the fields you would like to update in the body of the request. All fields are optional, so they can be updated independently.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/vrfs/{id}" \
-d '{
"name": "<string>",
"description": "<string>",
"ip_ranges": [
"<cidr_address>"
],
"local_asn": <integer>,
"tags": [
"<string>"
]
}'
Adding IP Address Reservations¶
In the IP Address Reservation section of the VRF's Overview, you can add Click Add IP Reservation and fill in the IP Subnet field with the subnets in CIDR notation. The subnets you request must be from the ip_ranges
block that is associated with your VRF. Click Submit Request.
To add IP Address Reservations to your VRF send a a POST
request the the /projects/{id}/ips
endpoint. The subnet you request must be from the ip_ranges
block that is associated with your VRF.
curl -X POST \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/ips" \
-d '{
"cidr": <integer>,
"network": "<ip_address>",
"type": "vrf",
"vrf_id": "<UUID>"
}'
Body Parameters:
"cidr"
(required) - The size of the VRF IP Reservation's subnet, expressed as an integer with a maximum size of 22 and a minimum size of 29."network"
(required) - The starting IP address for this VRF IP Reservation's subnet."type"
(required) - The type of IP address reservation. Must be set to"vrf"
."vrf_id"
(required) - The ID of the VRF in which this VRF IP Reservation is created. The VRF must have an existing IP Range that contains the requested subnet. This field may be aliased as just"vrf"
.
The BGP Table¶
Once traffic is flowing and your virtual router is routing, you can monitor the BGP Neighbors and Learned Routes of your VRF.
Note: You must have all networking configuration set up and enabled before you begin monitoring. All the servers have to be attached to the VLAN of the Metal Gateway, and the Metal Gateway have an "Active" status.
The BGP Table tab shows all of the routes present in the VRF. The BGP Neighbors table shows if there are any peers up and the Learned Routes table displays the routing information.