homelab_automation/documentation/STORAGE_DETAILS.md

Stockage Détaillé - Documentation Technique

Vue d'ensemble

La fonctionnalité "Stockage Détaillé" fournit une vue complète et normalisée des informations de stockage pour tous les hôtes, avec support multi-OS (Linux Alpine/Debian, TrueNAS CORE, TrueNAS SCALE).

Architecture

Backend

app/
├── models/host_metrics.py      # Colonne storage_details (JSON)
├── schemas/host_metrics.py     # Schéma Pydantic avec storage_details
├── services/builtin_playbooks.py  # Définition du builtin playbook
└── routes/builtin_playbooks.py    # API endpoints

ansible/playbooks/builtin/
└── _builtin_collect_storage_details.yml  # Playbook de collecte

Frontend

app/
└── main.js
    ├── renderStorageDetailsSection()  # Rendu de l'accordion
    ├── toggleStorageDetails()         # Toggle accordion
    └── toggleStorageInspector()       # Toggle mode inspecteur

Schéma de Données

StorageDetails v1

{
  "os_type": "linux-debian|linux-alpine|truenas-core|truenas-scale|linux-generic",
  "status": "ok|partial|error",
  "collected_at": "2025-12-19T10:00:00Z",
  "commands_run": [
    {"cmd": "lsblk", "status": "ok"},
    {"cmd": "df", "status": "ok"}
  ],
  "partial_failures": [],
  "summary": {
    "total_bytes": 500107862016,
    "used_bytes": 125026965504,
    "free_bytes": 349600112640,
    "used_pct": 25.0
  },
  "block_devices": [...],
  "mounts": [...],
  "filesystems": [...],
  "lvm": {
    "pvs": [...],
    "vgs": [...],
    "lvs": [...]
  },
  "zfs": {
    "pools": [...],
    "datasets": [...]
  },
  "feature_flags": {
    "has_lvm": false,
    "has_zfs": false,
    "has_lsblk": true,
    "has_findmnt": true
  }
}

Commandes par OS

Linux (Alpine/Debian)

Commande	Description	Fallback
lsblk -J -b -o ...	Block devices avec JSON	Options réduites
findmnt -J -b	Points de montage fiables	df seul
df -B1 -PT	Filesystems usage	Toujours disponible
pvs/vgs/lvs --reportformat json	LVM info	Ignoré si absent

TrueNAS CORE (FreeBSD)

Commande	Description	Notes
df -k -T	Filesystems	Conversion bytes nécessaire
zpool list -H -p	ZFS pools	Parsable output
zfs list -H -p	ZFS datasets	Avec bytes

TrueNAS SCALE (Linux + ZFS)

Combine les commandes Linux + ZFS.

Interface Utilisateur

Accordion "Stockage détaillé"

L'accordion est replié par défaut et affiche un résumé compact :

[icon] Stockage détaillé [OK] [4 FS] [ZFS] 25% utilisé • 116 GB / 465 GB [i] [v]

Éléments :

• Icône : fa-database (indigo)
• Badge statut : OK (vert), Partiel (jaune), Erreur (rouge)
• Chips : Nombre de filesystems, ZFS, LVM si présents
• Résumé : % utilisé et tailles
• Bouton inspecteur : fa-info-circle
• Chevron : expand/collapse

Contenu de l'accordion

1. Table Filesystems :

   • Colonnes : Mount, Device, FS, Taille, Utilisé, %
   • Seuils de warning : 75% jaune, 90% rouge
   • Fond rouge léger pour partitions > 85%

2. Section ZFS (si présent) :

   • Pools avec santé (ONLINE/DEGRADED/FAULTED)
   • Barre de progression usage
   • Liste des datasets

3. Section LVM (si présent) :

   • Volume Groups avec taille/free
   • Liste des LVs

Mode Inspecteur

Drawer affichant les métadonnées de collecte :

• OS détecté
• Timestamp de collecte
• Statut de collecte
• Liste des commandes exécutées avec statut
• Avertissements (partial failures)

API Endpoints

Exécuter la collecte

POST /api/builtin-playbooks/execute
Content-Type: application/json

{
  "builtin_id": "collect_storage_details",
  "target": "hostname"
}

Collecte sur tous les hôtes

POST /api/builtin-playbooks/collect-all

Migration Base de Données

Migration 0016_add_storage_details_column.py :

def upgrade():
    op.add_column('host_metrics', 
        sa.Column('storage_details', sa.JSON(), nullable=True))

Tests

Backend

pytest tests/backend/test_storage_details.py -v

Couverture :

• Validation schéma
• Parsing données par OS
• Feature flags
• Seuils de warning
• Métadonnées de collecte

Frontend

npm run test -- tests/frontend/storage_details.test.js

Couverture :

• Rendu accordion
• Table filesystems avec warnings
• Sections ZFS/LVM
• Mode inspecteur
• Formatage bytes

Checklist de Validation

• Section "Stockage détaillé" visible sur un host (repliée par défaut)
• Summary correct (chips, usage, tailles)
• Linux : filesystems/mounts affichés correctement
• TrueNAS CORE : df + ZFS pools/datasets affichés
• TrueNAS SCALE : Linux + ZFS affichés
• LVM affiché si présent
• Seuils de warning appliqués (75% jaune, 90% rouge)
• Mode inspecteur affiche les commandes et statuts
• Gestion gracieuse des erreurs partielles
• Données collectées dans le même run que les autres métriques

Compatibilité

Commandes Manquantes

OS	Commande	Comportement
Alpine	findmnt	Fallback df seul, status=partial
FreeBSD	lsblk	Non utilisé, block_devices=[]
Tout	LVM	Ignoré si absent
Tout	ZFS	Ignoré si absent

Fallbacks

1. Si lsblk -J -O -b échoue → essai avec options réduites
2. Si findmnt -J échoue → utilise df seul
3. Si LVM absent → lvm_info vide, pas d'erreur
4. Si ZFS absent → zfs vide, pas d'erreur

Performance

• Timeouts implicites via Ansible (task timeout)
• Commandes légères (lecture seule)
• Pas d'opérations bloquantes
• Collecte parallèle multi-hôtes possible

Sécurité

• Toutes les commandes sont en lecture seule
• Pas de commandes destructives
• Pas d'exposition de données sensibles (mots de passe, clés)
• Les serial numbers de disques sont optionnels