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.

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.