Concepts

VM locales et microVM

Exécuter un environnement XBee avec Firecracker, Cloud Hypervisor ou QEMU/KVM.

XBee peut matérialiser un environnement local sous forme de machines virtuelles indépendantes. Trois providers Linux sont disponibles :

Ils utilisent le même modèle XBee que Docker et les providers cloud : packs système, packs applicatifs, actions, opérations et volumes. La différence se trouve dans la matérialisation de l’hôte : chaque instance est ici une vraie VM avec son noyau, son adresse IP, son disque racine et son processus d’hyperviseur.

Le support fonctionnel actuellement validé pour les trois providers est Linux AMD64. ARM64 n’est pas annoncé comme supporté tant qu’un bundle de noyau AArch64 versionné et un hôte ARM64 avec KVM ne permettent pas d’exécuter les smoke tests complets.

Prérequis de l’hôte

Les trois providers nécessitent :

• Linux sur une machine AMD64 ;
• la virtualisation matérielle activée dans le BIOS ou l’UEFI ;
• /dev/kvm accessible en lecture et écriture ;
• Docker, utilisé pour construire l’image et injecter la configuration invitée ;
• ip, iptables, sysctl, mkfs.ext4, e2fsck et resize2fs ;
• sudo -n autorisé pour la création des bridges, interfaces TAP et règles réseau ;
• une clé SSH XBee, normalement créée automatiquement sous ~/.xbee/.ssh/.

Le runtime correspondant doit également être installé :

# Vérifications communes
test -r /dev/kvm && test -w /dev/kvm
command -v docker ip iptables mkfs.ext4 e2fsck resize2fs

# Puis l'un des runtimes
command -v firecracker
command -v cloud-hypervisor
command -v qemu-system-x86_64

Environnement minimal

Seul le nom du provider change entre les trois variantes :

schema-version: "1.0"

provider:
  name: qemu
  host:
    vcpu: 2
    memory: 2048

default:
  host:
    system: https://github.com/xbeerepository/ubuntu.git:26.04
    net: application

host:
  worker:
    count: 3

Les paramètres provider.host actuellement communs sont :

xbee up attribue une IP distincte à chaque instance développée par count, crée le réseau local, clone son disque racine et lance un processus d’hyperviseur par VM. Les instances communiquent directement sur leurs IP privées ; deux VM peuvent donc écouter toutes les deux sur 5432, 8080 ou tout autre port sans collision.

Construction des images

Une image locale doit être construite avant le premier démarrage :

xbee pack
xbee up

xbee pack :

1. construit l’image OCI issue du pack système et du pack applicatif ;
2. résout le bundle de noyau déclaré dans provider.<nom>.kernel par le pack système ;
3. vérifie son empreinte SHA-256 ;
4. exporte le système de fichiers OCI dans une image ext4 ;
5. injecte les modules correspondant au noyau ;
6. publie le bundle dans un store local adressé par le hash du pack.

Le bundle contient au minimum vmlinuz, rootfs.ext4, manifest.json, une configuration de runtime et SHA256SUMS. Une image applicative est complète : si elle est présente, XBee n’exige pas une seconde image contenant uniquement le système.

Les packs Ubuntu 24.04 et 26.04 déclarent aujourd’hui le même bundle de noyau microVM AMD64 pour Firecracker, Cloud Hypervisor et QEMU. L’environnement n’a donc pas à fournir lui-même une URL de noyau.

Réseau et adresses IP

Chaque environnement possède un bridge Linux et un sous-réseau privé déterministe. Chaque VM reçoit :

• une interface TAP dédiée ;
• une adresse MAC stable ;
• une IP propre ;
• une route par la passerelle du bridge ;
• un accès sortant grâce au NAT de l’hôte.

Le bridge et les règles NAT appartiennent à l’environnement ; les interfaces TAP appartiennent aux instances. xbee delete supprime les instances et le réseau de l’environnement.

L’IP est exposée par xbee infos et utilisée directement par XBee pour SSH. Il n’est donc généralement pas nécessaire de transformer le port d’un service en variable d’entrée uniquement pour éviter une collision entre instances.

Deux catégories de volumes

Les providers locaux respectent la distinction entre le volume natif d’un pack et les volumes externes déclarés par l’environnement.

Volume natif du pack

Un pack peut déclarer un élément volume optionnel. XBee crée alors automatiquement un disque ext4 propre à chaque instance, sans déclaration supplémentaire dans xbee-env.yaml.

• le disque est exposé comme /dev/vdb lorsqu’il suit immédiatement le disque racine ;
• il est monté dans l’invité sous /xbee/volume ;
• les chemins persistants du pack sont résolus sous /xbee/instance ;
• il survit à down puis up ;
• son cycle de vie est lié à l’instance et il est supprimé avec xbee delete.

Sa taille peut être réglée globalement :

provider:
  name: cloud-hypervisor
  host:
    instanceVolumeSize: 20

Une instance ne doit normalement héberger qu’une instance du service décrit par son pack. Par exemple, une microVM PostgreSQL possède son propre volume et peut conserver le port PostgreSQL standard.

Volumes externes de l’environnement

Un élément volume à la racine de l’environnement décrit une ressource indépendante du host et du volume natif du pack :

provider:
  name: qemu

default:
  host:
    system: https://github.com/xbeerepository/ubuntu.git:26.04

host:
  database:
    pack: https://github.com/xbeerepository/postgresql.git:18
    volume: data,backup

volume:
  data: 20
  backup: 5

Ces volumes sont des fichiers ext4 conservés à côté des instances. Ils sont attachés après le volume natif et montés sous /xbee/volumes/<nom>.

• down et up les conservent ;
• delete détache les volumes et supprime les VM, mais conserve leurs données ;
• leur suppression exige une opération explicite :

xbee admin delete volume --force data backup

Un volume externe en lecture-écriture ne peut pas être attaché simultanément à deux VM. Pour plusieurs instances, utilisez des noms développés distincts ou un stockage réellement partagé fourni par un autre service.

Les volumes ext4 peuvent grandir hors ligne. Une réduction est refusée avant tout arrêt de la VM afin d’éviter la corruption ou la perte de données.

Cycle de vie et réconciliation

xbee pack          # construit les bundles manquants
xbee up            # crée ou réconcilie, puis configure les VM
xbee infos         # affiche les instances, IP et états
xbee plan --state  # compare l'état déclaré et l'état observé
xbee down          # exécute les actions down et arrête proprement les VM
xbee up            # redémarre avec les mêmes disques
xbee delete        # supprime VM et volumes natifs, conserve les volumes externes

Le provider calcule une identité de configuration à partir de l’image, des vCPU, de la mémoire et des volumes attachés. Une modification de cette identité redémarre la VM en préservant son disque racine et ses volumes. Un changement d’image remplace en revanche l’instance.

Firecracker utilise son socket API, Cloud Hypervisor son API REST sur socket Unix et QEMU son moniteur QMP. Lors d’un down, XBee demande d’abord un arrêt propre de l’invité, arrête ensuite le VMM, puis utilise les signaux du processus uniquement en dernier recours.

Les actions up, down et les éléments operate restent ceux de l’environnement et des packs : les providers locaux n’introduisent pas un second modèle d’opérations.

Choisir le provider

Le modèle fonctionnel XBee est volontairement similaire entre ces providers. Ils ne sont toutefois pas interchangeables au niveau des performances, des périphériques et des possibilités de diagnostic. Validez toujours sur le provider cible les usages qui dépendent du noyau, de systemd, du réseau ou du stockage bloc.

À lire ensuite : Providers VM et volumes, Environnements et Cycle de vie et adoption.