278 lines
6.6 KiB
Markdown
278 lines
6.6 KiB
Markdown
# Architecture NETbian
|
|
|
|
Ce document decrit l'architecture actuelle de NETbian et le pipeline d'execution du provisioning.
|
|
|
|
## Vue d'ensemble
|
|
|
|
NETbian repose sur une architecture **profiles + roles**.
|
|
|
|
```text
|
|
profile -> liste ordonnee de roles
|
|
role -> implementation technique autonome
|
|
```
|
|
|
|
Un profil ne contient que de la composition. Toute la logique technique est portee par les roles et par les fonctions partagees de `lib.sh`.
|
|
|
|
## Arborescence
|
|
|
|
```text
|
|
netbian/
|
|
├── run.sh
|
|
├── roles.sh
|
|
├── lib.sh
|
|
├── profiles/
|
|
│ ├── cli.sh
|
|
│ ├── desktop.sh
|
|
│ ├── devel.sh
|
|
│ └── server.sh
|
|
├── roles/
|
|
│ ├── base/
|
|
│ ├── codium/
|
|
│ ├── desktop/
|
|
│ ├── devel/
|
|
│ ├── docker/
|
|
│ ├── firewall/
|
|
│ ├── server/
|
|
│ └── zram/
|
|
└── config/
|
|
```
|
|
|
|
## Profils
|
|
|
|
Chaque profil est un script shell qui declare `ROLE_ORDER`.
|
|
|
|
Exemple avec `profiles/devel.sh` :
|
|
|
|
```bash
|
|
ROLE_ORDER=(base desktop firewall zram docker codium devel)
|
|
```
|
|
|
|
Profils fournis :
|
|
|
|
- `cli` -> `base zram`
|
|
- `server` -> `base firewall server zram docker`
|
|
- `desktop` -> `base desktop firewall zram`
|
|
- `devel` -> `base desktop firewall zram docker codium devel`
|
|
|
|
## Contrat d'un role
|
|
|
|
Un role est un repertoire sous `roles/<nom>/`.
|
|
|
|
Fichiers reconnus par le moteur :
|
|
|
|
- `repo.sh`
|
|
- `packages.list`
|
|
- `install.sh`
|
|
- `config.sh`
|
|
- `run.sh`
|
|
- `l10n.packages`
|
|
- `rules.<suffix>.list`
|
|
|
|
Tout autre fichier est rejete par `validate_role()` pour eviter les derives silencieuses.
|
|
|
|
## Pipeline global
|
|
|
|
### 1. `run.sh`
|
|
|
|
`run.sh` est le point d'entree. Il :
|
|
|
|
1. initialise l'environnement (`PROJECT_DIR`, `ROLE_DIR`, `PROFILE_DIR`)
|
|
2. charge `lib.sh` et active `set -Eeuo pipefail`
|
|
3. parse les options CLI
|
|
4. peut lister les profils et roles disponibles
|
|
5. verifie les prerequis (`root`, Debian 13, reseau HTTP)
|
|
6. valide puis lit / met a jour le fichier de configuration
|
|
7. exporte `CONFIG_FILE`
|
|
8. execute `roles.sh`
|
|
|
|
### 2. `roles.sh`
|
|
|
|
`roles.sh` :
|
|
|
|
1. charge `lib.sh`
|
|
2. valide `CONFIG_FILE`
|
|
3. lit `CONFIG_FILE`
|
|
4. recupere `profile`
|
|
5. source `profiles/<profile>.sh`
|
|
6. valide la definition du profil et les roles references
|
|
7. execute `run_role` pour chaque role dans l'ordre
|
|
8. imprime un resume d'execution en sortie
|
|
|
|
## Resolution de configuration
|
|
|
|
Ordre de priorite :
|
|
|
|
1. options CLI
|
|
2. variables d'environnement `NETBIAN_*`
|
|
3. fichier de configuration cible
|
|
|
|
Variables gerees :
|
|
|
|
- `profile`
|
|
- `lang`
|
|
- `CONFIG_FILE` (transportee par l'environnement entre `run.sh` et `roles.sh`)
|
|
|
|
`validate_config_file()` refuse les lignes invalides et controle les formats de `profile` et `lang` avant sourcing.
|
|
|
|
## Pipeline d'un role
|
|
|
|
Le moteur execute les etapes suivantes dans cet ordre :
|
|
|
|
1. `repo.sh`
|
|
2. `packages.list`
|
|
3. `install.sh`
|
|
4. `config.sh`
|
|
5. `run.sh`
|
|
|
|
Toutes les etapes sont optionnelles.
|
|
|
|
Implementation logique de `run_role()` :
|
|
|
|
```text
|
|
validate_role
|
|
run_role_script repo.sh
|
|
load_role_packages
|
|
append_localized_packages
|
|
run_role_packages
|
|
run_role_script install.sh
|
|
run_role_script config.sh
|
|
run_role_script run.sh
|
|
```
|
|
|
|
Les erreurs sont propagees explicitement avec `|| return 1` pour eviter de dependre uniquement du comportement implicite de `set -e`.
|
|
|
|
## Gestion des paquets
|
|
|
|
- `load_role_packages()` charge `roles/<role>/packages.list`
|
|
- `append_localized_packages()` enrichit la liste avec les paquets localises definis dans `roles/base/l10n.packages`
|
|
- la langue utilisee provient de la configuration active (`lang`)
|
|
- `run_role_packages()` appelle `ensure_packages_installed()`
|
|
|
|
Si un role n'a aucun paquet a installer, le moteur enregistre un `[SKIP]` sur `role/packages.list`.
|
|
|
|
## Configuration et copie de fichiers
|
|
|
|
`copy_config()` copie les fichiers depuis `config/` vers leur destination finale :
|
|
|
|
- propriete `root:root` pour les fichiers systeme
|
|
- propriete utilisateur si la destination est sous `/home/<user>/`
|
|
- ecriture idempotente si le contenu est identique
|
|
|
|
`write_if_changed()` et `write_text_file_if_changed()` centralisent les ecritures atomiques simples.
|
|
|
|
## Firewall declaratif
|
|
|
|
Le role `firewall` utilise un systeme declaratif base sur des listes de regles :
|
|
|
|
```text
|
|
roles/firewall/
|
|
├── rules.common.list
|
|
├── rules.desktop.list
|
|
├── rules.devel.list
|
|
└── rules.server.list
|
|
```
|
|
|
|
Ordre d'application :
|
|
|
|
1. initialisation UFW
|
|
2. regles communes
|
|
3. regles specifiques au profil
|
|
|
|
Chaque ligne correspond a une regle passee a `ufw allow`.
|
|
|
|
Exemple :
|
|
|
|
```text
|
|
# rules.common.list
|
|
ssh
|
|
|
|
# rules.server.list
|
|
http
|
|
https
|
|
imap
|
|
imaps
|
|
smtp
|
|
submissions
|
|
```
|
|
|
|
Le modele est volontairement unique : les ouvertures UFW sont centralisees dans les fichiers `rules.*.list`, pas dans les autres roles.
|
|
|
|
## Services systeme
|
|
|
|
`restart_service_if_present()` permet de redemarrer un service uniquement s'il existe. Cela evite de rendre certains roles fragiles sur des machines ou le service n'est pas installe.
|
|
|
|
Le role `server` s'appuie sur ce mecanisme apres ecriture de la configuration SSH.
|
|
|
|
## Logs et resume d'execution
|
|
|
|
Le moteur expose les helpers suivants :
|
|
|
|
- `log_run`
|
|
- `log_ok`
|
|
- `log_skip`
|
|
- `log_info`
|
|
- `log_warn`
|
|
|
|
Tags utilises par l'orchestrateur :
|
|
|
|
- `[RUN]`
|
|
- `[OK]`
|
|
- `[SKIP]`
|
|
- `[INFO]`
|
|
- `[WARN]`
|
|
|
|
Des tableaux runtime suivent les etapes et roles executes, ignores ou en echec :
|
|
|
|
- `EXECUTED_STEPS`
|
|
- `SKIPPED_STEPS`
|
|
- `FAILED_STEPS`
|
|
- `EXECUTED_ROLES`
|
|
|
|
Le resume est imprime par `print_execution_summary()` via un `trap EXIT` dans `roles.sh`.
|
|
|
|
## Decouverte et validation
|
|
|
|
Lister les profils :
|
|
|
|
```bash
|
|
./run.sh --list-profiles
|
|
```
|
|
|
|
Lister les roles :
|
|
|
|
```bash
|
|
./run.sh --list-roles
|
|
```
|
|
|
|
Validation minimale recommandee :
|
|
|
|
```bash
|
|
bash -n run.sh roles.sh lib.sh roles/*/*.sh profiles/*.sh
|
|
./run.sh --list-profiles
|
|
./run.sh --list-roles
|
|
```
|
|
|
|
Validation recommandee avant production :
|
|
|
|
1. machine Debian 13 fraiche
|
|
2. test de chaque profil
|
|
3. verification des services systemd critiques (`ssh`, `docker`, `zramswap`)
|
|
4. verification UFW apres run
|
|
5. rerun complet pour confirmer l'idempotence
|
|
|
|
## Principes de conception
|
|
|
|
- **Idempotence** : rejouer un role ne doit pas deteriorer l'etat.
|
|
- **Composition simple** : les profils ne font qu'ordonner des roles.
|
|
- **Validation stricte** : les roles, manifests et fichiers de configuration sont verifies avant execution.
|
|
- **Ecritures limitees** : seules les differences utiles sont ecrites.
|
|
- **Previsibilite** : les comportements critiques sont centralises dans `lib.sh`.
|
|
- **Source de verite unique** : un seul mecanisme par sujet critique (ex. firewall).
|
|
|
|
|
|
## Resume d execution
|
|
|
|
- `Steps executed` compte les etapes ayant effectue une action.
|
|
- `Steps skipped` compte les etapes entierement conformes ou sautees par l'orchestrateur.
|
|
- `Skip events` compte tous les messages `[SKIP]` emis pendant l'execution.
|