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¶
When provisioning your server, 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
}
}
}'
Adding or Modifying Custom Data¶
To update your 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"
}
}
}'
Accessing Custom Data¶
Once your custom data is defined on your sever, you can access it locally on the server from the server's metadata endpoint.
curl https://metadata.platformequinix.com/metadata | jq '.customdata'
Or 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.
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