114 lines
4.8 KiB
Markdown
114 lines
4.8 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
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.
|
|
|
|
notification: # la chaîne d'alerte livrée avec le pack
|
|
perimetre: RabbitMQ
|
|
calendrier: 24x7 # 24x7 et Heures-Ouvrees sont reconnus
|
|
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`.
|
|
- **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 — `24x7`, `workhours`, `nonworkhours`, `none` — sont référencés, jamais recréés.
|
|
- **`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
|
|
|
|
```bash
|
|
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](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`.
|