Metal Gateways¶

An Equinix Metal™ Metal Gateway attaches a gateway IP address to a VLAN and provides routing to a subnet on that VLAN.

This allows you to deploy a group of servers on a VLAN that can talk to each other on that VLAN by way of Layer 2 connectivity. They can reach other hosts in Equinix Metal or the Internet through the Metal Gateway. This can be used for deployments like Enterprise appliances or ESXi installs that need a subnet with Internet access as a cheaper alternative to a dedicated firewall or Network Edge instance.

When attached to a Virtual Router using Virtual Routing and Forwarding (VRF), your Metal network can reach other Cloud Service Providers and other destinations on Equinix Fabric.

You provision a Metal Gateway with a VLAN and IP Address block to provide the subnet. Then, you connect your servers by:

• Converting them to one of the Layer 2 networking modes
• Attaching the servers to the VLAN
• Assigning each server an IP Address from the block

Limitations¶

• Metal Gateways can not use Global Anycast IP address blocks.
• Metal Gateways do not support DHCP, NAT, NACLs.
• In order to use Metal Gateways with Fabric Virtual Connections or Dedicated Ports, you will need to use Virtual Routing and Forwarding (VRF).
• Support for IPv6 addresses and subnets is only available for VRF gateways.
• BGP Neighbor support is only available for VRF gateways.

Metal Gateway IP Address Blocks¶

Metal Gateways can be created with:

• Public IPv4 address blocks from your Public IPv4 address reservations.
• VRF IP address blocks from a VRF's IP Address reservations.
• Private IPv4 address blocks from Metal's 10.x.x.x private IPv4 address space.

Public IPv4 Address Blocks¶

Metal Gateways support IPv4 address blocks of size /29 to /25 (or 8 IP addresses to 128 IP addresses) for public IPv4 addresses. You can use any existing block that you already have available in your Project as long as no addresses in the block are being used for anything else and it is the correct size. If you do not already have a usable public IPv4 address block, you can create one when creating your Metal Gateway.

The Metal Gateway is assigned the first usable IP address from your address block. For example, if you provision a Metal Gateway with the address block 128.66.1.0/28 the gateway's address will be 128.66.1.1 and you can assign the remaining IP addresses in the block to your servers. It is not possible to change the default gateway IP address for the block.

Metal Gateways with public IP address blocks will have a route to the Internet. Servers assigned an address from address block and on the Metal Gateway's VLAN will have Internet access, even if it was previously deployed without a public IP address.

VRF Address Blocks¶

When creating a Metal Gateway as part of your VRF, use the IP address reservations from your VRF's specified IP blocks.

A VRF's IPv4 address reservations have a maximum size subnet of /22 and a minimum size subnet of /29. You can create multiple Metal Gateways for each of your VRF's IPv4 address reservations in the same VRF.

VRF's only support subnets of size /64. There is a limit of one /64 IPv6 IP Reservation per VRF.

Private IPv4 address blocks¶

Metal Gateways with private IPv4 address blocks can be used for deployments that require a private subnet, like for deploying a database or backend application. Metal Gateways with private IPv4 address blocks deployed will NOT have a route to the Internet, but WILL have a route to other servers within Equinix Metal. They cannot reach Internet hosts or be reached by Internet hosts, but they can reach other hosts within your project and be reached by them.

Metal Gateways support IPv4 address blocks of size /29 to /25 (or 8 IP addresses to 128 IP addresses) for private IPv4 addresses.

The Metal Gateway is assigned the first usable IP address from your address block. For example, if you provision a Metal Gateway with the address block 10.1.1.0/28 the gateway's address will be 10.1.1.1 and you can assign the remaining IP addresses in the block to your servers. It is not possible to change the default gateway IP address for the block.

Cost¶

• There is no additional charge for Metal Gateways on your account.
• There is no additional charge for Private IPv4 address blocks or VRF IP address blocks.
• Public IPv4 address blocks used with a Gateway are billed at the existing rate.
• Egress bandwidth usage on public IPv4 blocks is billed at the existing rate.

Creating a Metal Gateway¶

metal gateway create --project-id <project_uuid> --virtual-network <vlan_uuid> --ip-reservation-id <reservation_uuid>

metal gateway create --project-id <project_uuid> --virtual-network <vlan_uuid> --private-subnet-size <int>

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 '{
    "virtual_network_id": <"string">,
    "ip_reservation_id": <"string">,
    "private_ipv4_subnet_size": <integer> 
}'

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": <string>,
    "virtual_network_id": <string> 
}'

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/projects/{id}/metal-gateways

Gateway Details¶

metal gateway get --project-id <project_uuid>

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/metal-gateways/{id}

Example Metal Gateway Configuration¶

This example uses a Metal Gateway configured with a public IPv4 subnet that provides Internet access to a server that is set up in Layer 2 Bonded Mode. The server will only have Internet access that provided by the gateway. The example Metal Gateway uses subnet 203.0.113.0/29, and the gateway's IP address is 203.0.113.1.

