homelab_automation/RESUME_FILTRAGE_PLAYBOOKS.md

Résumé : Filtrage des Playbooks par Host/Group

✅ Implémentation Complétée

Le système de filtrage des playbooks basé sur le champ hosts a été entièrement implémenté et testé.

🎯 Objectif

Assurer que seuls les playbooks compatibles avec un hôte ou groupe spécifique peuvent être exécutés, en se basant sur le champ hosts défini dans chaque playbook Ansible.

📋 Exemple Concret

Playbook backup-proxmox-config.yml

---
- name: Backup Serveurs Proxmox Configuration files
  hosts: role_proxmox  # ← Restriction au groupe role_proxmox
  become: true
  # ...

Résultat :

• ✅ Peut être exécuté sur :

  • Groupe role_proxmox
  • Hôtes membres : ali2v.xeon.home, hp.nas.home, hp2.i7.home, etc.

• ❌ Ne peut PAS être exécuté sur :

  • Hôte raspi.4gb.home (membre de role_sbc, pas de role_proxmox)
  • Groupe env_homelab (contient des hôtes hors de role_proxmox)

🔧 Modifications Apportées

1. Extraction du Champ hosts

Fichier : app/app_optimized.py

La méthode AnsibleService.get_playbooks() extrait maintenant le champ hosts de chaque playbook :

playbook_info = {
    "name": pb.stem,
    "filename": pb.name,
    "hosts": "all",  # Valeur par défaut
    "category": "general",
    "subcategory": "other",
    # ...
}

# Lecture du champ 'hosts' depuis le YAML
if 'hosts' in play:
    playbook_info['hosts'] = play['hosts']

2. Fonction de Compatibilité

Nouvelle méthode : is_target_compatible_with_playbook(target, playbook_hosts)

Vérifie la compatibilité selon les règles :

• hosts: all → compatible avec tout
• hosts: role_proxmox → compatible avec le groupe et ses hôtes
• hosts: server.home → compatible uniquement avec cet hôte

3. Filtrage des Playbooks

Nouvelle méthode : get_compatible_playbooks(target)

Retourne uniquement les playbooks compatibles avec une cible donnée.

4. Endpoint de Listing Amélioré

Endpoint : GET /api/ansible/playbooks?target={host_ou_groupe}

# Sans filtre - tous les playbooks
curl http://localhost:8000/api/ansible/playbooks

# Avec filtre - seulement les playbooks compatibles avec role_proxmox
curl http://localhost:8000/api/ansible/playbooks?target=role_proxmox

5. Validation à l'Exécution

Endpoint : POST /api/ansible/execute

Validation automatique avant l'exécution :

{
  "playbook": "backup-proxmox-config.yml",
  "target": "raspi.4gb.home"  // ❌ Erreur 400 - incompatible
}

Message d'erreur :

Le playbook 'backup-proxmox-config.yml' (hosts: role_proxmox) 
n'est pas compatible avec la cible 'raspi.4gb.home'. 
Ce playbook ne peut être exécuté que sur: role_proxmox

6. Validation des Schedules

Endpoint : POST /api/schedules

Même validation lors de la création de tâches planifiées.

🧪 Tests

Script de test : test_playbook_filtering.py

python test_playbook_filtering.py

Résultats :

✓ PASS | Playbook Proxmox sur groupe role_proxmox
✓ PASS | Playbook Proxmox sur hôte du groupe role_proxmox
✓ PASS | Playbook Proxmox sur hôte hors groupe role_proxmox
✓ PASS | Playbook Proxmox sur groupe env_homelab
✓ PASS | Playbook 'all' sur groupe all
✓ PASS | Playbook 'all' sur n'importe quel groupe
✓ PASS | Playbook 'all' sur n'importe quel hôte
✓ PASS | Playbook 'all' sur hôte quelconque

Tests terminés! (8/8 réussis)

📊 Inventaire Actuel

Groupes et Hôtes

Groupe role_proxmox :

• ali2v.xeon.home
• hp.nas.home
• hp2.i7.home
• hp3.i5.home
• mimi.pc.home

