Skip to main content
Equinix Deploy

Facilities

A Facility is a single, physical data center location within a Metro. Most Equinix Metal™ user experiences and features are focused around Metros, however sometimes it may be useful to dig down and know a little bit about your servers at the Facility level.

Which Facility is my Server in?

To find which facility your server is in, use the Equinix Metal CLI or API.

Use the metal device command, and specify that you want a JSON response using the output flag -o.

metal device get -i <device_id> -o json

Send a GET request to the devices/{id} endpoint. 

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

Both the CLI and API returns a response that includes a "facility" object. Sample Response:

{
"id": "0dd71771-143e-4964-87d2-7e6e0348253f",
...
"facility": {
    "id": "2b70eb8f-fa18-47c0-aba7-222a842362fd",
    "name": "Sunnyvale, CA",
    "code": "sjc1",
    "features": [
    "baremetal",
    "storage",
    "layer_2",
    "global_ipv4",
    "backend_transfer"
    ],
    "address": {
    "href": "#9dba11a6-0a26-4993-901b-df253713b89e"
    },
    "metro": {
    "id": "2991b022-b8c4-497e-8db7-5a407c3a209b",
    "name": "Silicon Valley",
    "code": "sv"
    },
    "ip_ranges": [
    "2604:1380:1000::/36",
    "147.75.200.0/22",
    "147.75.108.0/22",
    "147.75.68.0/22",
    "147.75.88.0/22"
    ]
},
...
}

Finding General Facility Information

You can retrieve a list of facilities using the metal facilities get command.

metal facilities get

Sending a GET request to the /facilities endpoint will return a list of data centers where your user account is able to provision with lots of information about each, including name, code, ID. The features listed are available to servers in those data centers.

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

Sending a GET request to the /projects/{id}/facilities endpoint, where the id is the Project ID, will return a list of data centers that are available to that project.

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

And sending a GET request to the /organizations/{id}/facilities endpoint, where the id is the Organization ID, will return a list servers that available to your organization.

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

Legacy Facility Sites

Equinix Metal has a number of legacy facilities that are located in metros along side Equinix IBX facilities. For our oldest customers, your infrastructure in a metro can span across both types of facilities.

Not all of these facilities are visible to every organization or user. Please contact us with details about your deployment or application needs if you have questions about these facilities.

Provisioning in a Specific Facility

If your use-case requires that you provision your servers in a specific facility, you can do so using the CLI or API.

When you use the metal device create command, use the --facility or -f parameter to specify the facility instead of a Metro.

metal device create -p $METAL_PROJECT_ID -P <plan> -f <facility> -H <hostname> -O <operating_system>

When you send the provisioning POST request projects/{id}/devices endpoint, use the "facility" field with the facility_code where you want the server to live instead of specifying a Metro.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
    "facility": "<facility_code>",
    "plan": "<server_type>",
    "operating_system": "<os_code>"
}'

Being able to provision in a specific facility through the API also allows automations that uses our integrations, like the Terraform provider, also support provisioning in specific facilities.

Using Facilities in Place of Metros

Similar to provisioning on-demand servers, other deployment options and platform features can use facilities in place of metros in the CLI or API.

Be aware, the use of the "facilities" parameter is mutually exclusive to the "metros" parameter; it is not possible to use both.

Facility Capacity

Data center logistics and variations in demand can sometimes result in inventory fluctuations. When you deploy from the console, in a Metro, your options are automatically filtered and you can take advantage of the capacity across the whole Metro. If you are deploying servers through the API to a specific facility, that filtering is not available, and if there isn't enough capacity to provision your order, the request will fail.

To see the capacity a facility, use the metal capacity command.

metal capacity get <facility>

Capacity responses are one of the following:

  • Normal - There are plenty of servers available.
  • Limited - There are servers available, but the stock is limited.
  • Unavailable - Servers of a particular type and data center combination are not available.

You can also check to see if your provisioning request can be fulfilled in a facility.

metal capacity check -f <facility> -P <plan> -q <quantity>

The response will indicate true if the servers are available, and false if there is no available capacity to fill your request.

To check the capacity of facilities, use the /capacity endpoint. Send a GET request to see a complete list of data centers, servers, and their capacity levels.

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

Capacity responses are one of the following:

  • Normal - There are plenty of servers available.
  • Limited - There are servers available, but the stock is limited.
  • Unavailable - Servers of a particular type and data center combination are not available.

Instead of checking capacity for everything at once, you can also check to see if a request for a specific facility and server will be able to be filled. Send a POST request to the /capacity endpoint with the facility, server type, and number of servers you need 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/capacity" \
-d '{
    "servers": [
        {
            "facility": "<facility_code>",
            "plan": "<server_type>",
            "quantity": <number_of_servers>
        }
    ]
}'

If the request will succeed, the servers object will contain an additional field "available":true in the response. If the request will fail, the servers object will contain an additional field "available":false in the response.

Copied code to clipboard