Concepts

Actions

Les actions typées exécutées dans un container ou une VM pendant le provisioning.

Les actions (xbee/actions/) sont des unités typées et exécutables, invoquées à l’intérieur d’un container ou d’une VM pendant le provisioning. Une directive up, down ou configure réduite à une chaîne est un raccourci vers une action shell.

Action Shell

Une action shell accepte une commande, une liste de variables ordinaires et deux modes d’injection temporaire pour les secrets :

shell:
  cmd:
    - deploy --key-file "$TLS_KEY"
  secret-env:
    API_TOKEN: "{{ .api.token }}"
    TLS_KEY: /run/xbee-secrets/private-key.pem
  secret-file:
    - content: "{{ .tls.privateKey }}"
      to: /run/xbee-secrets/private-key.pem
      mode: "0400"

secret-env expose les valeurs uniquement pendant la commande, au moyen d’un fichier d’environnement temporaire en 0600. secret-file crée chaque cible de manière exclusive : xbee refuse d’écraser un fichier existant. Les modes donnant des droits au groupe ou aux autres utilisateurs sont refusés. Les fichiers et l’environnement temporaires sont supprimés après l’exécution, y compris lorsqu’elle échoue.

Une interpolation directe du secret dans cmd est refusée, car elle pourrait exposer la valeur dans la liste des processus ou dans un message d’erreur. Pour la même raison, xbee refuse de rendre un secret directement dans un fichier de template : utilisez secret-file pour matérialiser ce contenu uniquement pendant l’action qui le consomme.

Action Url

url:
  from:
  topath:
  todir:
  unpack:

from définit l’URL elle-même. La ressource n’est téléchargée que si elle n’est pas déjà présente dans le cache (~/.xbee/cache-artefacts par défaut) :

1. Si la ressource est dans le cache, pas de téléchargement ; sinon elle est téléchargée vers le cache.
2. topath et todir sont mutuellement exclusifs. todir a une valeur par défaut si ni l’un ni l’autre n’est renseigné. unpack vaut true par défaut avec todir, et false par défaut avec topath.

url: http://toto.com/toto.tar.gz

récupère toto.tar.gz et le dépaquette dans /opt. Si todir est renseigné, l’artefact y est dépaqueté (ou copié tel quel) ; si topath est renseigné, l’artefact est copié sous ce nom, et dépaqueté dans le répertoire parent si unpack est vrai.

Action Env

La section env d’un pack expose des variables d’environnement dans le descripteur du container (pour une VM, elles doivent être accessibles à tout utilisateur). L’action env d’une directive provision, elle, peut être attribuée à un utilisateur spécifique et n’apparaît pas dans le descripteur du container.

Action Systempath

systempath: /opt/apache-maven-3.9.9/bin

ajoute un ou plusieurs répertoires au PATH du container ou de la VM — réduit à une chaîne pour un seul répertoire, à une liste (path: [...]) pour plusieurs. owner restreint l’effet à un utilisateur donné ; sans lui, tous les utilisateurs en bénéficient.

Action Pkg

pkg:
  name: openjdk-21-jdk

installe un ou plusieurs paquets (name, chaîne ou liste) via le gestionnaire du système sous-jacent — apt ou yum selon la distribution, sans que le pack ait à s’en soucier. update: true rafraîchit l’index des paquets avant l’installation ; remove: true les retire au lieu de les installer ; builddep: true installe leurs dépendances de build plutôt que les paquets eux-mêmes.

Secrets pour les actions réseau

Les identifiants nécessaires aux actions url ou git peuvent être fournis via un fichier credentials.yml, placé dans le répertoire .xbee d’une abstraction ou dans celui de l’utilisateur :

- key:
  user:
  password:

key correspond à une URL complète ou à un host ; l’ancien nom name reste accepté. Lorsque plusieurs entrées correspondent, le préfixe le plus précis est retenu. Xbee force les permissions du fichier à 0600, signale un YAML invalide et masque le mot de passe dans ses logs.

NamedPayload

Au niveau d’un pack, les sections up, down, configure et command produisent chacune un NamedPayload — NP.Name valant up/down/configure/command, et NP.Payload un Shell ou une Command. Au niveau d’un environnement, un NamedPayload peut référencer soit un shell direct, soit l’une de ces sections d’un pack.