Metal Gateways¶

An Equinix Metal™ Metal Gateway provides a single IPv4 Gateway for a subnet. This allows you to deploy a group of servers in a Metro that are all on the same subnet and that can all connect to each other or the Internet through the Metal Gateway.

You provision a Metal Gateway with a VLAN and IPv4 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

Public and Private Metal Gateways¶

Metal Gateways can be provisioned with either Private IPv4 address blocks or Public 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.

Metal Gateways with public IPv4 address blocks will have a route to the Internet which will allow the servers in the subnet Internet access. 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. Note that if you configure a server to use a public IPv4 address with a Metal Gateway, it will then be reachable from the Internet, even if it was previously deployed without a public IP address.

Limitations¶

• Metal Gateways can not use Global Anycast IP address blocks.
• Metal Gateways do not support IPv6 addresses and subnets.
• Metal Gateways do not support DHCP, NAT, NACLs, nor do they have BGP neighbor support.
• Metal Gateways are not compatible with Fabric Virtual Connections or Dedicated Ports. You will not be able to use a VLAN that is already in use with Fabric Virtual Connections or Dedicated Ports.

IP Address Blocks and Block Sizes¶

Metal Gateways support IP address blocks in the range of /29 to /25 (or 8 IP addresses to 128 IP addresses) for both private IPv4 addresses and public IPv4 addresses.

When you provision a Metal Gateway the Gateway's IP address is auto-provisioned with the IP addresses block's first usable IP address. 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.

Metal Gateways cannot be used with existing ”used” IPv4 address blocks. For private IPv4 address blocks, this means that you will provision a new private IPv4 address block when you provision the Metal Gateway. For public IPv4 address blocks, you will need an unused public IPv4 address block. You can use any existing block that you already have available on the Project as long as no addresses in the block are being used for anything else and it is the correct size. You can also provision a new Elastic public IPv4 address block for the gateway.

Note: there is a default limit on the number of reserved IPv4 addresses for a Project. They are:

• 128 private IPv4 addresses
• 256 public IPv4 addresses

The IP addresses reserved for Metal Gateways are included in these limits. For example, you are limited to one Metal Gateway if it uses a /25 private IPv4 address block. In order to provision additional Metal Gateways using private IPv4 addresses, you would need to tear down and reprovision your Metal Gateways with smaller IP blocks.

Cost¶

• There is no additional charge for Metal Gateways on your account.
• There is no additional charge for Private IPv4 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.

Provisioning 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 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 sever, 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.