Funk-lab/admin/cluster.md

# Gestion du cluster Funk

Script central : `/usr/local/bin/funk-cluster` sur storage-01.
Fonctions bash configurées dans `~/.bashrc` du poste perso.

---

## Commandes

```bash
# Depuis le poste perso
funk-status          # État complet (storage-01 + gpu-01 + k8s)
funk-start           # Démarre gpu-01 (WOL) + tous les services
funk-start --k8s     # Idem + démarre le cluster k8s (compute-01/02/03)
funk-stop            # Arrête services + gpu-01 + storage-01
funk-stop --k8s      # Idem + éteint le cluster k8s avant
```

> `funk-stop` éteint storage-01 en dernier — la connexion SSH se coupe, c'est normal.

---

## Procédures d'utilisation

### Allumer le homelab (sans k8s)

1. **Allumer storage-01 et gpu-01 manuellement** (bouton physique)
2. Attendre ~30s que storage-01 boot
3. Depuis le poste perso :
   ```bash
   funk-start
   ```
4. Le script démarre les services et attend que gpu-01 soit prêt (~3 min pour les modèles LLM)
5. Vérifier l'état :
   ```bash
   funk-status
   ```

### Allumer le homelab complet (avec k8s)

1. **Allumer storage-01 et gpu-01 manuellement**
2. Lancer le démarrage :
   ```bash
   funk-start --k8s
   ```
3. Le script envoie des paquets WOL aux compute nodes — **si WOL non configuré dans le BIOS, allumer compute-01/02/03 manuellement pendant l'attente ping** (~30s de fenêtre)
4. Le script attend automatiquement que les nœuds k8s soient `Ready` (3 min max)

> WOL sur les compute nodes nécessite `Wake on LAN` activé dans le BIOS (Gigabyte : `Advanced → ACPI Settings`). Tant que ce n'est pas configuré, allumage manuel requis.

### Éteindre le homelab (sans k8s)

```bash
funk-stop
```

La connexion SSH se coupe à la fin (storage-01 s'éteint lui-même). C'est normal.

### Éteindre le homelab complet (avec k8s)

```bash
funk-stop --k8s
```

Ordre d'arrêt automatique : hermes-agent + litellm → talosctl shutdown compute-01/02/03 → gpu-01 → qdrant + postgresql → storage-01.

---

## Ce que fait chaque commande

### `funk-status`

Vérifie dans l'ordre :
- Services storage-01 : postgresql-16, qdrant, litellm, hermes-agent
- Santé : PostgreSQL (connexion réelle), Qdrant (collections), LiteLLM (modèles), Hermes, NFS export
- gpu-01 : ping, NFS /mnt/models, llama-server GPU (:1234), embeddings, llama-server CPU (:1236/:1237)
- Cluster k8s : ping compute-01/02/03, kubectl get nodes Ready

### `funk-start [--k8s]`

1. Démarre postgresql-16, qdrant, litellm, hermes-agent sur storage-01
2. Envoie un paquet Wake-on-LAN à gpu-01 si éteint, attend le ping + SSH
3. Attend le montage NFS `/mnt/models` sur gpu-01
4. Attend le chargement du modèle GPU (jusqu'à 4 min)
5. Attend les modèles CPU (jusqu'à 2 min)
6. `--k8s` : envoie WOL aux 3 nœuds, attend ping, attend nœuds Ready (3 min max)

### `funk-stop [--k8s]`

1. Arrête hermes-agent et litellm sur storage-01 (timeout 10s + SIGKILL si besoin)
2. `--k8s` : `talosctl shutdown` sur compute-01/02/03, attend extinction
3. Éteint gpu-01 (`shutdown -h now` via SSH)
4. Arrête qdrant et postgresql-16 sur storage-01
5. Éteint storage-01 (`shutdown -h now`) — connexion SSH coupée

---

## GitOps — ArgoCD

Les workloads k8s sont gérés par ArgoCD. **Ne jamais faire `helm install` ou `kubectl apply` manuellement pour les workloads.**

```bash
# Déployer quelque chose : modifier k8s/ → git push → ArgoCD applique (~3 min)

# Vérifier l'état des applications
kubectl get applications -n argocd

# Forcer un refresh si ArgoCD n'a pas encore détecté un commit
kubectl -n argocd annotate application <nom> argocd.argoproj.io/refresh=hard --overwrite
```

UI : http://argocd.lab.local — voir [argocd.md](argocd.md) pour la doc complète.

---

## Machines et MACs

| Machine | IP | MAC | Rôle |
|---|---|---|---|
| storage-01 | 192.168.10.1 / 192.168.1.200 | — | Passerelle + services IA |
| gpu-01 | 192.168.10.20 | `a8:a1:59:72:a6:11` | LLM GPU + CPU |
| compute-01 | 192.168.10.11 | `6c:4b:90:82:8e:47` | k8s control-plane |
| compute-02 | 192.168.10.12 | `6c:4b:90:cf:7f:c5` | k8s worker |
| compute-03 | 192.168.10.13 | `6c:4b:90:b6:49:20` | k8s worker |

---

## Fonctions bash (`~/.bashrc` poste perso)

```bash
funk-start() { ssh storage-01 "sudo /usr/local/bin/funk-cluster start $*"; }
funk-stop()  { ssh storage-01 "sudo /usr/local/bin/funk-cluster stop $*"; }
alias funk-status='ssh storage-01 "sudo /usr/local/bin/funk-cluster status"'
alias funk-pull='ssh storage-01 "sudo -u ansible git -C /srv/data/lab pull"'
```

Les fonctions bash transmettent les arguments — `funk-start --k8s` et `funk-stop --k8s` fonctionnent directement.

---

## Déploiement du script

Le script est versionné dans `ansible/roles/litellm/files/funk-cluster`.
Pour le redéployer sur storage-01 :

```bash
scp ansible/roles/litellm/files/funk-cluster s01:/tmp/
ssh s01 "sudo cp /tmp/funk-cluster /usr/local/bin/funk-cluster && sudo chmod +x /usr/local/bin/funk-cluster"
```

---

## Points d'attention

| Sujet | Détail |
|---|---|
| Ordre d'arrêt | Hermes/LiteLLM → k8s (optionnel) → gpu-01 → Qdrant/PG → storage-01 |
| Ordre de démarrage | storage-01 (toujours déjà up) → gpu-01 → k8s (optionnel) |
| WOL compute nodes | BIOS non configuré → allumer manuellement pendant l'attente ping de `funk-start --k8s` |
| LiteLLM bloquant | `systemctl stop --timeout=10` + SIGKILL automatique si timeout |
| talosctl path | `/home/ansible/.config/talos/config` requis explicitement (sudo change HOME) |
| SSH coupée à l'arrêt | Normal — storage-01 s'éteint lui-même en fin de `funk-stop` |