Concepts

Packs

L'unité de packaging de xbee : dépendances, types de packs et cycle de vie.

Un pack est un artefact YAML. Le descripteur s’appelle xbee-pack.yaml, xbee-pack-system.yaml, xbee-pack-builder.yaml ou xbee-pack-dev.yaml selon le type.

son système requis (require) — l’image OS sous-jacente
ses dépendances — des packs installés dans l’image avant lui
ses builders — des packs utilisés uniquement au moment de la construction
son modèle de données — const, var, in (voir Modèle de données)
ses actions de cycle de vie — provision, deploy, configure, up, down, command

Propriétés de premier niveau

Propriété	Rôle
`schema-version`	Version du modèle de données (`1.0` actuellement, ajoutée automatiquement si absente)
`description`	Documentation libre, non utilisée par xbee en interne
`dependency`	Une dépendance (string, map, ou liste de map)
`builder`	Un ou plusieurs packs builders injectés automatiquement pendant `provision`
`require`	Pack système utilisé comme image de base
`env`	Variables d’environnement embarquées dans le descripteur du container/VM
`user`	`USER` du container ; calculé par défaut depuis l’extension, `require`, ou l’image système
`directory`	Répertoire par défaut pour `xbee enter` et les commandes shell de `cmd`

Dépendances

Une dépendance peut être :

une chaîne — l’origin de la dépendance (ex. tomcat)
une map — l’objet dépendance complet
une liste de maps — plusieurs dépendances

Les coordonnées d’une dépendance sont origin (dépôt Git ou chemin relatif/absolu sur le système de fichiers hôte) et, si versionnée, commit. On peut y ajouter ref (branche ou tag) et var (surcharge du modèle de données de la dépendance) :

dependency:
  origin: ./tomcat
  var:
    jdk.xbee.version: 21

Une dépendance est installée dans l’image du pack avant l’installation du pack lui-même.

Types de packs

Type	Fichier	Rôle
`default`	`xbee-pack.yaml`	Pack applicatif standard
`system`	`xbee-pack-system.yaml`	Image OS de base (ex. `ubuntu:24.04`)
`builder`	`xbee-pack-builder.yaml`	Construit un artefact sans faire partie de l’image finale
`dev`	`xbee-pack-dev.yaml`	Complément de développement associé à un pack système

Un pack système peut contenir une section provider indexée par nom :

provider:
  aws:
    # métadonnées du système attendues par xbee-aws
  gcp:
    # métadonnées du système attendues par xbee-gcp

Ces valeurs décrivent comment un provider doit retrouver ou préparer ce système. Xbee transmet provider.<nom> au binaire sélectionné par l’environnement.

Un pack peut aussi étendre un autre pack, qui sert de template :

extend: ubuntu

Pack dev

Un pack système peut être associé à un pack dev, défini dans son propre répertoire, qui s’appuie sur la même image et supporte const/var et l’action provision :

dev: ./ubuntu-dev

Cycle de vie

Tout pack dispose par défaut d’actions up, down et configure qui ne font rien — ce sont les points de liaison entre un environnement et le pack. La commande xbee up d’un environnement invoque la tâche up de chaque pack concerné ; une tâche up/down décrit une action shell (voir Actions).

Pour un pack pris isolément (hors environnement), xbee pack enchaîne :

système → acquisition/build des builders → provision → deploy

Le système fournit l’image de base. Avant le provisioning du pack, les entrées builder sont résolues : Xbee réutilise un artefact validé du cache local ou distant, ou exécute l’action build du xbee-pack-builder.yaml. Il injecte ensuite automatiquement chaque archive au début de provision, avant les actions déclarées par le pack. Aucune action copy n’est nécessaire dans le manifeste consommateur.

provision produit une image en installant les dépendances, les artefacts builders et les actions du pack. deploy, lorsqu’il est déclaré, produit ensuite une couche supplémentaire indépendante de ce mécanisme.

Puisque provision et deploy génèrent chacune une image, mieux vaut toujours remonter au niveau provision lorsqu’il n’y a rien à construire, seulement à installer : deploy n’a de sens que couplé à un véritable build.

Par défaut, Xbee réutilise les images et artefacts valides. --force-system et --force-provision forcent la reconstruction des couches correspondantes. --rebuild-builders ignore les artefacts builders en cache ; --no-remote-builder-cache interdit leur récupération depuis le cache distant. xbee pack --plan affiche le plan sans construire d’image ni modifier un provider.

Voir Builders et artefacts pour le détail.