xbee

Concepts

Conteneur d'initialisation

Exécuter une préparation locale, bloquante et éphémère avant les hôtes d'un environnement.

Le bloc init d’un xbee-env.yaml exécute une préparation dans un conteneur Docker local avant la première configuration des hôtes. Il convient par exemple pour générer des fichiers, initialiser un dépôt de configuration ou appeler une commande fournie par un pack.

Cette étape reste locale, même lorsque les hôtes de l’environnement sont des VM créées par un provider cloud. Le poste qui lance XBee doit donc disposer de Docker et de l’image nécessaire.

Cycle de vie

Lors d’un xbee up, XBee :

  1. construit le modèle synthétique init/1 et son enveloppe de secrets ;
  2. démarre un conteneur éphémère depuis les packs système et applicatif sélectionnés ;
  3. exécute le bootstrap puis l’action name ou shell ;
  4. tente un arrêt gracieux et supprime le conteneur, y compris après une erreur.

L’initialisation est bloquante. Une image absente, un bootstrap impossible ou une action en échec interrompt la montée de l’environnement. Construisez les images avec xbee pack avant xbee up.

Le conteneur porte un nom temporaire de la forme xbee-init-* et n’est pas conservé après l’exécution. Si l’arrêt gracieux échoue, XBee effectue une suppression forcée.

Choisir le système et le pack

system sélectionne le pack système du conteneur. Lorsqu’il est omis, XBee utilise le système du premier hôte de l’environnement. pack est facultatif et fournit les commandes applicatives ainsi que leur modèle.

init:
  system: ./packs/ubuntu
  pack: ./packs/environment-init
  name: configure
  arg: production

L’image correspondant à cette combinaison doit avoir été construite localement.

Commande de pack ou shell

Une initialisation peut appeler une commande déclarée par son pack :

init:
  pack: ./packs/environment-init
  name: generate-config
  arg: production

Elle peut aussi déclarer directement une action shell :

init:
  shell:
    cmd:
      - ./scripts/generate-config.sh

name et shell sont mutuellement exclusifs. Leur présence simultanée est rejetée à la validation afin d’éviter qu’un mode masque silencieusement l’autre.

Workspace

Le répertoire courant est monté dans le répertoire de travail du pack. Par défaut, le conteneur peut le modifier. Pour une initialisation qui ne fait que lire les sources ou la configuration, rendez ce montage non modifiable :

init:
  workspace:
    readonly: true
  shell:
    cmd: ["./scripts/check-config.sh"]

Une commande qui génère des fichiers dans le workspace nécessite évidemment le mode lecture-écriture par défaut.

Binds supplémentaires

La syntaxe historique associe un nom à un chemin source :

init:
  bind:
    config: ./config

Le contenu est disponible dans le modèle via {{ .xbee.bind.config }}. La forme structurée permet d’imposer la lecture seule :

init:
  bind:
    config:
      source: ./config
      readonly: true

Les binds déclarés à la racine de l’environnement et sous init.bind sont fusionnés. À nom identique, init.bind l’emporte. Ils alimentent le même modèle xbee.bind et sont partagés avec les conteneurs de l’environnement ; init.bind ne constitue donc pas un montage privé au seul conteneur d’initialisation.

Privilèges

Pour préserver la compatibilité avec les environnements existants, le conteneur est privilégié par défaut. Il est recommandé de désactiver ce mode dès que le bootstrap et l’action n’ont pas besoin de capabilities étendues :

init:
  privileged: false
  name: configure

privileged: false retire --privileged de la commande Docker. Le processus XBee du conteneur continue actuellement à être lancé avec l’utilisateur root.

Ports

port publie une correspondance Docker unique ou une liste :

init:
  port:
    - "8080:8080"
    - "127.0.0.1:9090:9090"

Avec expose-ports: true, XBee publie les ports exposés par les packs système et applicatif au lieu de lire port :

init:
  expose-ports: true

Le conteneur étant éphémère, ces publications ne durent que pendant l’initialisation.

Modèle et secrets

L’action s’exécute avec un hôte synthétique accessible sous xbee.host.init. Le modèle global de l’environnement et le modèle du pack restent disponibles lors de la résolution des templates.

Les secrets ne sont pas transmis en clair dans les arguments Docker. XBee crée une enveloppe chiffrée temporaire et remet sa clé par l’entrée standard. Lorsque l’action peut être résolue à l’avance, l’enveloppe ne contient que les secrets qu’elle référence. Si elle dépend de valeurs disponibles uniquement à l’exécution, le repli conservateur contient le modèle synthétique init/1, mais exclut les modèles des hôtes ordinaires.

Utilisez les mécanismes secret-env et secret-file des actions pour exposer un secret uniquement au processus qui en a besoin. Pour le fonctionnement général, voir Gestion des secrets.

Exemple complet

schema-version: "1.0"

default:
  host:
    system: ./packs/ubuntu

init:
  pack: ./packs/environment-init
  name: generate-config
  arg: production
  privileged: false
  workspace:
    readonly: false
  bind:
    inputs:
      source: ./config/inputs
      readonly: true

host:
  application:
    pack: ./packs/application

Ici, generate-config s’exécute localement avant l’hôte application. Il peut écrire dans le workspace, mais ne peut pas modifier ./config/inputs.