User Data

When provisioning a server on Equinix Metal™ you have the option to include User Data, which can be used to perform various automation tasks after the server is ready, such as executing common scripts, installing packages, or triggering other more advanced configuration processes.

Usage

Equinix Metal user data is based on open-source project cloudbase-init and officially supports two user data formats.

User Data Scripts

Scripts are for executing shell scripts and begin with #! for Linux shell or #ps1 for Windows Powershell.

Debian/Ubuntu

#!/bin/bash
export DEBIAN_FRONTEND=noninteractive
apt-get update && apt-get upgrade -y
apt-get install nginx -y

Windows

#ps1
New-Item C:/Users/Admin test.txt
Set-Content C:/Users/Admin/test.txt "Hello world"

$password = ConvertTo-SecureString "P@55w0rd!" -AsPlainText -Force
New-LocalUser -Name "user01" -Password $password

Cloud Config Data

Cloud Config data must use valid yaml syntax and begins with #cloud-config

#cloud-config
package_upgrade: true
packages:
    -  nginx

info

Support for formats other than #!<script> and #cloud-config are experimental.

Provisioning with User Data

Console

When provisioning a server from the Metal console, add User Data by expanding the Optional Settings > User data tab.

Paste your script into the field. Click Deploy Now. The script is read and executed during the server provisioning process.

CLI

When provisioning a server from the CLI, use the metal device create command and include your user data script with -u, --userdata or include a path to a file that contains your user data script on your local machine with --userdata-file.

metal device create --project-id <project_UUID> --plan <server_type> --metro <metro_code> --operating-system <os_code> --userdata-file <local_file_path>

API

When provisioning in the API, send a POST request to the projects/{id}/devices endpoint and include your user data script with the "userdata" parameter in the body of the request.

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>"
    "userdata": <string>
}'

note

Depending on the length of your script, allow some time for the server provisioning process to execute after you see the server as "Active."

Managing User Data

Console

A server's user data is available in the server's Settings tab, under User Data.

CLI

To retrieve a server's user data from the CLI, use the metal device get command, specifying with the -o, --output flag to retrieve the full json output, which will include the user data in the "userdata" field.

metal device get -i <device_id> -o json

API

To retrieve a server's user data from the API, send a GET request to the /devices/{id}/userdata endpoint.

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

info

You can also access the user data from the server from its metadata endpoint. SSH into the server and send a request to https://metadata.platformequinix.com/userdata.

Verifying User Data on the Server

To verify the user data stored on your server, check for it at /var/lib/cloud/instance/user-data.txt.

The server logs for user data are available at /var/log/cloud-init.log and /var/log/cloud-init-output.log

Adding User Data Post-Provisioning

During provisioning, user data is executed on a server's first bootup. You can add user data to an already provisioned server, but you must reinstall the server first to execute the new user data.

warning

Reinstalling is a disruptive operation and has options that include deleting data. Proceed with caution.

Console

Update the user data field in the server's Settings tab, under User Data.

Click Save. The new user data will be written to the server and appear in the server's metadata immediately, but will not be executed until you preform a server Reinstall.

CLI

To update user data, use the metal device update command and include your updated user data script with -u, --userdata or include a path to a file that contains your updated user data script on your local machine with --userdata-file.

metal device update --project-id <project_UUID> --plan <server_type> --metro <metro_code> --operating-system <os_code> --userdata-file <local_file_path>

The new user data will be written to the server and appear in the server's metadata immediately, but will not be executed until you preform a server Reinstall.

API

When provisioning in the API, send a PUT request to the projects/{id}/devices endpoint and include your updated user data script with the "userdata" parameter in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
    "userdata": <string>
}'

The new user data will be written to the server and appear in the server's metadata immediately, but will not be executed until you preform a server Reinstall.