Batch Deployments¶
The batch deployment feature enables deploying multiple servers at once using the Equinix Metal™ API. This is useful if you don't already use a tool like Terraform, which includes its own method for handling large deployments.
With batch deployments you can choose the server types and locations that suit your particular deployment needs. It is also possible to create several batches at once.
Making a Batch Deployment¶
To make a batch deployment, send a POST
request to the /projects/{id}/devices/batch
endpoint. Send your batch requirements as the JSON object "batches"
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/batch" \
-d '{
"batches": [
{
"metro": "<metro_code>",
"plan": "<server_type>",
"operating_system": "<os_code>",
"quantity": <number_of_servers>
}
]
}'
"plan"
, "operating_system"
, and "quantity"
are all required fields. "metro"
is required unless you are specifying a facility or facilities. All of the other optional fields that are available when you provision servers are also available when you are creating a batch deployment.
The response will include a batch ID, state, and timestamps.
{
"batches":[
{
"id":"34876707-a2e5-4949-8825-5b4dfd541db8",
"error_messages":[],
"quantity":2,
"state":"queued",
"created_at":"2020-10-06T18:29:34Z",
"updated_at":"2020-10-06T18:29:34Z",
"devices":[],
"project":{"href":"/metal/v1/projects/<project_id>"}
}
]
}
Specifying Facilities¶
You may specify a facility by passing a single facility code into your request instead of a metro.
Passing "facility": "any"
in your request will deploy servers to locations based on the most available capacity for the requested server type.
Passing "facility"
an array of facility codes will deploy servers to only those locations based on the most available capacity for the requested server type at those locations.
Facility Diversity¶
In addition to prioritized location selection, it is possible to indicate how many facilities to spread across with the "facility_diversity_level"
parameter. So if you want to provision all your servers in the same location, but the location can be either dc13
or ny5
, you can request:
'{
"batches": [
{
"facility": "['dc13', 'ny5']",
"plan": "<server_type>",
"operating_system": "<os_code>",
"quantity": <number_of_servers>,
"facility_diversity_level": 1
}
]
}'
If you want to spread your servers across a couple of locations, you can request:
'{
"batches": [
{
"facility": ["dc13", "ny5"],
"plan": "<server_type>",
"operating_system": "<os_code>",
"quantity": <number_of_servers>,
"facility_diversity_level": 2
}
]
}'
If "facility_diversity_level"
is not specified, no limit is enforced and device provisioning could be spread across 1 or 2 or all facilities.
Host Naming Schemes¶
Specifying hostnames for your servers is not required, and they will be auto-generated when the servers are deployed. If you would like to name your servers, use "hostname"
or "hostnames
in your request.
To name your servers sequentially, use "hostname"
and create a parseable hostname, "hostname":"s{{index}}.blah.com"
where{{index}}
will be replaced during creation in a logical order (e.g. 1, 2, 3).
'{
"batches": [
{
"facility": "<facility_code>",
"plan": "<server_type>",
"operating_system": "<os_code>",
"quantity": <number_of_servers>,
"hostname": "dev.server{{index}}"
}
]
}'
To name each server with a specific name, use "hostnames"
and pass it an array of hostnames.
'{
"batches": [
{
"facility": "<facility_code>",
"plan": "<server_type>",
"operating_system": "<os_code>",
"quantity": <number_of_servers>,
"hostnames": ["dev.server1","dev.server2","dev.server3"]
}
]
}'
Checking Batch Deployment Status¶
To check on the status of your batch deployments, send a GET
request to the /batches/{id}
endpoint. The batch ID is part of the response when you create a batch deployment.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' "https://api.equinix.com/metal/v1/batches/{id}"
There are four states for batch requests.
State | Description |
---|---|
queued | A batch deployment starts as ‘queued’ while your request is being validated and location capacity is checked. |
in_progress | Once your request has passed validation, it will move to in_progress . |
completed | When the servers are available, and they start provisioning to fill your request, it will move to completed . |
failed | If the servers can't be provisioned, the batch request will be marked as failed and you will be able to see why in ‘error_messages’ field. |
Retrieving all Batches from a Project¶
To list all of your batch deployments in a project, send a GET
request to the /projects/{id}/batches
endpoint.
curl -X GET -H "X-Auth-Token: API-TOKEN" "https://api.equinix.com/metal/v1/projects/{id}/batches"
Note - If you normally use the Equinix Metal console to provision servers, the response will contain more batches than expected. This is because the Equinix Metal console creates a batch of a single instance (quantity 1) for every server deployment. If you create server instances through the /devices
API endpoint, it isn't considered a batch so it will not show in the list returned by this endpoint.