User State¶
Equinix Metal™ provides a User State endpoint for you to send and emit state information during the provisioning process.
The endpoint is accessible from your server during normal provisioning with one of the Equinix Metal provided operating system images after the server hardware has come up and the imaging process is complete. You can then use the User State endpoint in the User Data to send state information about your User Data operations.
When using Custom iPXE to provision user, the endpoint is accessible after the hardware comes up and we start installing the provided image. In this case, User State allows you to send state information during and after the imaging process.
Retrieving the User State Endpoint¶
The User State endpoint depends on the location where the server is provisioned, so you will need to retrieve it from the server's metadata before you can use it. For example, if you SSH into a currently provisioned server and cURL the metadata endpoint:
curl https://metadata.platformequinix.com/metadata | jq -r .user_state_url
returns the User State events url:
http://tinkerbell.sv15.packet.net/events
In practice, to use this during the provisioning process you can write a bash script (example) in your User Data to retrieve and store the User State endpoint as an environment variable.
Creating a Custom User State Event¶
If you want to create a custom user state event, send a POST
request to the user state endpoint.
curl -X POST -d '{"state":"running","code":1000,"message":"running the user data script"}' http://tinkerbell.sv15.console.equinix.com/metal/events
The body of the POST request can accept the following fields:
"state"
-running
,succeeded
, orfailed
."code"
- an integer between1000
and1099
, inclusive."message"
- can be any string message that you want.
For example, you could use this at the end of your user data script to indicate that your user data script has finished running after provisioning your server.
curl -X POST -d '{"state":"succeeded","code":1001,"message":"done running the user data script"}' http://tinkerbell.sv15.console.equinix.com/metal/events
The POST request adds an event to the server's timeline and also displays a message in the timeline section of the console.
Example Script¶
The following is a BASH script that you can use to easily send user-state events either in your custom-image installation process or user-data stages.
#!/bin/bash
apt-get update && apt-get upgrade -y
apt-get install jq -y
url="$(curl https://metadata.platformequinix.com/metadata | jq -r .user_state_url)"
send_user_state_event() {
data=$(
echo "{}" \
| jq '.state = $state | .code = ($code | tonumber) | .message = $message' \
--arg state "$1" \
--arg code "$2" \
--arg message "$3"
)
curl -v -X POST -d "$data" "$url"
}
send_user_state_event running 1000 "hey im still running"
send_user_state_event succeeded 1001 "hey im done now :)"