Stockage partagé CephFS pour un cluster Incus OS

Dans un cluster Incus, une instance peut être relancée ou déplacée sur n'importe quel nœud. Si ses données vivent sur le disque local d'un nœud, elles ne suivent pas. La réponse est un stockage partagé : un volume accessible depuis tous les nœuds à la fois. Ce guide montre comment attacher un CephFS (le système de fichiers distribué de Ceph) aux instances d'un cluster Incus OS, entièrement par API, sans jamais ouvrir de shell sur les nœuds. Public visé : administrateurs d'un cluster Incus OS disposant d'un cluster Ceph.

Ce que vous allez apprendre

Pourquoi un stockage partagé est nécessaire dès qu'on a un cluster.
Installer le client Ceph sur les nœuds via l'add-on incus-ceph.
Déclarer un cluster Ceph dans Incus OS avec le service ceph (API).
Attacher un CephFS à une instance via un disk device.
Régler les permissions d'écriture pour un conteneur non privilégié.

Prérequis

Un cluster Incus OS opérationnel. Voir Incus OS sans interface et Cluster Incus.
Un cluster Ceph joignable depuis les nœuds, avec un CephFS déjà créé (appelé labfs dans ce guide) et un utilisateur dédié (ici client.incus). Si vous partez de zéro, le guide Ceph : déployer un stockage distribué monte le cluster, les pools et le CephFS.
Un client Incus dont le certificat est approuvé, avec un remote vers chaque nœud.

Comme pour les mises à jour A/B, toute l'administration d'Incus OS passe par son API REST préfixée par /os, interrogée avec incus query. Le service Ceph se configure par nœud : les commandes ci-dessous ciblent chaque membre du cluster via son remote.

Pourquoi un stockage partagé en cluster

