User State¶

Equinix Metal™ provides a User State endpoint for you to send and emit custom state information during the provisioning process.

When you setup provisioning with one of the Equinix Metal-issued operating system images, the User State endpoint is accessible from your server after the server hardware has come up and the imaging process is complete. In this setup, the standard use of the user state is to define the event in your user data script 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 your 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

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 \
http://tinkerbell.sv15.packet.net/events \
-d '{
    "state":"running",
    "code":1000,
    "message":"running the user data script"
    }' 

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 \ 
http://tinkerbell.sv15.packet.net/events \
-d '{
    "state":"succeeded",
    "code":1001,
    "message":"done running the user data script"
    }' 

Viewing the Events on the Timeline¶

The POST request adds an event to the server's timeline, which you can view from the console and the API.

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

Example Bash Script¶

The following is an example Bash script that you can use in either your custom image installation process or in your user data to send user state events.

#!/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 :)"