bogdan Analizeaza timpi reboot si documente

f16725e 3 months ago History

# Madagascar Cluster Projects

Acest director este punctul unic de lucru pentru proiectele cluster-level actuale si viitoare.

## Baza de referinta

Workflow-ul de install, uninstall si reinstall documentat aici este bazat pe implementarea cea mai completa existenta in `autoNAS`.

Referinte principale:
- `cluster/projects/autoNAS/README.md`
- `cluster/projects/autoNAS/DEVELOPMENT.md`
- `cluster/projects/autoNAS/scripts/install.sh`
- `cluster/projects/autoNAS/scripts/autonas-uninstall.sh`

Observatie importanta:
- `autoNAS` confirma workflow-ul corect de uninstall-inainte-de-reinstall si curatare a fisierelor orfane
- `autoNAS` nu este inca aliniat complet la noua regula de locatie pentru comenzi operator-facing, deoarece instaleaza in prezent in `/usr/local/bin`
- pentru proiectele noi, regula ramane `/usr/local/sbin`; `autoNAS` trebuie tratat ca precedent functional pentru workflow, nu ca standard final de layout

## Namespace de organizatie

Pentru claritate si evitarea coliziunilor intre proiecte, toate locatiile standard trebuie namespaced cu identificatorul de organizatie:

- `xdev`

Regula generala este:
- folosim `<project-name>` pentru identitatea proiectului
- folosim `xdev` in calea de instalare pentru fisiere interne, configuratie, date si documentatie

## Reguli generale

- Toate proiectele noi se creeaza sub `cluster/projects/<project-name>`.
- Proiectele se deschid si se mentin din `cluster`, pentru a reduce divergenta intre workspace-uri si duplicarea documentatiei sau scripturilor.
- Fiecare proiect trebuie sa aiba cel putin:
  - `README.md`
  - script de instalare
  - script de dezinstalare
  - instructiuni de operare si upgrade

## Locatii well-known obligatorii

Instalarile trebuie sa foloseasca locatii predictibile si stabile:

- executabile si scripturi operator-facing: `/usr/local/sbin`
- binare sau scripturi interne ale proiectului: `/usr/local/lib/xdev/<project-name>`
- documentatie instalata pe host: `/usr/local/share/doc/xdev/<project-name>`
- fisiere de configurare persistente: `/etc/xdev/<project-name>`
- environment defaults: `/etc/default/xdev-<project-name>`
- unitati systemd: `/etc/systemd/system`
- stare persistenta si date operationale: `/var/lib/xdev/<project-name>`
- cache temporar: `/var/cache/xdev/<project-name>` daca este necesar
- loguri dedicate pe disc, daca proiectul chiar le scrie in fisier: `/var/log/xdev/<project-name>`

Regula practica:
- daca un operator trebuie sa ruleze comanda direct, ea merge in `/usr/local/sbin`
- daca fisierul este suport intern pentru proiect, el merge in `/usr/local/lib/xdev/<project-name>`
- daca fisierul este documentatie instalata local pentru host, el merge in `/usr/local/share/doc/xdev/<project-name>`
- daca fisierul reprezinta configuratie editabila, el merge in `/etc/xdev/<project-name>` sau `/etc/default/xdev-<project-name>`
- daca fisierul reprezinta stare, baza locala, lock, snapshot sau alta data operationala, el merge in `/var/lib/xdev/<project-name>`

## Locatia standard pentru scripturile de dezinstalare

Locatia standard canonica pentru scriptul de dezinstalare instalat pe host este:

- `/usr/local/lib/xdev/<project-name>/uninstall.sh`

Motivatie:
- uninstall-ul este in primul rand parte din mecanismul intern de lifecycle al proiectului
- trebuie sa poata fi apelat de installer pentru cleanup automat inainte de reinstall
- trebuie versionat impreuna cu restul fisierelor interne ale proiectului
- evita aglomerarea inutila a `/usr/local/sbin` cu scripturi care nu sunt folosite frecvent in operare zilnica

Regula de naming:
- scriptul canonic instalat pe host se numeste `uninstall.sh`
- directorul proiectului da contextul complet: `/usr/local/lib/xdev/<project-name>/uninstall.sh`

Expunere optionala pentru operator:
- daca vrem o comanda manuala simpla si predictibila, se poate instala un wrapper sau symlink in:
  - `/usr/local/sbin/xdev-<project-name>-uninstall`
- acest wrapper trebuie sa apeleze scriptul canonic din `/usr/local/lib/xdev/<project-name>/uninstall.sh`
- wrapperul din `/usr/local/sbin` este optional; scriptul canonic din `/usr/local/lib/xdev/<project-name>/` este obligatoriu

## Instalare si dezinstalare

