Skip to content

Batch Deployments

The batch deployment feature enables deploying multiple servers at once using the Equinx 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": [
        {
        "facility": "<facility_code>",
        "plan": "<server_type>",
        "operating_system": "<os_code>",
        "quantity": <number_of_servers>
        }
    ]
}'

"facility", "plan", "operating_system", and "quantity" are all required fields. 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 Locations

Passing a single facility code into your request will deploy servers in that location.

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.

Location 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.