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.
When provisioning your server in the API, define your custom data object in the body of the POST request to the /projects/{id}/devices endpoint.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
"metro": "<metro_code>",
"plan": "<server_type>",
"operating_system": "<os_code>",
"customdata": {
"data": {
"text": "testing device",
"frozen": false,
"oneOf": 3
}
}
}'
Accessing Custom Data¶
Once your server is provisioned, you can access its Custom Data from the server's Settings tab.
Scroll to the Custom Data section.
Once your custom data is defined on your server, you can access it locally on the server from the server's metadata endpoint.
curl https://metadata.platformequinix.com/metadata | jq '.customdata'
You can access the custom data from outside the server from the devices/{id}/customdata API endpoint.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/devices/{id}/customdata
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.
Scroll to the Custom Data section and enter your new JSON-formatted data into the field and click Save.
To update your server's custom data, send a PUT to the /devices/{id} endpoint, defining the custom data object in the body of the request.
curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: $API_TOKEN" \
"https://api.equinix.com/metal/v1/devices/{id}" \
-d '{
"customdata": {
"data": {
"text": "Click Here"
}
}
}'
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 https://api.equinix.com/metal/v1/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