Bring Your Own Image (BYOI)

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

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

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:

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

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

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. 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.

Deploying your image via the APIs

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

POST /dedicated/server/{serviceName}/install/start

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

{
  "details": {
    "customHostname": "myCustomBYOI"
  },
  "templateName": "byoi_64",
  "userMetadata": [
    {
      "key": "sshKey",
      "value": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9xPpdqP3sx2H+gcBm65tJEaUbuifQ1uGkgrWtNY0PRKNNPdy+3yoVOtxk6Vjo4YZ0EU/JhmQfnrK7X7Q5vhqYxmozi0LiTRt0BxgqHJ+4hWTWMIOgr+C2jLx7ZsCReRk+fy5AHr6h0PHQEuXVLXeUy/TDyuY2JPtUZ5jcqvLYgQ== my-nuclear-power-plant"
    },
    {
      "key": "imageURL",
      "value": "https://cdimage.debian.org/cdimage/cloud/bullseye/20230124-1270/debian-11-generic-amd64-20230124-1270.raw"
    },
    {
      "key": "imageType",
      "value": "raw"
    },
    {
      "key": "httpHeaders0Key",
      "value": "Authorization"
    },
    {
      "key": "httpHeaders0Value",
      "value": "Basic bG9naW46cGFzc3dvcmQ="
    },
    {
      "key": "imageCheckSum",
      "value": "2cbd3dd5606ef95a5cfa47943b3ad453fcc43522915be7f559a296a71395f82f88e621e558df7aa5f3d2e62c20043f9430ad18c900e565a1c070066e8d008aaa"
    },
    {
      "key": "imageCheckSumType",
      "value": "sha512"
    },
    {
      "key": "configDriveUserData",
      "value": "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

¹ 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

Result examples

Here are some results you might have:

Go further

OVHcloud API and OS Installation

Bring Your Own Linux (BYOLinux)

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

For more information and tutorials, please see our other Dedicated Servers support guides or explore the guides for other OVHcloud products and services.