Skip to content

Custom OS Images

The Equinix Metal™ official images are optimized for speed and therefore only have the minimum number of packages installed.

There are different use cases where the ability to deploy a custom image can reduce deployment time and streamline your workflow, especially in very active environments. While you can always install and remove packages (or adjust your kernel) after deploying an official OS image, using a custom image can streamline your customizations.

Building a Custom Image

Equinix Metal uses a GitHub repository to manage a selection of our officially supported Operating System images. Also included are a few tools that will allow you to create custom versions of those images.

The repository's branch layout has a "base" branch for each supported operating system distribution, example centos_7-base, ubuntu_18_04-base, etc. The base branch contains a Dockerfile (per supported architecture) with a sufficient level of customization to produce a standardized operating system experience across Equinix Metal's servers.

Hardware specific changes to an image are in their own branch. For example, a branch that has an Ubuntu 18.04 image tailored to the c3.small.x86 server is in the ubuntu_18_04-c3.small.x86 branch. If you want to create a custom Ubuntu image for a c3.small.x86 server, you can use the image from ubuntu_18_04-c3.small.x86, and the Dockerfile from ubuntu_18_04-base to complete a multi-stage build based off the official Equinix Metal base image.

The image is built with the packet-save2image tool, found in the master branch of the packethost/packet-images repository.

An example of building an image is in the repository's Readme.

Deploying a Custom Image

Once you have created a custom image, you can deploy it by specifying the repository and image tag in the UserData at the time of deployment. If you are using the Equinix Metal console to provision your server, select the operating system and version you're deploying (Ubuntu 18.04, CentOS 7, etc.) from the Select an Operating System section. Then enter your custom image information into the User Data field under Optional Settings.

#cloud-config
#image_repo=https://somegitserver/user/image-repo.git
#image_tag=b1ce89c2584b9fe1513ec72a481fd1c662db6808

️ The image_repo will be the clone address of the GitHub or GitLab repository where you pushed the image, and the image_tag is the hash of the commit when you pushed the image to that repository.

Deploying a Custom Image in the API

If you are using the Equinix Metal API to deploy servers with a custom image, you will send the image information 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 '{
    "facility": "<facility_code>",
    "plan": "<server_type>",
    "operating_system": "<os_code>",
    "userdata": "#cloud-config \
                 #image_repo=https://somegitserver/user/image-repo.git \ #image_tag=b1ce89c2584b9fe1513ec72a481fd1c662db6808"
}'