Bring Your Own Image (BYOI) – Support Guides

Learn how to use Bring Your Own Image (BYOI) on your OVHcloud Dedicated Server.

The Bring Your Own Image technology (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) answers correctly to the definition of technical expectations of a cloudready image.

Requirements

A dedicated server in your OVHcloud account
Access to the OVHcloud Control Panel (for the "Deployment via Control Panel" section of this guide)
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

NOTE: As with any classical OS installation, a new installation with BYOI will erase all the data on the server.

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

About RAID:

Bring Your Own Image (BYOI) does not support software RAID configuration at install time, but you can use the service Bring Your Own Linux (BYOLinux) for that. Choose the custom image method that fits your needs: Bring Your Own Image (BYOI) / Bring Your Own Linux (BYOLinux), a comparison sheet.
If Hardware RAID is supported, it is because it is configured before the image is deployed on the disk.

Deployment methods:

Deployment via the Control Panel: allows you to simply 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

From the OVHcloud Control Panel:

Click Bare Metal Cloud in the top navigation bar.
Select Dedicated servers in the left-side menu and choose your server.
In the General information box click the more options ... button next to Operating system (OS) then click Install.

DS_serverAdmin_BringYourOwnImage01***.png

In the window that appears, select Install from an OVHcloud template and click Next.

DS_serverAdmin_BringYourOwnImage02**.png

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

DS_serverAdmin_BringYourOwnImage03**.png

You will be redirected to the configuration page. Make sure your image URL is in the correct format. Complete 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.

DS_serverAdmin_BringYourOwnImage04**.png

Deploying your image via the APIs

POST /dedicated/server/{serviceName}/reinstall

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

NOTE: In the customizations section, only imageURL, imageType, efiBootloaderPath mandatory.

{
  "operatingSystem": "byoi_64",
  "customizations": {
    "hostname": "my-host",
    "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.com

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.com
disable_root: false
packages:
  - vim
  - tree
final_message: The system is finally up, after $UPTIME seconds

Once you completed the fields, start the deployment by clicking Execute.

Deployment options

Field	Description	Required
userMetadata/sshKey	SSH public key	❌
userMetadata/imageURL	Your image URL	✅
userMetadata/imageType	Your image format (qcow2, raw)	✅
userMetadata/imageCheckSum	Your image's checksum	❌
userMetadata/imageCheckSumType	Your image's checksum type (md5, sha1, sha256, sha512)	❌ (except if checksum provided)
userMetadata/configDriveUserData	Your configDrive file content¹	❌
userMetadata/configDriveMetadata	Custom Cloud-Init metadata	❌
userMetadata/httpHeaders?Key	HTTP Headers key	❌²
userMetadata/httpHeaders?Value	HTTP Headers value	❌²
userMetadata/ediBootloaderPath	Efi bootloader path	✅³

¹ Can either be a #cloud-config or a script. It must be in one-line and have \n for line-return

² Use only if you need HTTP Headers, such as Basic Auth

³ Examples of Efi bootloader path:

Operating System	efiBootloaderPath
Debian	`\\efi\\debian\\grubx64.efi`
Ubuntu	`\\efi\\ubuntu\\grubx64.efi`
Windows	`\\efi\microsoft\\boot\\bootmgfw.efi`
FreeBSD	`\\efi\\FreeBSD\\loader.efi`
Alma	`\\efi\\almalinux\\shimx64.efi`
Gentoo	`\efi\\boot\\bootx64.efi`

The ConfigDrive partition is used by cloud-init during the first server boot to apply your configurations. You can choose whether you want to use the default one, or a custom one (using configDriveUserData).

Common customer errors

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

Error message	Details	Solution(s)
Please provide checkSum AND checkSumType or none of them	You have specified only one of the arguments `imageCheckSum` and `imageCheckSumType`.	Either provide both arguments or none of them.
image provided format is `x` which does not match expected qcow2 format	Not matter what the file extension is, the real format has to be qcow2.	- Change the value of `imageType` to `raw`. - Convert your image to qcow2.
image provided has a size of `n` bytes which is larger than `device` of `m` bytes	The image provided has a size that is bigger than the size of the disk chosen for the OS installation.	- If your server has several disk groups, you can try to reinstall the OS on another disk group by specifying the `diskgroupid` argument. - You need to reduce the size of your image.
Can't write `t` on disk	Impossible to write qcow2/raw image on disk.	Modify your image so that the command `qemu-img convert -f "$imageType" -O raw $pathToImageFile "$device"` works.
Could not download, `t` image is too big to download in memory.	Your server doesn't have enough RAM to download the image.	You need to reduce the size of your image.
Could not download image located: `url`	Cannot download image from `imageURL`.	Check that a download with the `curl` command from your server works in rescue mode. If some HTTP specific headers are required, you can precise them with the `httpHeaders` argument.
image provided format is not of type raw because no partition table was found. It seems to contain: `x`	A raw image must contain a partition table.	Check that your image contains a partition table.
Bad `checkSumType` for downloaded file, got: `n` while expecting `m`.	Incorrect checksum.	- Please ensure that you have specified the correct checksum. - Check that a download with the `curl` command from your server works in rescue mode.