Whether you provision your server with no public IP addresses or convert an existing server, this set up will work in either case. Make sure that you have the root password and SSH keys for your server; they are both required for using the SOS/OOB Console.

1. Convert the server to Layer 2 Bonded Mode. All Internet access and Equinix Metal assigned IP addresses are removed from the server.

   

2. Add the server to the Metal Gateway's VLAN.

   

3. Use the SOS/OOB Console to SSH into the server and update the networking configuration in the operating system. This example uses Ubuntu 20.04.

   ssh -o PubkeyAcceptedAlgorithms=+ssh-rsa -o HostKeyAlgorithms=+ssh-rsa <device_id>@sos.da11.platformequinix.com
   

4. Configure the prerequisites for VLANs.

   modprobe 8021q
   echo "8021q" >> /etc/modules
   

5. Assign an IP address from the range of useable IP addresses that belong to the Metal Gateway. For this example, only one VLAN is attached to this server, and untagged packets are not supported, so configure the IP address by updating bond0. (If you are attaching more than one VLAN to this server you will need to use tagged traffic and subinterfaces and/or set a Native VLAN.)

   ip addr add 203.0.113.2/29 dev bond0
   ip link set dev bond0 up
   

   You can check that it came up with

   ip -d link show bond0
   

6. Move the default route. Since the server is in a Layer 2 mode, the old default route is no longer in use, so you can remove it and update it to the Metal Gateway's IP address.

   ip route delete default via <old_ip_gateway>
   ip route add default via 203.0.113.1 dev bond0
   

7. Check the interface configuration and default route with

   ip route
   >
   default via 203.0.113.1 dev bond0
   10.67.50.2/31 dev bond0 proto kernel scope link src 10.67.50.3
   203.0.113.2/29 dev bond0 proto kernel scope link src 203.0.113.2
   

8. The result should be that you are able to ping the server at the IP address in the subnet that belongs to your Metal Gateway.

   ping 203.0.113.2
   >
   PING 203.0.113.2 (203.0.113.2): 56 data bytes
   64 bytes from 203.0.113.2: icmp_seq=0 ttl=46 time=49.347 ms
   64 bytes from 203.0.113.2: icmp_seq=1 ttl=46 time=49.664 ms
   64 bytes from 203.0.113.2: icmp_seq=2 ttl=46 time=43.281 ms
   64 bytes from 203.0.113.2: icmp_seq=3 ttl=46 time=54.083 ms
   64 bytes from 203.0.113.2: icmp_seq=4 ttl=46 time=43.737 ms
   ^C
   --- 203.0.113.2 ping statistics ---
   5 packets transmitted, 5 packets received, 0.0% packet loss
   round-trip min/avg/max/stddev = 43.281/48.022/54.083/4.050 ms
   

Adding an IP Address to a Metal Gateway¶

Notice: This feature is a test feature currently under active development, and is only available to certain users.

You can assign one of your reserved public IPv4 addresses to a destination IP address in a Metal Gateway.

When assigning the reserved IP address (or address range) to the Metal Gateway, you also specify the "next-hop" or destination IP address. The next-hop address must be contained within the subnet assigned to the Metal Gateway, and it can not be the network, gateway, or broadcast address (can't be the first or last addresses in the subnet).

Note - There is no verification that the selected next-hop address is actually being used by any of your servers.

Then, to assign a reserved IP address to a Metal Gateway, send a POST request to the /metal-gateways/{id}/ips endpoint.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/metal-gateways/{id}/ips" \
-d '{
    "address": "a.b.c.d/e",
    "next_hop": "w.x.y.z",
    "tags": ["list", "of", "tags"],
    "customdata": { "customdata": "object" }
}'

Body Parameters:

• "address" (required) - An IP address (or IP Address range) contained within one of the Project's reserved IP address blocks.
• "next_hop" (required) - An IP address contained within the Metal Gateways' IP address block.
• "customdata" - An optional user-defined JSON object value. More on custom data fields can be found on the Custom Data documentation page.
• "tags" - Optional list of user-defined tags. Can be used by users to provide additional details or context.

To list the Metal Gateway's reserved IP address assignments, send a GET request to the /metal-gateways/{id}/ips endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/metal-gateways/{id}/ips

To show an individual IP address assignment, send a GET request to the /ips/{id} endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/ips/{id}

To remove a reserved IP address from a Metal Gateway, send a DELETE request to the /ips/{id} endpoint, specifying the ID of the assignment in the request.

curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/ips/{id}

This will not remove the IP Address from your Project. The address or subnet will be free to use elsewhere.

Deleting a Metal Gateway¶

metal gateway delete --id <gateway_uuid>

curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/metal-gateways/{id}

When you delete a Metal Gateway, data for the gateway and the subnets are removed. If the block is a public IPv4 address block, then the block is just returned to the Project and you can reuse it for something else. If the IP address block is a private IPv4 address block, the block of IP Addresses is deleted. The VLAN associated with the Gateway will continue to exist and can also be used for something else.

Note: it is possible to delete an "Active" Gateway. Please ensure that the Gateway is not currently handling traffic before deleting it to avoid disruption.