Concepts

Environnements

Décrire plusieurs hôtes et coordonner leurs actions up / down / configure.

Un environnement (xbee-env.yaml) décrit un ensemble d’hôtes, chacun porteur d’un système et d’un ensemble de packs. L’EnvironmentGraph résout les providers et coordonne le provisioning à travers ces hôtes.

Structure de premier niveau

default:
  host:
    system:
  volume:

host:

• default porte les valeurs par défaut (système, réseau, volumes) appliquées à tout hôte.
• host déclare les hôtes eux-mêmes, par clé.

Un hôte peut être répété à l’identique (« castle ») via count :

host:
  a:
    count: 2

Chaque hôte compte alors count instances, adressables individuellement via <clé>1 … <clé>N dans les directives up/down/configure (voir plus bas).

Pack applicatif d’un hôte

Chaque hôte référence, via pack, le pack applicatif qui y est installé — un Id, sous forme abrégée (l’origine seule) ou complète :

host:
  a:
    pack: ./hello

host:
  a:
    pack:
      origin: ./hello
      var:
        greeting: "Bonjour depuis l'environnement !"

var, sur ce pack, surcharge le modèle de données du pack référencé — le même principe que la surcharge d’une dépendance de pack à pack. C’est ce pack dont les actions up, down, configure et command sont invoquées sur l’hôte — voir les directives UDC ci-dessous.

Les directives UDC — Up / Down / Configure

configure, up, down (et les sections operate.<name>) décrivent, pour chaque hôte, une commande de pack ou une commande shell à exécuter. Elles acceptent plusieurs raccourcis syntaxiques, tous normalisés vers une forme canonique interne.

Directive absente. Si up (ou down/configure) n’apparaît pas du tout, xbee génère le comportement par défaut : exécuter la directive de même nom sur tous les hôtes, en parallèle. operate.* n’a pas de comportement par défaut.

Chaîne unique. Si la section entière est une chaîne, c’est une commande shell exécutée sur l’unique hôte de l’environnement (erreur s’il y en a plusieurs) :

up: "echo hello"

Référence d’hôte nue. Un élément de séquence qui est une simple chaîne désigne un hôte (clé ou alias) sur lequel exécuter l’action par défaut ; une liste séparée par des virgules exécute sur plusieurs hôtes en parallèle :

up:
  - config1
  - tosiam1,tosiam2

Hôte avec action explicite. Un élément de séquence qui est une map à une clé associe une référence d’hôte à un payload :

configure:
  - tosiam1.tosit.org:
      name: configure
      args:
        - "{{ .xbee.templates }}/config.properties"
      env: JAVA_TOOL_OPTIONS=-Djavax.net.ssl.trustStore=/instance/cacerts

Parallélisme explicite. xbee.parallel regroupe plusieurs éléments ; si la valeur est une chaîne d’hôtes séparés par des virgules, les clés voisines (name, args, env, …) forment un payload partagé, cloné sur chaque hôte :

configure:
  - xbee.parallel: tosiam1,tosiam2
    name: add_config_store
    arg: config2.tosit.org

Directive globale. Une map dont l’unique clé est xbee (ex. - xbee: restart) est conservée telle quelle, sans hôte associé.

Payload

Le payload associé à un hôte est soit une chaîne (raccourci pour une commande shell), soit une map contenant au moins une clé sélectrice d’action :

Résolution d’hôte

Une référence d’hôte est résolue dans l’ordre : correspondance exacte avec une clé de host:, puis avec un alias, puis en découpant un suffixe numérique (tosiam2 → préfixe tosiam + index 2) si le préfixe correspond à l’alias — ou au premier segment de la clé — d’un hôte déclaré avec count. count vaut 1 par défaut, donc en pratique la plupart des environnements n’utilisent que les deux premières règles.

Volumes

xbee sépare la définition d’un volume de son usage par un hôte.

Au niveau racine de l’environnement, volume déclare les volumes nommés, avec leur taille et les options spécifiques au provider (voir Providers & volumes) :

volume:
  data1:
    size: 10
    provider:
      # options spécifiques au provider choisi

Une valeur entière (data1: 10) est un raccourci pour {size: 10}.

Chaque hôte déclare ensuite, dans sa propre section volume, les volumes qu’il utilise :

host:
  a:
    volume:
      data1: /mnt/data
      data2:
        - /a/c
        - packB.vol3   # référence packB.<nom> déclaré par un pack dépendant

La valeur associée à chaque volume est un chemin, une liste de chemins, ou une référence <alias-pack>.<nom> vers un volume déclaré par un pack dépendant. En l’état actuel de xbee, cette valeur est analysée mais pas encore utilisée pour choisir le point de montage : côté VM, un volume attaché est systématiquement partitionné (GPT), formaté en ext4, et monté sur /mnt/xbee/<nom-du-volume> — seul le nom du volume (la clé) compte pour l’instant.

Un volume n’est jamais détruit par xbee delete : il survit à la suppression de l’instance qui l’utilise, et doit être supprimé explicitement via xbee admin delete volume <nom>.