- Orice instalare trebuie sa fie insotita de un script de dezinstalare livrat de acelasi proiect.
- Scriptul de dezinstalare instalat pe host trebuie sa existe la `/usr/local/lib/xdev/<project-name>/uninstall.sh`.
- Scriptul de dezinstalare trebuie sa elimine toate fisierele instalate de proiect:
  - executabile
  - fisiere din `/usr/local/lib/xdev/<project-name>`
  - documentatie din `/usr/local/share/doc/xdev/<project-name>`
  - unitati systemd
  - fisiere de configurare generate de proiect, daca sunt gestionate exclusiv de el, din `/etc/xdev/<project-name>` sau `/etc/default/xdev-<project-name>`
  - directoare de stare, date sau cache create de proiect, daca nu contin date care trebuie pastrate explicit, din `/var/lib/xdev/<project-name>` sau `/var/cache/xdev/<project-name>`
- Scopul este prevenirea fisierelor orfane si a reinstalarilor peste artefacte ramase din versiuni anterioare.

## Regula de reinstall

- Toate reinstalarile se fac numai dupa dezinstalare completa.
- Dezinstalarea se face numai cu scriptul original de uninstall al proiectului, nu prin stergeri manuale partiale.
- Fluxul obligatoriu este:

```text
uninstall -> verificare curatare -> install
```

- Nu se face reinstall direct peste o instalare existenta, chiar daca pare functionala.
- Daca scriptul de uninstall lipseste, instalarea proiectului este incompleta si trebuie corectata inainte de orice upgrade sau reinstall.

## Cerinte pentru proiectele noi

Fiecare proiect nou trebuie sa includa explicit:

1. un `install` care foloseste locatiile well-known
2. un `uninstall` care inverseaza complet instalarea
3. un `README.md` cu:
   - layout-ul fisierelor instalate
   - comenzile de instalare
   - comenzile de dezinstalare
   - pasii de reinstall
   - locatia uninstall-ului instalat pe host: `/usr/local/lib/xdev/<project-name>/uninstall.sh`
   - locatiile pentru configuratie, documentatie si date
4. daca exista systemd:
   - `daemon-reload` la install si uninstall
   - enable/disable/stop clar definite
   - la deployment, serviciile si timer-ele care trebuie sa ramana active se pornesc cu `systemctl enable --now`, nu doar cu `enable`

## Aplicare la proiectele existente

Proiectele deja mutate sub `cluster/projects/` trebuie aliniate progresiv la aceste reguli.

Prioritati:
- confirmarea unui script de uninstall pentru fiecare proiect
- standardizarea instalarii in `/usr/local/sbin` si `/usr/local/lib/xdev/<project-name>`
- eliminarea reinstalarilor facute peste fisiere existente

## Lectii confirmate in autoNAS

Problemele deja identificate si rezolvate in `autoNAS`, care trebuie considerate reguli pentru proiectele viitoare:

- reinstalarile peste versiuni vechi lasa fisiere orfane daca nu exista cleanup explicit
- instalarea trebuie sa poata rula cleanup de versiune anterioara inainte de install
- uninstaller-ul trebuie instalat pe host pentru a permite cleanup corect la upgrade sau reinstall
- uninstall-ul trebuie sa curete agresiv fisierele istorice ramase din versiuni mai vechi
- config-ul utilizatorului trebuie pastrat cand contine date reale, nu sters orbeste
- serviciile systemd trebuie oprite, dezactivate, sterse si urmate de `daemon-reload`
- la deployment, un serviciu necesar in productie nu trebuie lasat doar `enabled`; se foloseste `enable --now` pentru a evita deploy-uri cu servicii instalate dar nepornite
- unele resurse necesita cleanup manual explicit daca pot contine date operationale, de exemplu exports NFS sau mount points active

Fluxul validat de `autoNAS` este:

```text
detect previous install -> run original uninstall -> clean orphan files -> install new version -> preserve user data where required
```

## Regula operationala

Cand se modifica un proiect existent sau se adauga unul nou, se actualizeaza si documentatia proiectului astfel incat procedura de:

- install
- uninstall
- reinstall

sa fie explicita, repetabila si fara artefacte ramase pe host.

## Deploy cluster-wide

Pentru rollout final pe cluster nu facem deploy nod cu nod manual daca proiectul este destinat cluster-wide.

Regula practica este:
- fiecare proiect trebuie sa pastreze si varianta pe un singur nod pentru development si testing
- pentru rollout cluster-wide se foloseste orchestratorul comun din radacina:
  - `cluster/scripts/deploy-project.sh <project-name>`

Sursa de adevar pentru noduri:
- `cluster/cluster-context/madagascar.json`

Exemple:

```bash
./scripts/deploy-project.sh pve-guests-state
./scripts/deploy-project.sh pve-net-hang-watchdog
./scripts/deploy-project.sh pve-backup-scheduler
./scripts/deploy-project.sh autoNAS
./scripts/deploy-project.sh pve-guests-state install --node ebony
```

Cerinta pentru proiecte:
- proiectele noi trebuie sa ofere fie `setup.sh`, fie `deploy.sh`
- `setup.sh` ramane entrypoint-ul standard pentru install/uninstall pe un singur nod
- orchestratorul comun decide nodurile pe baza `cluster-context/madagascar.json` si ruleaza proiectul pe toate tintele selectate