Bring Your Own Image (BYOI) (EN)

Objective

The Bring Your Own Image feature (BYOI) enables you to deploy cloudready images directly on your dedicated server. You can therefore use the bare metal service as a resource for your deployments.

What does cloudready mean?

The cloudready standard generally means being agnostic of the infrastructure on which the image is deployed. In addition to the requirements and limitations mentioned below, you must ensure that the image (downloaded or generated) meets the technical expectations of a cloudready image.

This guide explains how to use Bring Your Own Image (BYOI) on your OVHcloud dedicated server.

Requirements

• A dedicated server in your OVHcloud account
• Access to the OVHcloud Control Panel (for the "Deployment via Control Panel" method)
• Access to the OVHcloud API (for the "Deployment via API" section of this guide)
• Your image must be smaller than the server RAM minus 3GiB

Instructions

Technical limitations:

There are some technical limitations linked to the use of physical products such as dedicated servers. Here is a non-exhaustive list, to keep in mind during your deployment preparation:

• Boot type: uefi or legacy
• Partition type: MBR or GPT
• Image format: qcow2 or raw

Deployment methods:

• Deployment via the Control Panel: allows you to deploy your image using the OVHcloud Control Panel.
• Deployment via API: you can use the OVHcloud API to integrate images into your own scripts to automate deployments.

Deploy your image via the Control Panel

Log in to the OVHcloud Control Panel and go to the Bare Metal Cloud section, then select your server under Dedicated servers.

In the General information tab, click the ... button next to "System (OS)" then click Install.

In the window that appears, select Custom in the menu, then Bring Your Own Image - byoi, and click Next.

You will be redirected to the configuration page. Make sure your image URL is in the correct format. Fill in the rest of the required fields on this page. Once you have confirmed that the information is correct, click Confirm.

You can find more details on the options in the deployment options section below.

For more information and examples about Cloud-Init's ConfigDrive, please read the official documentation on this page.

Deploy your image via the API

Log in to the API console and go to the /dedicated/server section.

The Bring Your Own Image (BYOI) payload should be similar to the following:

{
  "operatingSystem": "byoi_64",
  "customizations": {
    "hostname": "mon-tux",
    "imageURL": "https://cdimage.debian.org/cdimage/cloud/bullseye/20230124-1270/debian-11-generic-amd64-20230124-1270.raw",
    "imageType": "raw",
    "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9xPpdqP3sx2H+gcBm65tJEaUbuifQ1uGkgrWtNY0PRKNNPdy+3yoVOtxk6Vjo4YZ0EU/JhmQfnrK7X7Q5vhqYxmozi0LiTRt0BxgqHJ+4hWTWMIOgr+C2jLx7ZsCReRk+fy5AHr6h0PHQEuXVLXeUy/TDyuY2JPtUZ5jcqvLYgQ== my-nuclear-power-plant",
    "efiBootloaderPath": "\\efi\\debian\\grubx64.efi",
    "imageCheckSum": "2cbd3dd5606ef95a5cfa47943b3ad453fcc43522915be7f559a296a71395f82f88e621e558df7aa5f3d2e62c20043f9430ad18c900e565a1c070066e8d008aaa",
    "httpHeaders": {
      "Authorization": "Basic bG9naW46cGFzc3dvcmQ="
    },
    "imageCheckSumType": "sha512",
    "configDriveUserData": "I2Nsb3VkLWNvbmZpZwpzc2hfYXV0aG9yaXplZF9rZXlzOgogIC0gc3NoLXJzYSBBQUFBQjhkallpdz09IG15c2VsZkBteWRvbWFpbi5uZXQKCnVzZXJzOgogIC0gbmFtZTogcGF0aWVudDAKICAgIHN1ZG86IEFMTD0oQUxMKSBOT1BBU1NXRDpBTEwKICAgIGdyb3VwczogdXNlcnMsIHN1ZG8KICAgIHNoZWxsOiAvYmluL2Jhc2gKICAgIGxvY2tfcGFzc3dkOiBmYWxzZQogICAgc3NoX2F1dGhvcml6ZWRfa2V5czoKICAgICAgLSBzc2gtcnNhIEFBQUFCOGRqWWl3PT0gbXlzZWxmQG15ZG9tYWluLm5ldApkaXNhYmxlX3Jvb3Q6IGZhbHNlCnBhY2thZ2VzOgogIC0gdmltCiAgLSB0cmVlCmZpbmFsX21lc3NhZ2U6IFRoZSBzeXN0ZW0gaXMgZmluYWxseSB1cCwgYWZ0ZXIgJFVQVElNRSBzZWNvbmRzCg=="
  }
}

Even though the configDrive user data could be sent to the API directly in clear text by escaping special characters, it is recommended to send a base64-encoded script to the API. You can use the following UNIX/Linux command to encode your data:

cat my-data.yaml | base64 -w0

Here is the clear-text configDrive user data from the example above:

#cloud-config
ssh_authorized_keys:
  - ssh-rsa AAAAB8djYiw== myself@mydomain.net

users:
  - name: patient0
    sudo: ALL=(ALL) NOPASSWD:ALL
    groups: users, sudo
    shell: /bin/bash
    lock_passwd: false
    ssh_authorized_keys:
      - ssh-rsa AAAAB8djYiw== myself@mydomain.net
disable_root: false
packages:
  - vim
  - tree
final_message: The system is finally up, after $UPTIME seconds

Once you have filled in the fields, start the deployment by clicking Execute.

Deployment options

¹ Can either be a #cloud-config or a script. Its JSON representation must be on a single line with \n for line breaks, as JSON strings cannot contain literal newlines.
² Use only if you need HTTP Headers, such as Basic Auth
³ The EFI bootloader path is used by iPXE to boot your operating system. For more information, see Understanding the dedicated server boot process. Examples:

Common customer errors

The following table gives an overview of well-known customer errors and how to fix them.

Go further

OVHcloud API & OS installation

Bring Your Own Linux (BYOLinux)

Bring Your Own Image (BYOI) / Bring Your Own Linux (BYOLinux), a comparison sheet

Understanding the dedicated server boot process

Join our user community on https://community.ovh.com/en/.