OVHcloud API & Partitioning (EN)

Last updated 10th March 2023

Objective

With OVHcloud Dedicated Servers, you can configure Partitions, software RAID, LVM, ZFS, etc. during OS installation from the OVHcloud API as well as the OVHcloud Control Panel. In this article, we will focus on the OVHcloud API. This will give us more details about the engine that is running in the background in order to create the partitioning on the dedicated server from the input data passed on to the OVHcloud API.

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

• their custom partitioning could not be applied on their dedicated server.
• the actual partitioning on the dedicated server is slightly different from what the customer requested.

Requirements

• A dedicated server ready to be installed/re-installed 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, server partitioning 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.

Partitioning Overview

When we talk about partitioning layout, we are talking about how your data will be organized on the disks, i.e everything that comes on top of your disk, up to the filesystem that is mounted and visible to the OS: from lowest to highest layers:

• disk (physical 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:

Partitioning using the API

Template Concepts

When triggering an OS installation, the customer can either choose between several OVHcloud templates or choose between one of their personal templates (based on an OVHcloud template).

OVHcloud templates

An OVHcloud template is an official template that is nearly identical to the official software editor/vendor cloud-ready image.

To list available templates (depending on your server's hardware), use the following API call:

You can get the details such as LVM compatibility, filesystem availability of a specific OVHcloud template with the following API call:

Example:

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

The partitioning layout defined within an OVHcloud template cannot be changed: this is called the "default" partitioning scheme layout.

Customer Templates

Users can create custom installation templates based on OVHcloud templates in order to be able to create custom partitioning layouts:

Once created, the template inherits the default partitioning layout and partitions can be listed on the "default" scheme:

Of course a partition can be altered, deleted, added and then displayed:

API Partition Layout

Structure

A partiton layout is a list of partitions. Here is an example of a partition structure:

{
  "raid": "1",
  "filesystem": "ext4",
  "volumeName": "data",
  "size": 0,
  "order": 4,
  "type": "lv",
  "mountpoint": "/var/lib/vz",
}

Filesystems & LVM + RAID levels Comptibility Matrix

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 OVHcloud templates for more details.

ZFS vdevs vs standard RAID

ZFS does not support standard RAID levels. It refers to 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.

Partitioning Backend

Architecture

There is an abstraction layer between the partitioning description on the OVHcloud API (that is quite minimalist) and the real partitioning (that can be very complex).

The key feature of this partitioning is the separation between the pre-processing and the action script:

• the pre-processing runs on the OVHcloud infrastructure. It just converts the data from the OVHcloud API to a richer JSON representation.

• the action script runs on the customer's server, takes the rich JSON representation of the partitioning and creates the partitions.

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 therefore require pre-processing. The drawback is that customers are notified later during the OS installation 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 2 types of errors:

• ovh errors: the customer is not responsible for the error, the customer can re-install 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 within the partitioning pre-processing step, 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

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

Go further

Configuring Software RAID

Managing Hardware RAID

Join our community of users on https://community.ovh.com/en/.

Otras guías que podrían interesarle...