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 will only work with VLANs and servers located in Equinix IBX sites. Metal Gateways are not supported in in Equinix Metal legacy facilities.
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 Shared or Dedicated Ports. You will not be able to use a VLAN that is already in use with Shared 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 Elastic 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.

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¶

Console

Metal Gateways are scoped at the Project level, so to provision one, open the Project's Metal Gateway page. Click + Add Metal Gateway.

From the Create Metal Gateway panel, select the VLAN you want to attach to the gateway from the drop-down. Make sure that the VLAN is in the same Metro as the IP address blocks and servers you want to use with the gateway. If you do not have an eligible VLAN, click +Create New VLAN, which takes you through the process to create one.

Then, select which type of IPv4 addresses you want to use with the gateway. If using a Public IPv4 address block, either select from the eligible IP address blocks in the Metro where the servers are or click +Create New IP Block to create one. Again, make sure that the IP address block is in the same Metro as the VLAN and the servers you want to use with the gateway.

Creating a Public IPv4 Gateway

If you want to use a Private IPv4 address block, you will have to create a new one. Select the size of the block from the drop-down and it will automatically be created in the same Metro as the VLAN you choose for the gateway.

Creating a Private IPv4 Gateway

Click Create Metal Gateway to start the provisioning.

Once you have a Metal Gateway provisioned in a Project, it is listed on the Metal Gateways page.

CLI

Create a Metal Gateway with the metal-gateway create command. Specify the VLAN the gateway will be created on to the --virtual-network flag.

If you are using using a Public IPv4 address block, specify the block with the --ip-reservation-id flag.

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

If you are creating and using a Private IPv4 address block, the specify the size of the block (number of IP addresses) with the --private-subnet-size flag.

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

API

To create a Metal Gateway in the API, 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 '{
    "virtual_network_id": "string",
    "ip_reservation_id": "string",
    "private_ipv4_subnet_size": integer 
}'

Request Fields:

virtual_network_id - The UUID of the VLAN to use for this Metal Gateway. This field is required.
ip_reservation_id - The UUID of a public IPv4 reservation to use for this Metal Gateway. Required if using the Metal Gateway with a public IPv4 address block. The specified IP reservation must belong to the same Metro as the VLAN.
private_ipv4_subnet_size - The size of the private IPv4 subnet to create for this Metal Gateway, and must be an integer that is a power of 2 between 8 and 128, representing how many IP addresses are in the block. Required if using the Metal Gateway with a private IPv4 address block.

NOTE: The ip_reservation and private_ipv4_subnet_size fields are mutually exclusive -- only one can be specified in the request.

Once you have a Metal Gateway provisioned in a Project, you can retrieve a list of gateways by sending a GET request to the /projects/{project id}/metal-gateways endpoint.

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

Gateway Details¶

Console

Once provisioned, the details of your Metal Gateway are listed in the table on the Metal Gateway page of your Project.

Table of Gateway Details

CLI

To get a list and details of the Metal Gateways in a project, use the metal gateway get command.

metal gateway get --project-id <project_uuid>

API

To get the details and state of a specific gateway, send a GET request to the /metal-gateways/{id} endpoint.

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

Field	Description
State	The current state of the Gateway. The possible states are: Ready - The Gateway was successfully provisioned with the IP Address block and VLAN. Active - The VLAN has servers attached to it and the Gateway is in use.
Location	The Metro where the Metal Gateway is located. It will also be the Metro where the VLAN and the servers are located.
VXLAN	VLAN ID of the VLAN attached to the gateway.
Gateway	The IP Address of the gateway.
IP Block	The block of usable IP Addresses available through the gateway.
Created	Date when the Metal Gateway was created.

Adding Servers to the Gateway VLAN¶

Equinix Metal offers a few methods of supporting Layer 2 networking on its platform. To add servers to the gateway, you would choose which Layer 2 mode meets your use-case, enable that mode on your server, and attach the server to the same VLAN you attached to the gateway.

Using Hybrid Bonded Mode for example, you convert the server to Hybrid Bonded mode and assign the VLAN to the bond0 port.

Console

In the Equinix Metal console, navigate to the server's Network page, click Convert To Other Network Type, select Hybrid, and choose Bonded.

