Skip to main content

Custom Data

Equinix Metal™ offers a custom data service, so you can define and consume data about your servers and infrastructure through the server's metadata and the Equinix Metal API.

One way to think of custom data is as a far more expressive tag feature. Custom data allows JSON-formatted strings, arrays, maps, maps of arrays of numbers, booleans, et cetera. The fields and object properties are completely user-defined and intended to offer additional options for automation. The JSON objects used on this page are just simple examples.

Provisioning with Custom Data

To add Custom Data to your server at provisioning, expand the Optional Settings section. Select Custom Data. Enter your JSON-formatted data into the field.

Custom Data Field in the Optional Settings in the Console

Accessing Custom Data

Once your server is provisioned, you can access its Custom Data from the server's Settings tab.

Location of a Server's Settings Tab

Scroll to the Custom Data section.

Custom Data Field in a Server's Settings

Custom data is accessible for as long as the server is provisioned in your project.

Adding or Modifying Custom Data

To update your server's custom data, open the server's Settings tab.

Location of a Server's Settings Tab

Scroll to the Custom Data section and enter your new JSON-formatted data into the field and click Save.

Modifying the Custom Data in the Console

Custom Data for other Resources

In addition to servers, other Equinix Metal resources support custom data through the API. While not available in metadata, these endpoints can be taken advantage of for remote state storage particular to the resource offering the "customdata" property.

Users

You can add custom data to any already created user with the /users/{id} endpoint.

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/users/{id}" \
-d '{
"customdata": {
"data": {
"text": "bot-user-1",
"auto-rotate": true
}
}
}'

And then you can access it from the /users/{id}/customdata endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/users/{id}/customdata

Projects

You can create a Project with custom data by including it in the body of your POST to the /projects endpoint.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/" \
-d '{
"customdata": {
"data": {
"text": "dev-env-05",
"do-not-disturb": false
}
},
"name": "string",
"organization_id": "<uuid>",
"payment_method_id": "<uuid>"
}'

You can update a Project's custom data using the "customdata" field in the body of a PUT request to the /projects/{id} endpoint.

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}" \
-d '{
"customdata": {
"data": {
"text": "dev-env-05",
"do-not-disturb": true
}
}
}'

And finally, you can retrieve a Project's custom data from the /projects/{id}/customdata endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/projects/{id}/customdata

Organizations

You can add custom data to any Organization using the "customdata" field in the body of a PUT request to the /organizations/{id} endpoint.

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/organizations/{id}" \
-d '{
"customdata": {
"data": {
"text": "cluster-03",
"do-not-disturb": true
},
"owners": "internal"
}
}'

You can retrieve an Organizations's custom data from the /organizations/{id}/customdata endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/organizations/{id}/customdata

IP Addresses

You can add custom data to an IP Address when it is assigned to a server by including the "customdata" field in the body of your POST request to the /devices/{id}/ips endpoint.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/devices/{id}/ips" \
-d '{
"address": "198.51.100.3/31",
"customdata": {
"data": {
"text": "connect-me",
"can_float": false
},
"group": "for_vms"
}
}'

You can update an IP Address's custom data using the "customdata" field in the body of a PATCH request to the /ips/{id} endpoint.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/ips/{id}" \
-d '{
"address": "198.51.100.3/31",
"customdata": {
"data": {
"text": "connect-me",
"can_float": true
},
"group": "static"
}
}'

You can retrieve an IP Address's custom data from the /ips/{id}/customdata endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/ips/{id}/customdata