Enclume/CONTRIBUTING.md

Contribuer à Enclume

Deux formes de contribution, très différentes par leur difficulté.

Proposer un pack — le plus utile

Un pack décrit une technologie : un modèle d'hôte et ses sondes. C'est ce qui fait la valeur d'Enclume, et c'est accessible à quiconque supervise cette technologie au quotidien.

Depuis le site, bouton « Proposer un pack » : collez votre YAML, il est vérifié immédiatement, et une demande de fusion est ouverte après relecture.

Par pull request, si vous préférez : un fichier dans catalog/<catégorie>/<id>.yml.

Le format

id: app-rabbitmq              # minuscules, chiffres et tirets
name: RabbitMQ                # nom lisible, affiché dans le catalogue
category: applications        # une des catégories ci-dessous
status: to-verify             # verified seulement si éprouvé sur un central réel
plugin: centreon_rabbitmq_restapi.pl
description: Supervision d'un broker RabbitMQ via son API de management.

host_template:
  name: App-RabbitMQ-custom   # <Famille>-<Techno>-custom
  alias: Applicatif RabbitMQ
  parents: [generic-active-host-custom]
  macros:
    - {name: RABBITPORT, value: "15672", description: "Port de l'API"}
    - {name: RABBITPASSWORD, value: "", description: "Mot de passe", is_password: true}

prerequis:                    # facultatif mais précieux
  paquets:
    debian: [libwww-perl]
    rhel: [perl-libwww-perl]
  notes: |
    Activer le plugin de management et créer un compte en lecture seule.

groupe_hote:                  # le groupe dans lequel ranger les hôtes
  name: HG-App-RabbitMQ
  alias: RabbitMQ

notification:                 # la chaîne d'alerte livrée avec le pack
  perimetre: RabbitMQ
  calendrier:                 # le pack apporte le sien, il ne réutilise pas celui du central
    name: TP-App-RabbitMQ-24x7
    modele: 24x7              # 24x7 ou Heures-Ouvrees : le rythme copié
    alias: RabbitMQ, en permanence
  groupe: CG-App-RabbitMQ     # CG-<Famille>-<Techno>
  criticite: Majeure
  impact: "Échanges entre applications interrompus"
  options_hote: d,u,r
  options_service: w,c,r
  intervalle: 30

services:
  - name: Queues              # donnera le modèle App-RabbitMQ-Queues
    alias: Queues
    description: Messages en attente dans les files
    default: true             # false pour une sonde décochée par défaut
    line: "$CENTREONPLUGINS$/centreon_rabbitmq_restapi.pl --plugin=… --mode=queues …"
    macros:
      - {name: WARNING, value: "1000", description: "Seuil warning"}

Les catégories

Ce sont celles des connecteurs de supervision Centreon, pour qu'un pack se range là où on ira le chercher dans la documentation officielle :

operating-system, network, hardware-server, storage, database, applications, virtualization, protocol, ups-pdu, printer, sensor, cloud, toip-voip, blockchain, centreon.

Le fichier se dépose dans catalog/<catégorie>/<id>.yml, et le champ category porte la même valeur.

Les règles

• Pas de point-virgule dans une ligne de commande : c'est le séparateur CLAPI, il casserait le fichier d'import.
• Les seuils en macros $_SERVICEXXX$, jamais en dur. C'est tout l'intérêt d'un modèle.
• Ce qui est commun à l'hôte va sur l'hôte : ports, comptes, options du plugin. Ce qui est propre à une sonde va sur la sonde : seuils, filtres.
• Aucun mot de passe réel. Valeur vide et is_password: true.
• Un groupe d'hôtes. Nommé HG-<Famille>-<Techno>. Un hôte sans groupe devient introuvable dès que le parc grandit, et les droits comme les filtres s'appuient dessus.
• Une chaîne de notification. Un pack qui supervise sans prévenir personne n'a pas d'intérêt : calendrier, groupe et impact sont attendus. Choisissez 24x7 pour ce dont la panne réveille quelqu'un, Heures-Ouvrees sinon. Les calendriers livrés par Centreon. Chaque pack apporte son propre calendrier, nommé TP-<Famille>-<Techno>-<rythme> : ajuster les plages d'une technologie ne doit pas modifier celles de tout le central.
• status: verified uniquement si vous avez exécuté ces commandes sur un Centreon. Sinon to-verify, c'est honnête et c'est utile.
• $CENTREONPLUGINS$ est remplacé par le répertoire de plugins choisi par l'utilisateur.

Le plus précieux

Vérifier un pack existant marqué to-verify vaut autant qu'en écrire un nouveau. Un --list-mode sur le plugin concerné, une exécution réelle, et le passage en verified : c'est ce qui rend le catalogue fiable.

Contribuer au code

python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt pytest ruff
python -m pytest -q
sh tests/interface.sh

Avant toute proposition, la revue décrite dans docs/CONVENTIONS.md : ruff check, la suite de tests, le test d'interface. Les conventions de nommage y sont aussi.

Une règle traverse tout le projet : le serveur n'exécute jamais rien. Ni CLAPI, ni prérequis, ni contribution. Il écrit des fichiers que l'utilisateur relit avant de les jouer. Toute proposition qui s'en écarte sera refusée, quel que soit son intérêt.

Signaler un problème

Un pack dont le CLAPI généré ne passe pas sur votre central est un signalement de première importance : indiquez la version de Centreon, le pack, et le message d'erreur de centreon.