first commit
This commit is contained in:
julien
277
ARCHITECTURE.md
Normal file
277
ARCHITECTURE.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user