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, or failed.
• "code" - an integer between 1000 and 1099, 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 :)"