Un pool local (ZFS sur le disque système d'un nœud) est parfait pour une instance qui reste sur son nœud. Mais la valeur d'un cluster, c'est la résilience : si un nœud tombe, on veut relancer ses instances ailleurs. Sans stockage partagé, les volumes de données restent prisonniers du nœud en panne.

CephFS répond à ce besoin. C'est un système de fichiers monté simultanément par plusieurs clients en lecture-écriture. Deux instances, sur deux nœuds différents, voient et modifient les mêmes fichiers. Si vous connaissez Kubernetes, c'est l'équivalent d'un volume RWX (ReadWriteMany) fourni par une classe de stockage distribuée. Ceph propose aussi du bloc (RBD, plutôt ReadWriteOnce) via source=ceph:, mais pour un volume partagé entre instances, c'est bien CephFS qu'il faut.

Installer le client Ceph sur les nœuds

Incus OS n'embarque pas le client Ceph par défaut. Il faut installer l'application incus-ceph, un add-on qui ajoute les binaires Ceph au système immuable. On la déclenche par un POST sur l'endpoint des applications, pour chaque nœud :

for n in node1 node2 node3; do
  incus query -X POST "$n:/os/1.0/applications" -d '{"name":"incus-ceph"}'
done

La réponse est vide en cas de succès. Vérifiez ensuite que l'application est bien présente sur chaque nœud :

incus query node1:/os/1.0/applications

La liste doit contenir /os/1.0/applications/incus-ceph à côté de /os/1.0/applications/incus. Tant que cet add-on n'est pas installé, le service ceph décrit plus bas reste indisponible.

Déclarer le cluster Ceph

Une fois le client présent, on déclare le cluster Ceph via le service ceph. On fournit trois informations : le FSID du cluster Ceph, l'adresse d'au moins un moniteur, et la clé de l'utilisateur Ceph. Ces valeurs se récupèrent côté Ceph (ceph fsid, ceph mon dump, et ceph fs authorize labfs client.incus / rw pour la clé).

La configuration s'applique par un PUT sur services/ceph, sur chaque nœud :

cat > /tmp/ceph.json <<'JSON'
{
  "config": {
    "enabled": true,
    "clusters": {
      "ceph": {
        "fsid": "f2a9d236-38b5-4b79-a111-da7e41163404",
        "monitors": ["192.168.10.202"],
        "keyrings": {
          "incus": { "key": "AQDxpkZqrH5SNBAA4c7dybjWDdNl1x3Qsi6nDA==" }
        }
      }
    }
  }
}
JSON

for n in node1 node2 node3; do
  incus query -X PUT "$n:/os/1.0/services/ceph" -d "$(cat /tmp/ceph.json)"
done

À partir de cette configuration, Incus OS écrit lui-même /etc/ceph/ceph.conf (avec le FSID et le moniteur) et le fichier de keyring du client. Le nom du cluster, ici ceph, est la clé de l'objet clusters ; c'est lui qu'on réutilisera comme ceph.cluster_name au moment d'attacher le volume.

Attacher le CephFS à une instance

Le montage se fait avec un disk device de type disk dont la source commence par cephfs:. On précise le système de fichiers et un sous-chemin, l'utilisateur Ceph et le nom du cluster déclaré plus haut :

incus config device add node1:cephtest cephvol disk \
  source=cephfs:labfs/incusdata \
  ceph.user_name=incus \
  ceph.cluster_name=ceph \
  path=/data

L'instance monte alors le CephFS sur /data. La commande df le confirme depuis l'intérieur :

incus exec node1:cephtest -- df -hT /data

Filesystem                                         Type  Size  Used Avail Use% Mounted on
incus@f2a9d236-38b5-4b79-a111-da7e41163404.labfs=/ ceph   19G     0   19G   0% /data

Le type ceph et le FSID dans le nom du montage confirment que le client kernel CephFS est bien actif et que l'authentification cephx a réussi.

Régler les permissions d'écriture

Le montage réussit, mais un conteneur non privilégié échoue souvent à écrire, avec un Permission denied. La cause est le mapping d'UID d'Incus : le root du conteneur (uid 0) est projeté sur l'hôte, et donc côté CephFS, en uid 1000000 par défaut. Si la racine du CephFS appartient à root, cet uid décalé n'a pas les droits.

La solution propre est de préparer un sous-répertoire dédié appartenant à l'uid mappé, depuis un client qui monte déjà le CephFS en administrateur :

# Sur un hôte disposant du client Ceph, monté sur /mnt/cephfs :
mkdir /mnt/cephfs/incusdata
chown 1000000:1000000 /mnt/cephfs/incusdata

Il suffit ensuite de pointer le disk device sur ce sous-chemin (source=cephfs:labfs/incusdata, comme ci-dessus). Le conteneur écrit alors sans erreur, et le fichier apparaît côté Ceph avec le propriétaire 1000000 :

incus exec node1:cephtest -- sh -c 'echo bonjour > /data/hello.txt'

Vérifier le partage

L'intérêt du CephFS se voit quand plusieurs clients accèdent au même chemin. Un fichier déposé côté Ceph (ou par une autre instance) est immédiatement visible dans l'instance :

incus exec node1:cephtest -- ls -l /data/

Un fichier créé par l'instance apparaît de la même façon côté Ceph et pour tout autre client montant labfs. C'est cette cohérence partagée qui permet à une instance relancée sur un autre nœud de retrouver ses données intactes, à condition d'attacher le même disk device dans son profil ou sa configuration.

Dépannage

Symptôme	Cause probable	Solution
`errno 95` / `no keyring found` au montage	Clé `keyrings` nommée `client.incus` au lieu de `incus`	Corriger le `PUT` du service ceph, la clé de map est le nom d'utilisateur seul
Le service `ceph` renvoie `not found`	Add-on `incus-ceph` absent sur le nœud	Installer l'application par `POST /os/1.0/applications`
`Permission denied` en écriture depuis un conteneur	UID `root` mappé sur `1000000`	Créer un sous-répertoire `chown 1000000` et pointer le device dessus
`error connecting to the cluster`	Moniteur injoignable depuis le nœud	Vérifier la route réseau et l'adresse dans `monitors`

À retenir

Un cluster exige un stockage partagé pour que les instances gardent leurs données en changeant de nœud.
CephFS fournit un volume partagé (RWX) ; RBD (source=ceph:) fournit du bloc (RWO).
Sur Incus OS, tout passe par l'API : add-on incus-ceph, puis service ceph avec FSID, moniteurs et keyring.
La clé de l'objet keyrings est le nom d'utilisateur seul (incus), pas client.incus.
On attache le volume avec un disk device source=cephfs:<fs>/<chemin>.
Un conteneur écrit avec un UID mappé (1000000) : aligner le propriétaire du sous-répertoire.

Prochaines étapes

Déployer un cluster Ceph Monter Ceph avec cephadm : RADOS, RBD et CephFS.

Cluster Incus Quorum, nœuds par token et récupération après panne.

Incus OS sans interface Installation, seed et cluster sans shell.

Mises à jour A/B et rollback Mettre à jour un cluster Incus OS sans coupure.

Stockage Incus Pools locaux dir, ZFS, LVM et volumes.