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 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.
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.
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.
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>
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¶
Once provisioned, the details of your Metal Gateway are listed in the table on the Metal Gateway page of your Project.
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>
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. |
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.
-
Convert the server to Layer 2 Bonded Mode. All Internet access and Equinix Metal assigned IP addresses are removed from the server.
-
Add the server to the Metal Gateway's VLAN.
-
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
-
Configure the prerequisites for VLANs.
modprobe 8021q echo "8021q" >> /etc/modules
-
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
-
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
-
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
-
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¶
Select the Metal Gateway you want to delete from the list on the Metal Gateways page. Click Delete.
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>
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.