OVHcloud API and Storage

Learn about the OVHcloud API engine running in the background and the input data passed to it when customizing storage on a Dedicated Server.

With OVHcloud Dedicated Servers, you can configure Disks, hardware RAID, Partitions, software RAID, LVM, ZFS, etc., during OS reinstallation from the OVHcloud Control Panel, as well as the OVHcloud API, which is the focus of this guide. This will give us more details about the engine that is running in the background in order to create the storage customization on the dedicated server from the input data passed on to the OVHcloud API.

Providing in-depth details about storage configuration can help customers understand why:

• Their custom storage configuration could not be applied to their dedicated server.
• The actual storage configuration on the dedicated server is slightly different from what the customer requested.

Requirements

• A dedicated server ready to be installed/reinstalled in your OVHcloud account
• Access to the OVHcloud API

Instructions

During the default OS installation, the user is interactively prompted by the OS installer (provided by the software editor) to specify on which disks the Operating System will be installed, the partitioning layout, etc. Once the OS is installed, it is possible to change the partitioning layout, but it can be very tricky and risky, especially for partitions that are currently used by the system. For that reason, storage is a very important subject that needs to be considered before installing an Operating System.

Apart from the simplicity offered by an API, the main advantage is the possibility to fully customize the disks and partitions on which the OS will be installed.

On this page, we are focusing only on the storage sub-hash of the API call used to reinstall an OS on a dedicated server. For other customizations not related to storage, please read OVHcloud API & OS installation for more details.

{
    "operatingSystem": "debian12_64",
    "storage": [
        {
            "diskGroupId": 2,
            "hardwareRaid": [
                {
                    "raidLevel": null,
                    "disks": 2
                }
            ],
            "partitioning": {
                "disks": 2,
                "layout": [
                    {
                        "fileSystem": "ext4",
                        "mountPoint": "/boot",
                        "size": 1000,
                        "raidLevel": 1
                    },
                    {
                        "fileSystem": "ext4",
                        "mountPoint": "/",
                        "size": 0
                    }
                ]
            }
        }
    ]
}

Disk Groups

Some dedicated servers have multiple groups of disks. For example, one group with SATA disks and another group with SSD disks. Those servers are sometimes also called hybrid servers.

To list the disk groups and their disks, you can use the following API call in order to identify the disk group on which you want the OS to be reinstalled:

Example reply:

{
  "bootMode": "uefi",
  "defaultHardwareRaidSize": null,
  "description": "SCALE-7 - AMD Epyc 7763",
  "expansionCards": null,
  "threadsPerProcessor": 128,
  "memorySize": {
    "unit": "MB",
    "value": 524288
  },
  "defaultHardwareRaidType": null,
  "diskGroups": [
    {
      "defaultHardwareRaidType": null,
      "numberOfDisks": 2,
      "diskGroupId": 1,
      "diskType": "SSD",
      "defaultHardwareRaidSize": null,
      "diskSize": {
        "unit": "GB",
        "value": 480
      },
      "description": "2 X Disk SSD 480 GB, JBOD",
      "raidController": null
    },
    {
      "defaultHardwareRaidType": null,
      "numberOfDisks": 2,
      "diskGroupId": 2,
      "diskType": "NVME",
      "defaultHardwareRaidSize": null,
      "diskSize": {
        "unit": "GB",
        "value": 1920
      },
      "raidController": null,
      "description": "2 X Disk NVME 1920 GB, JBOD"
    }
  ],
  "processorArchitecture": "x86_64",
  "coresPerProcessor": 64,
  "processorName": "Epyc7763",
  "formFactor": "1u",
  "motherboard": "S8036-M",
  "numberOfProcessors": 1,
  "usbKeys": null
}

In this example, there are two disk groups:

• the first one (diskGroupId=1) contains 2 x 480 GB disks.
• the second one (diskGroupId=2) contains 2 x 1.9 TB disks.

Example of Debian 12 (Bookworm) OS installation on the diskGroup 2:

{
    "operatingSystem": "debian12_64",
    "storage": [
        {
            "diskGroupId": 2
        }
    ]
}

Hardware RAID

This section only applies to servers having at least a hardware RAID controller in one of their disk group.

Server & Hardware RAID Compatibility

You can get this information by using the following API call:

If your server doesn't have any hardware RAID controller, it will return an HTTP 403 (Forbidden) with the following message:

{
  "message": "Hardware RAID is not supported by this server"
}

Example of reply for a server with a hardware RAID controller:

{
  "controllers": [
    {
      "type": "mega",
      "disks": [
        {
          "names": [
            "c0:d0",
            "c0:d1",
            "c0:d2"
          ],
          "type": "SSD",
          "capacity": {
            "unit": "GB",
            "value": 960
          },
          "speed": {
            "value": "6g",
            "unit": "GB/s"
          }
        }
      ],
      "model": "9361-8i-2G"
    }
  ]
}

API & Hardware RAID

Example of OS installation with a hardware RAID 1 between the first two disks of the disk group:

{
    "operatingSystem": "debian12_64",
    "storage": [
        {
            "hardwareRaid": [
                {
                    "raidLevel": 1,
                    "disks": 2
                }
            ]
        }
    ]
}

Now, let's suppose you have a dedicated server with 1 disk group attached to the RAID controller and 12 disks in that disk group. Example with a hardware RAID 10:

{
    "operatingSystem": "debian12_64",
    "storage": [
        {
            "hardwareRaid": [
                {
                    "raidLevel": 10,
                    "arrays": 4
                }
            ]
        }
    ]
}

In this example, all the 12 disks will be involved in a hardware RAID of level 10. There will be 4 groups of 3 disks, meaning four RAID 1 across three disks and the four groups will be in RAID 0.