Then, select Gateway's VLAN from the drop-down, which will assign it to the bond0 port. Click Assign New VLAN and Convert to Hybrid Networking to start the changes.

Converting to Hybrid Bonded mode options panel

CLI

In the CLI, convert to Hybrid Bonded mode and assign a VLAN to the bonded interface, bond0, with the metal port vlan command.

metal ports vlan --port-id <bond0_id> --assign <VLAN_id>

Specify the UUID of bond0 for the --port-id and the VLAN that you are assigning to --assign.

API

In the API, you assign the Gateway's VLAN to a port by sending a POST to the /ports/{id}/assign endpoint.

You have to specify the port ID the VLAN is going to be attached to in the path, and it needs to be the UUID for that port as returned by the /devices/{id} endpoint. The ID of the VLAN is sent in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \ 
-H "X-Auth-Token: <API_TOKEN> " \
"https://api.equinix.com/metal/v1/ports/{id}/assign" \
-d '{
    "vnid": "<VLAN_ID>"
    }'

More information on the Layer 2 modes that Equinix Metal supports and how to configure them on your servers are available on the Hybrid Bonded Mode, Hybrid Unbonded Mode, and Pure Layer 2 Modes pages.

Configuring the Server's Networking¶

Similarly, how you configure the network on the server will vary by which Layer 2 mode and operating system you are using. In general, you will want to enable VLAN support and add the VLAN to the interface, either bond0 for the bonded modes, or eth0 or eth1 for the unbonded modes. When adding the VLAN to the interface, you assign the server an IP Address from the Gateway's IP Address block.

Adding the VLAN to the Network Interface¶

This example assumes the server is in Hybrid Bonded mode and steps through adding the VLAN to bond0.

Enable VLAN support.

modprobe 8021q
lsmod | grep 8021q
echo "8021q" >> /etc/modules-load.d/networking.conf

Add the VLAN to bond0. VLAN_ID should match the VLAN ID found on the console.
```
ip link add link bond0 name bond0.<VLAN_ID> type vlan id <VLAN_ID>
```
Add the IP address to the VLAN.
```
ip addr add <IP_ADDRESS> dev bond0.<VLAN_ID>
ip link set dev bond0.<VLAN_ID> up
```
To make the changes permanent, configure /etc/network/interfaces with the IP address to the desired IP from your chosen block. For example,
```
auto bond0.<VLAN_ID>
iface bond0.<VLAN_ID> inet static
pre-up sleep 5
address <IP_ADDRESS>
netmask 255.255.255.0
vlan-raw-device bond0
```
Note: The line pre-up sleep 5 helps to prevent conflicts on bond0 when the server boots.
Ensure the IP address is configured.
```
ip -d link show bond0.<VLAN_ID>
```

You need to run through the same steps on all the servers that you want to attach to the VLAN, assigning a different IP address from the block to each.

Examples for configuring the networking for servers in the Layer 2 modes on Equinix Metal are available in the Hybrid Bonded Mode, Hybrid Unbonded Mode, and Pure Layer 2 Modes pages.

Moving the Default Routes (Optional)¶

When you provision a server on Equinix Metal, it is assigned a public IPv4 address and a private IPv4 address. If you want to use the Metal Gateway IP Addresses as the default route, then you move your default routes.

Remove the default routes.

For the public IPv4 address:

ip route delete default via <IP_ADDRESS>

For the private IPv4 address:

ip route delete 10.0.0.0/8 via <IP_ADDRESS>

Reassign the new IP addresses as default routes.

For a public IPv4 address:

ip route add default via <IP_ADDRESS> dev bond0.<VLAN_ID>

For a private IPv4 address:

ip route add 10.0.0.0/8 via <IP_ADDRESS> dev bond0.<VLAN_ID>

Deleting a Metal Gateway¶

Console

Select the Metal Gateway you want to delete from the list on the Metal Gateways page. Click Delete.

Gateway Delete Button

CLI

To delete a Metal Gateway, use the metal gateway delete command. Specify which gateway to delete by supplying its UUID to the --id flag

metal gateway delete --id <gateway_uuid>

API

To delete a gateway, send a DELETE request to the /metal-gateways/{id} endpoint.

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.