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. Batch Deployments are for deploying servers in the same metro, with the same server plan, and the same operating system. If you are deploying a large amount of servers, we recommend checking the capacity levels in your desired Metro before running a batch deployment.

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": "<plan_code>",
        "operating_system": "<os_slug>",
        "quantity": <number_of_servers>
        }
    ]
}'

Body Parameters:

• "metro" (required) - The Metro code representing the Metro where you are deploying servers.
• "plan" (required) - The plan code that represents the server type you are deploying.
• "operating_system" (required) - The slug representing which operating system to install on to your servers.
• "quantity" (required) - An integer specifying how many servers to deploy in the batch.

All the optional fields that are available when you provision individual servers are also available when you are creating a batch deployment. See the API Reference for a full listing.

Deploying a batch is an asynchronous process, so the response includes the batch ID, state, and timestamps. You can use the batch ID to check the state while the process runs.

{
    "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 Hostnames¶

If you would like to name your servers, use "hostname" or "hostnames in your request.

To name your servers sequentially, use "hostname" parameter in your "batches" object and create a parseable hostname with {{index}}. For example, "dev.server{{index}}" where {{index}} will be replaced with an integer in a logical order (1, 2, 3,...) during server provisioning.

'{
    "batches": [
        {
        "metro": "<metro_code>",
        "plan": "<plan_code>",
        "operating_system": "<os_slug>",
        "quantity": <number_of_servers>,
        "hostname": "dev.server{{index}}"
        }
    ]
}'

Once the batch finishes deploying, the servers are named dev.server1, dev.server2, and dev.server3.

To name each server with a specific name, use "hostnames" parameter in your "batches" object and pass it an array of hostnames.

'{
    "batches": [
        {
        "metro": "<metro_code>",
        "plan": "<server_type>",
        "operating_system": "<os_code>",
        "quantity": <number_of_servers>,
        "hostnames": ["dev.server1","dev.server2","dev.server3"]
        }
    ]
}'

Specifying hostnames for your servers is not required. If you do not supply either "hostname" or "hostnames", the servers will be provisioned with auto-generated names. You can change server hostnames after provisioning.

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.