Reserved Hardware¶

Reserved hardware gives you the ability to reserve specific servers for a committed period of time. Unlike hourly on-demand, once you reserve hardware, you will have access to that specific hardware for the duration of the reservation. Reserved hardware is not available on Equinix Metal™ by default. To enable reservations, contact support at support@equinixmetal.com or reach out to your specific account manager.

Reserved hardware is the best way to ensure that all of your capacity and usage needs can be met at any time. On-demand server availability is determined by data center and server capacity at the time that you provision and is not guaranteed.

Provisioning from Hardware Reservations¶

Once you have reserved hardware enable and assigned to your project, when you go to provision a new server, you can select which hardware device and operating systems to provision from your list of previously reserved servers.

In the Equinix Metal™ console, when you click + New Server, your list of reserved hardware is on the Reserved page.

Hardware Reservations in the API¶

The Equinix Metal™ API supports listing your reservations and provisioning from them. To list hardware reservations, send a GET request to the /projects/{id}/hardware-reservations endpoint.

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

The response contains an array of all the reserved hardware for that project. It might be useful to use jq or other tool to filter the response to specific fields depending on your use case.

To see the details of a single reservation, you can send a GET to /hardware-reservations/{id}.

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

To create a device from a specific hardware reservation, send a POST request to the the projects/<id>/devices endpoint, just as if you were provisioning an on-demand server, but specify the hardware_reservation_id, hostname, and operating_system that you want to provision 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/projects/{id}/devices" \
-d '{
  "hardware_reservation_id":"reservation_id",
  "hostname": "your-hostname",
  "operating_system": "ubuntu_20_04_image"
  }'

If you have multiple reservations, you can provision the next available reserved hardware by sending in "next-available" for hardware_reservation_id instead of a reservation ID.

Moving Reservations between Projects¶

Managing hardware reservations between projects within the same organization can be done from the Equinix Metal™ console in Organization Settings on the Reserved Hardware tab. To move a hardware reservation to a different project, click the overflow menu (the three dots) and click Assign to project. Select the project to move the reservation to from the drop-down field.

Moving a Reservation in the API¶

To move to a reservation in the API, you will need the reservation ID and the Project ID that you are moving the reservation to. Then, send a POST to /hardware-reservations/{id}/move with the reservation ID in the path, and the project ID 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/hardware-reservations/{id}/move" \
-d '{
  "project_id": "new-project-id"
  }'