Concepts

Providers VM & volumes

Comment xbee délègue les VM et volumes à un binaire provider externe.

Xbee possède deux familles de providers :

• le provider interne Docker, utilisé par défaut lorsqu’aucun bloc provider n’est déclaré ;
• les providers VM externes, sélectionnés explicitement avec provider.name.

Un provider VM est un binaire externe nommé xbee-<nom> — par exemple xbee-aws ou xbee-azure — auquel xbee délègue le cycle de vie des VM, images, réseaux et volumes. Cette page décrit ces providers externes.

Packs système et ressources provider

Le système déclaré par l’utilisateur est un pack système racine fourni par XBee, par exemple ubuntu:24.04. Il ne s’agit pas de l’identifiant brut d’une ressource cloud. Le pack porte la définition portable du système ainsi que les métadonnées nécessaires à sa matérialisation par les providers compatibles.

La répartition des responsabilités est volontairement simple :

L’utilisateur n’a donc normalement pas à rechercher une AMI, recopier une famille d’image GCP, fabriquer un VMDK ou maintenir ces identifiants dans chaque environnement. Une surcharge provider reste possible pour un besoin avancé, mais elle ne constitue pas le parcours nominal.

Code source et publication

Les providers cloud AWS, Azure, Exoscale, GCP, Hetzner, IONOS, OVHcloud et Scaleway, ainsi que les providers locaux Firecracker, Cloud Hypervisor et QEMU, sont développés dans le dépôt privé commun iodasolutions/xbee-providers. Ils conservent chacun leur module Go et leur binaire xbee-<nom>, mais sont testés, compilés et publiés ensemble.

Lors de l’exécution, xbee lit le manifeste du canal latest, sélectionne l’artefact immuable correspondant au provider, au système et à l’architecture, puis vérifie son empreinte SHA-256 avant de lancer le binaire. Les anciens dépôts individuels ne sont plus des sources de build ou de publication.

À la première utilisation, Xbee télécharge directement le binaire correspondant à l’OS et à l’architecture courants :

https://download.xbee.io/latest/<os>_<arch>/xbee-<nom>.gz

Le téléchargement utilise cache-artefacts/ dans le répertoire interne Xbee.

Configurer un environnement avec un provider

Le provider est une map dont name est obligatoire. La forme scalaire historique provider: aws n’est plus acceptée :

provider:
  name: aws
  region: eu-west-3

Ces valeurs communes sont fusionnées avec default.host.provider, host.<nom>.provider et volume.<nom>.provider. Les valeurs les plus spécifiques complètent ou remplacent les valeurs communes. Xbee vérifie la structure générale et que les valeurs requises ne sont pas vides ; la signification précise des champs reste le contrat du binaire provider.

Enfin, un pack système fournit des métadonnées sous provider.<nom>. Elles sont transmises séparément au provider pour identifier son image OS de base. L’environnement n’a donc généralement pas à répéter une AMI, une famille d’image GCP, un VMDK ou son équivalent.

AWS (host.provider) :

provider:
  name: aws
  region: eu-west-3

default:
  host:
    system: ubuntu:24.04
    net: default
    provider:
      availabilityZone: eu-west-3a
      instanceType: t3a.medium
      size: 20

host:
  a: {}

volume:
  data1:
    size: 20
    provider:
      volumeType: gp3
      iops: 3000
      throughput: 125

GCP (host.provider) :

provider:
  name: gcp
  projectId: my-project
  zone: europe-west9-b

default:
  host:
    system: ubuntu:26.04
    net: xbee-net
    provider:
      instanceType: e2-medium
      size: 20

host:
  a: {}

volume:
  data1:
    size: 20
    provider:
      diskType: pd-balanced

Azure (host.provider) :

provider:
  name: azure
  subscriptionId: <subscription-id>
  resourceGroup: my-rg
  location: westeurope

default:
  host:
    system: ubuntu:26.04
    net: xbee-net
    provider:
      vmSize: Standard_D2s_v3
      size: 30

host:
  a: {}

volume:
  data1:
    size: 20
    provider:
      sku: Premium_LRS

Les valeurs par défaut connues de Xbee vivent dans ~/xbee.yaml. La commande xbee new env --provider <nom> les utilise pour générer le squelette de xbee-env.yaml. Les providers actuellement présents dans cette configuration sont virtualbox, aws, gcp, azure, scaleway et ovh; la convention de téléchargement permet d’en utiliser d’autres si leur binaire est publié.

Ces valeurs se consultent et se modifient avec xbee config; voir Configuration globale.

Données envoyées au binaire

Avant chaque appel, Xbee écrit une représentation normalisée de l’environnement dans .xbee/env.yaml, puis lance le binaire avec une action (up, down, infos, image, suppression de volumes ou d’images, etc.). Cette représentation distingue :

• les paramètres communs du provider ;
• la configuration provider de chaque hôte et volume ;
• les métadonnées provider.<nom> de chaque pack système ;
• l’identité et le hash des systèmes et packs applicatifs.

Orchestrateur

L’Orchestrateur (xbee/orchestrator.go) abstrait le cycle de vie container vs VM derrière une interface commune :

Up / Down / Enter / Delete / Operate / Pack

Les implémentations vivent sous xbee/container/ pour Docker et xbee/vm/ pour tous les providers externes. Le reste du modèle — packs, environnements et actions — est commun.

Volumes

Voir Environnements pour la déclaration d’un volume (volume: racine) et son association à un hôte (host.<nom>.volume:).

Pour la distinction entre volume natif d’un pack et volume externe, ainsi que leur cycle de vie avec les hyperviseurs locaux, voir VM locales et microVM.