All disks involved in a hardware RAID configuration will be seen as 1 single virtual disk by the OS.

This means that if you have involved all disks of the target disk group in a hardware RAID configuration, configuring software RAID on top of it is not possible since the OS will see a single virtual disk.

Partitioning

Partitioning layout is about how your data will be organized and seen by the OS, i.e, everything that comes on top of your physical disks (or virtual disk if you have configured hardware RAID), up to the filesystem that is mounted, from the lowest to the highest layer:

• disk (physical/virtual disk, PD),
• partition (physical partition, PP),
• ZFS: vdev (zgroup, ZG), zpool (ZP), ZFS dataset (ZD), ZFS volume (ZV),
• software RAID (SR),
• LVM: physical volume (PV), volume group (VG), logical volume (LV),
• filesystem with a mountpoint (FS)

The following table provides an overview of the different partitioning components and how these layers interact with each other:

OS & Partitioning Compatibility

Since the partitioning configuration will be visible by the OS, the chosen OS for reinstallation has an impact on the possibilities you have in your partitioning customization.

In the /dedicated/installationTemplate section, you can display storage details such as LVM compatibility and filesystem availability for a specific OS:

Example:

{
    "templateName": "debian11_64",
    "filesystems": [
        "ext3",
        "ext4",
        "swap",
        "xfs"
    ],
    ...
    "lvmReady": true,
    "noPartitioning": false,
    "softRaidOnlyMirroring": false
}

The following API call can be used to list the different operating system's partitioning scheme names. Most operating systems support custom partitioning configuration and only have one single scheme named default. Only a few that don't support custom partitioning configuration (noPartitioning set to true) can therefore have multiple schemes.

The following API calls can be used to know which partitioning will be applied by default, if not customized or not customizable by OS.

LVM, RAID Levels & Filesystems Compatibility

The following table provides an overview of filesystem compatibility with RAID levels as well as LVM within the context of OVHcloud:

¹ See the ZFS vdevs vs standard RAID table for more details.
² The RAID level for swap can only be set to 1 within the OVHcloud API. In reality, the swap partitions will not use RAID. When a swap partition with size s is defined on a server with n disks, this will create n partitions of size s on every disk without any software RAID device underneath.
³ Windows native RAID (the one configured by the OVHcloud installer) supports RAID 1 but only between two disks while other implementations allow for more than two.
⁴ The ESXi installer does not support custom partitioning schemes. Partitioning is defined by the software publisher. Nevertheless, the OVHcloud API can give you an idea of what the partitioning looks like: see OS & Partitioning Compatibility for more details.

ZFS vdevs vs standard RAID

ZFS does not support standard RAID levels. It uses virtual devices (vdevs) to describe fault tolerance within a group of devices. See the official OpenZFS documentation for more details about vdevs.

In order to make the OVHcloud API as simple as possible, customers must define a standard RAID within the API for ZFS filesystems. The standard RAID level will then be translated to an equivalent vdev definition. The following table illustrates the translation of the various RAID levels offered by the OVHcloud API as well as a reminder of their respective characteristics.

API & Partitioning

Example of OS installation with a custom partitioning layout:

{
    "operatingSystem": "debian12_64",
    "storage": [
        {
            "partitioning": {
                "disks": 2,
                "layout": [
                    {
                        "fileSystem": "ext4",
                        "mountPoint": "/boot",
                        "size": 1000,
                        "raidLevel": 0
                    },
                    {
                        "fileSystem": "ext4",
                        "mountPoint": "/",
                        "size": 0
                    }
                ]
            }
        }
    ]
}

size 0 means that the partition will fill all the remaining space on the involved disks.

In this example, only the 2 first disks of the disk group will be involved in the partitioning (ie. in the software RAID).

As you can see, a partitioning layout is a list of partitions. Here is an example of a partition structure:

{
    "mountPoint": "/var/lib/vz",
    "fileSystem": "ext4",
    "size": 0,
    "raidLevel": "1",
    "extras": {
        "lv": {
            "name": "data"
        }
    }
}

The extras sub-hash is optional. It can only be used to specify that the partition will be a logical volume (and its name). It can also be used for ZFS:

{
    "mountPoint": "/",
    "fileSystem": "zfs",
    "size": 0,
    "raidLevel": "5",
    "extras": {
        "zp": {
            "name": "poule"
        }
    }
}

In this example, the / mount point will target a ZFS dataset in a zpool named "poule" in a raidz1. Please check ZFS vdevs vs standard RAID to get the matching between raidz and standard RAID levels.

Error handling

Basic customer input data errors are directly handled by the OVHcloud API. This is the most common and easiest situation as customers can see the error synchronously and retry immediately.

Customer input data related to partitioning might be too specific to be checked by the OVHcloud API and will require pre-processing time. The drawback is that customers are notified later during the OS reinstallation process.

Within the OVHcloud Control Panel, this is visible on the progress bar. From the OVHcloud API, this status can be obtained with the following API call:

There are two types of errors:

• ovh errors: the customer is not responsible for the error, the customer can reinstall with another partitioning layout, but OVHcloud will have to fix the bug.
• customer errors: the customer requested a partitioning layout that cannot be achieved or one that would prevent the server from booting properly.

In the next section, we will only focus on the customer errors types related to the partitioning because this is only helpful for the customer.

Common customer errors

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

Input customer auto-fixing

To improve customer experience, reduce OVHcloud support workload and to avoid introducing breaking changes for customers, some customer input is automatically fixed or changed by the backend. The following table gives an overview of what is currently auto-fixed/changed:

Go further

OVHcloud API & OS installation

Managing software RAID

Managing hardware RAID

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