Metal-published Operating System Images¶

Equinix Metal™ provides a range of operating systems available for you to deploy on our platform. Metal's operating system images are lightly modified versions of the upstream cloud images tailored to be compatible with our server hardware and network configurations.

We offer Linux and open-source operating systems at no extra cost, licensed operating systems billed by either a usage or bring-your-own license model, or you can bring-your-own operating system with Custom iPXE.

About Our Images¶

Changes to our operating system images are tracked in equinixmetal-images/changelog. Images are kept as close to upstream releases as possible.

The changelog aims to show what packages have changed since the last published image, the kernel used in the image, and what deviations from the upstream cloud image (if any) are in the new published image.

When you provision a server using one of our images, you get the most recent image we have published. Once you have provisioned your server, we no longer have access to the system; it is your responsibility to keep the operating system up to date.

If we do not offer an operating system or a version of an operating system that meets your use-case, you can bring your own images using Custom iPXE.

Image Lifecycle¶

Equinix Metal publishes the dates of our images' lifecycle in the API.

To find the lifecycle dates for a specific operating system and version, send a GET request to the /operating-systems endpoint, filtering on the operating system slug in the path.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/operating-systems?slug=<os_slug>

Response Parameters:

• “release_date” - The date the upstream operating system maintainer released this version.
• "build date" - The date Metal built and released the current operating system image.
• “deprecation_date” - The date set by the upstream operating system maintainer indicating the end of feature updates and bug fixes, and the beginning of security-only updates for this operating system version.
• “end_of_service_date” - A Metal-specific date, typically 30 days before end-of-life, when you should for prepare any new provisions to use the newest version of the operating system.
• “end_of_life_date” - The operating system image no longer receives any updates and can be disabled at any time. Metal typically matches the end-of-life date to the deprecation date set by the operating system maintainer.

The API response also includes a "lifecycle_state" parameter to indicate where the operating system image is in the lifecycle. Possible states are:

• "testing"
• "pre_release"
• "active"
• "deprecated"
• "end_of_service"
• "end_of_life"

Note that images in "testing" and "pre_release" states might not be in a provisionable or operable state. Trying to provision a server with a "testing" or "pre_release" image can result in an error, and should only be used for testing and evaluation.

End-of-Life Images¶

When an operating system image is end-of-life, you will no longer be available to provision it on new servers through the console or the API. End-of-life images are eventually de-listed from the Metal API entirely, and their changelogs removed from the changelog repository.

Servers running end-of-life operating systems will continue to run normally, but you will not be able to provision new servers with that same operating system image or version through the Metal console or API.

Operating Systems Reference¶

Debian¶

Default user: root

Rocky Linux¶

Default user: root

Ubuntu¶

Default user: root

Server Compatibility¶

All of our operating system images go through a validation process in order to be provisionable on our server plans. Not all operating systems are available on every server.

metal operating-systems get -o json

{
    "id": "d782347f-fd9a-4427-b7bb-6b9d4c1ebfc0",
    "slug": "debian_12",
    "name": "Debian 12",
    "version": "12",
    "provisionable_on": [
        "a3.large.x86",
        "c2.medium.x86",
        "c3.large.arm64",
        "c3.medium.x86",
        "c3.small.x86",
        ....    
    ]
},

curl -X GET \
-H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/operating-systems"

{
    "id": "d782347f-fd9a-4427-b7bb-6b9d4c1ebfc0",
    "slug": "debian_12",
    "name": "Debian 12",
    "version": "12",
    "provisionable_on": [
        "a3.large.x86",
        "c2.medium.x86",
        "c3.large.arm64",
        "c3.medium.x86",
        "c3.small.x86",
        ....    
    ]
},

Provisioning with a Metal-published Image¶

metal device create -p $METAL_PROJECT_ID -m <metro> -P <plan_slug> -O <os_slug>

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>",
    "plan": "<plan_slug>",
    "operating_system": "<os_slug>"
}'