The Spot Market¶

The Equinix Metal™ Spot market allows users to bid on spare server capacity at reduced rates. In exchange, you give Equinix Metal the right to revoke any instance with only a two minute warning. If you have portable workload, the Spot market is an excellent tool to help you reduce your costs.

How Does the Spot Market Work?¶

The spot market is a marketplace with constantly changing inventory. You can place bids on this inventory by defining a variety of factors such as the maximum price you are willing to pay for a particular resource, number and type of servers, whether you want all or some of the order filled at any given time, etc.

For example, you can provision five instances with the maximum price you want to pay per hour per instance. If your price is equal to or greater than the current spot price for the given metro and plan, then the instances will be created for you.

These instances are volatile, which means that they can be revoked by Equinix Metal at any time if another user bids with a higher price. If your instance is going to be revoked, it will receive a termination time that is at least two minutes in length.

Current and Historical Market Pricing¶

The current market price reflects the price you need to specify to deploy a single instance at this point in time. If the listed spot market price is 10x the standard price for a server of that type, then we are out of capacity for spot market instances in that location.

The /market/spot/prices endpoint will provide the current prices for each Equinix Metal metro and plan.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/market/spot/prices

To see price history for a specific location and server, the /market/spot/prices/history?plan&metro endpoint will allow you to check spot market prices for the last 90 days.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/market/spot/prices/history?plan&metro

Bidding Strategies¶

While your specific bidding strategy is entirely up to you, most users adopt one of these bidding strategies based on their use case:

Strictly Optimize Cost - Sacrifice availability for the deepest discount. This is great for long-running workloads that have flexible end dates.

• Use Case: Research-style tasks
• Suggested Bid: near minimum

Cost/Availability Balance - Slightly higher price than strictly cost optimized, but allows you to increase the likelihood of getting and keeping an instance for longer periods of time.

• Use Case: Batch jobs that can handle some amount of reclamation
• Suggested Bid: 10-20% above minimum

Bid On Demand Price - Receive a discount anytime the spot price is lower than on demand, immediately switching to on demand when it goes higher.

• Use Case: Fully cloud native applications capable of easily moving workloads around
• Suggested Bid: on demand price

Optimize Continuity - Bid very high to ensure availability and continuity.

• Use Case: Accept some periods of higher-than-market prices in return for uptime continuity
• Suggested Bid: 2x-3x on demand price

Creating a Spot Market Request¶

To make a spot market request, send a POST request to the /projects/{id}/spot-market-requestsendpoint. In the body of the request, define the details of your request.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/spot-market-requests" \
-d '{
    "devices_max": <integer>,
    "devices_min": <integer>,
    "max_bid_price": <float>,
    "metro": "<metro_slug>",
    "instance_parameters": {
        "hostname": "<string>",
        "plan": "<plan_slug>",
        "operating_system": "<os_slug>"
    }
}'

Body Parameters -

• "devices_max" (required) - The maximum number of devices to provision to fill this request.
• "devices_min" (required) - The minimum number of devices to provision to fill this request.
• "max_bid_price" (required) -
• "end_at" (optional) - Set an expiration for the spot market request with date and UTC time of expiration in ISO8601 format.
• "instance_parameters" (required) - Configuration for the requested devices. The instance parameters object must contain hostname, plan, operating_system, and metro.

instance_parameters can also contain any of the other fields used to provision and configure servers through the API. A complete list of those fields is in the API reference for the /projects/{id}/spot-market-requests endpoint.

Managing Your Spot Market Devices¶

To get a list of all your spot market devices, send a GET request to the /projects/{id}/devices endpoint, filtering on device type.

curl -X GET -H "X-Auth-Token: <API_TOKEN>" \
https://api.equinix.com/metal/v1/projects/{id}/devices?type=spot

Spot-market devices can be updated through the API by sending a PUT request to the /devices/{id} endpoint. Include which fields you would like to update in the body of the request. None of the fields are required, and all can be updated independently.

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/devices/{id}" \
-d '{
    "description": "<string>",
    "hostname": "<string>",
    "always_pxe": <boolean>,
    "ipxe_script_url": "<string>",
    "locked": <boolean>,
    "spot_instance": <boolean>,
    "tags": [
        "<string>"
    ],
    "userdata": "<string>"
}'

A complete list of fields and their descriptions is available in the API Reference.

Converting a Spot Market server to On Demand¶

If you have a spot market server that you need to keep, you can use the API to convert it to an on demand server. Once it is an on demand server, it will not be subject to termination, and it will be billed at the on demand price for the rest of its existence.

Note that servers that have been marked for termination are not eligible for conversion. You must convert your spot market server to on demand BEFORE it is selected for termination.

To convert, send a PUT request to the /devices/{id} endpoint with the body of the request containing the metro where the server lives and "spot_instance": false.

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/devices/{id}" \
-d '{
  "spot_instance": false
}'

Spot Market Termination¶

Termination of spot market servers occurs when your max bid price is below the current spot price max or if demand for servers has increased and your device has the lowest price of all the spot market instances. A server that is marked for termination has 120 seconds before it is removed.

Termination time is available in the API or from the server's metadata.

To determine a server's termination time 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}

The field termination_time contains the UTC time in ISO8601 format when the instance will be terminated. If the response is null, it indicates that no termination time has been set.

You can also grab a list of all devices in a project and their info from the /projects/{id}/devices endpoint.

To query the server itself for termination time, you can cURL its metadata. From the server itself, run:

curl -s https://metadata.platformequinix.com/metadata

The response will contain a termination date/time or it will be null.

Deleting a Spot Market Request¶

To delete a request, send a DELETE to the /spot-market-requests/{id} endpoint.

curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1//spot-market-requests/{id}

If you want to also delete the servers provisioned by the request, send force_termination=true as a query parameter.

curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/spot-market-requests/{id}?force_termination=true