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.