# 🌑 Moon Cheat Sheet

Moon est le **Task Runner officiel** de la plateforme Homelab.

Il fournit une interface unique permettant d'exécuter les tâches d'administration, de maintenance et de déploiement sans avoir à mémoriser les commandes complexes.

---

## 🎯 Objectif

Moon simplifie l'utilisation de la plateforme en standardisant l'exécution des scripts et des playbooks.

Il gère automatiquement :

- l'exécution depuis la racine du dépôt ;
- les variables d'environnement nécessaires ;
- la configuration Ansible ;
- la standardisation des commandes ;
- la mise en cache des tâches lorsque cela est possible.

---

## 🚀 Commandes principales

Toutes les commandes doivent être exécutées depuis la racine du dépôt.

```bash
cd ~/workspace/homelab-infra-monorepo

```

---

## 🛠 Maintenance de la plateforme

<table id="bkmrk-commande-description"><thead><tr><th>Commande</th><th>Description</th></tr></thead><tbody><tr><td>`moon run :apply-system_update-config`</td><td>Mise à jour des systèmes Linux (APT/DNF), redémarrages automatiques et maintenance.</td></tr><tr><td>`moon run :apply-cluster-restart`</td><td>Rolling Restart complet du cluster Kubernetes (Drain → Reboot → Uncordon).</td></tr><tr><td>`moon run :apply-docker-prune`</td><td>Suppression des images Docker inutilisées sur les hôtes Docker.</td></tr><tr><td>`moon run :apply-network-config`</td><td>Déploiement de la configuration réseau (AdGuard Home, DHCP, DNS).</td></tr></tbody></table>

---

## 📦 Gestion des applications

<table id="bkmrk-commande-description-1"><thead><tr><th>Commande</th><th>Description</th></tr></thead><tbody><tr><td>`moon run :apply-docker-registry-config`</td><td>Déploiement et mise à jour du Docker Registry.</td></tr><tr><td>`moon run :apply-bookstack-config`</td><td>Mise à jour de BookStack.</td></tr><tr><td>`moon run :apply-plex-config`</td><td>Configuration du serveur Plex.</td></tr></tbody></table>

---

## ☸ Mise à niveau du cluster Kubernetes

### Via Moon

```bash
moon run :upgrade-k8s-cluster -- \
-e "target_version=1.3x.x-1.1"

```

### Commande Ansible équivalente

```bash
ansible-playbook \
-i infra/ansible/inventory.yml \
infra/ansible/playbooks/upgrade-cluster.yml \
-e "target_version=1.3x.x-1.1"

```

---

## ⚙ Ajouter une nouvelle tâche

Les tâches Moon sont définies dans les fichiers de configuration du dépôt.

Exemple :

```yaml
tasks:

  ma-nouvelle-tache:

    command: |
      export ANSIBLE_ROLES_PATH=$(pwd)/infra/ansible/roles
      export ANSIBLE_HOST_KEY_CHECKING=False

      ansible-playbook \
      -i infra/ansible/inventory.yml \
      infra/ansible/playbooks/mon_playbook.yml

    options:
      runFromWorkspaceRoot: true
      interactive: true

    inputs:
      - infra/ansible/playbooks/mon_playbook.yml

```

---

## 🔍 Débogage

### Simulation (Dry Run)

```bash
moon run :ma-tache --dryRun

```

### Forcer l'exécution

```bash
moon run :ma-tache --force

```

Cette option ignore le cache de Moon.

### Afficher les tâches disponibles

```bash
moon project :

```

---

## 🚨 Dépannage

<table id="bkmrk-probl%C3%A8me-solution-la"><thead><tr><th>Problème</th><th>Solution</th></tr></thead><tbody><tr><td>La tâche est indiquée comme "cached"</td><td>Utiliser `--force`.</td></tr><tr><td>Erreur Ansible</td><td>Vérifier l'inventaire et les rôles.</td></tr><tr><td>Variables d'environnement manquantes</td><td>Exécuter la commande depuis la racine du dépôt.</td></tr><tr><td>Commande inconnue</td><td>Vérifier la définition dans la configuration Moon.</td></tr></tbody></table>

---

## 💡 Bonnes pratiques

- Utiliser Moon comme point d'entrée pour toutes les opérations manuelles.
- Ne pas exécuter directement les playbooks Ansible lorsqu'une tâche Moon existe déjà.
- Conserver des noms de tâches cohérents.
- Une tâche Moon = une responsabilité.
- Versionner systématiquement la configuration Moon dans Git.
- Préférer Moon pour les opérations répétitives afin de garantir une exécution homogène.

---

## 🏗 Philosophie de la plateforme

<table id="bkmrk-composant-responsabi"><thead><tr><th>Composant</th><th>Responsabilité</th></tr></thead><tbody><tr><td>Git</td><td>Source de vérité</td></tr><tr><td>Moon</td><td>Point d'entrée utilisateur</td></tr><tr><td>Terraform</td><td>Provisionnement de l'infrastructure</td></tr><tr><td>AWX / Ansible</td><td>Configuration des systèmes</td></tr><tr><td>ArgoCD</td><td>Déploiement GitOps Kubernetes</td></tr></tbody></table>

Moon ne remplace pas Terraform, AWX ou ArgoCD. Il fournit une interface unique permettant d'orchestrer les opérations manuelles de la plateforme de manière simple et reproductible.

---

## 📚 Voir également

- Ansible
- Terraform
- ArgoCD
- Kubernetes
- Monitoring

```