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:

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:

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:

./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