Groupe role_sbc :

• orangepi.pc.home
• raspi.4gb.home
• raspi.8gb.home

Playbooks

Playbook	Champ hosts	Description
backup-proxmox-config.yml	role_proxmox	Backup configuration Proxmox
bootstrap-host.yml	all	Bootstrap initial d'un hôte
health-check.yml	all	Vérification de santé
vm-upgrade.yml	all	Mise à jour des packages
vm-reboot.yml	all	Redémarrage

🎨 Utilisation dans l'Interface

Scénario 1 : Sélection d'un Hôte Proxmox

1. Utilisateur sélectionne ali2v.xeon.home
2. Interface appelle : GET /api/ansible/playbooks?target=ali2v.xeon.home
3. Playbooks affichés :
   • ✅ backup-proxmox-config.yml (compatible via role_proxmox)
   • ✅ health-check.yml (compatible via all)
   • ✅ vm-upgrade.yml (compatible via all)
   • etc.

Scénario 2 : Sélection d'un Hôte SBC

1. Utilisateur sélectionne raspi.4gb.home
2. Interface appelle : GET /api/ansible/playbooks?target=raspi.4gb.home
3. Playbooks affichés :
   • ❌ backup-proxmox-config.yml (NON affiché - incompatible)
   • ✅ health-check.yml (compatible via all)
   • ✅ vm-upgrade.yml (compatible via all)
   • etc.

Scénario 3 : Tentative d'Exécution Incompatible

1. Utilisateur essaie d'exécuter backup-proxmox-config.yml sur raspi.4gb.home
2. API retourne erreur 400 avec message explicatif
3. Interface affiche le message d'erreur à l'utilisateur

📝 Bonnes Pratiques

Pour les Nouveaux Playbooks

Toujours définir explicitement le champ hosts :

---
- name: Mon nouveau playbook
  hosts: role_proxmox  # ← Spécifier le groupe cible
  become: true
  vars:
    category: maintenance
    subcategory: system
  tasks:
    # ...

Pour les Playbooks Universels

Utiliser hosts: all pour les playbooks qui peuvent s'exécuter partout :

---
- name: Health check
  hosts: all  # ← Compatible avec tous les hôtes
  become: false
  # ...

🔍 Dépannage

Problème : Playbook non visible pour un hôte

Vérifier :

1. Le champ hosts dans le playbook
2. L'appartenance de l'hôte aux groupes dans ansible/inventory/hosts.yml

Exemple :

# Voir les playbooks compatibles avec un hôte
curl http://localhost:8000/api/ansible/playbooks?target=ali2v.xeon.home

Problème : Erreur lors de l'exécution

Message : "Le playbook X n'est pas compatible avec la cible Y"

Solution :

• Utiliser le filtrage pour voir les playbooks compatibles
• Choisir un playbook compatible ou changer la cible

📚 Documentation

• Documentation complète : PLAYBOOK_FILTERING.md
• Script de test : test_playbook_filtering.py
• Code source : app/app_optimized.py (classe AnsibleService)

✨ Résumé des Bénéfices

1. ✅ Sécurité : Empêche l'exécution de playbooks sur des hôtes incompatibles
2. ✅ Clarté : Messages d'erreur explicites en cas d'incompatibilité
3. ✅ Filtrage : Interface peut afficher uniquement les playbooks pertinents
4. ✅ Validation : Contrôles à tous les niveaux (listing, exécution, schedules)
5. ✅ Flexibilité : Support de all, groupes, hôtes, et sous-groupes

🚀 Prochaines Étapes

L'implémentation est complète et testée. L'interface peut maintenant :

1. Appeler /api/ansible/playbooks?target=X pour filtrer les playbooks
2. Afficher uniquement les playbooks compatibles dans les listes déroulantes
3. Gérer les erreurs de compatibilité avec des messages clairs
4. Créer des schedules avec validation automatique

---

Date : 5 décembre 2024
Statut : ✅ Implémentation complétée et testée
Tests : 8/8 réussis