akadmin/Funk-lab
1
0
Fork 0
mirror of https://github.com/Alkatrazz24/Funk-lab.git synced 2026-07-08 19:14:43 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
Funk-lab/CLAUDE.md
alkatrazz 144c522096 chore: mettre à jour vault Gmail + RAG 339 chunks 
- vault: App Password Gmail mis à jour pour postfix_relay
- CLAUDE.md: RAG 284 → 339 chunks (ajout docs n8n + open-webui)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-29 18:17:08 +02:00

283 lines
11 KiB
Markdown
Raw Blame History

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Présentation du projet
**Funk** — homelab IA composé d'un cluster Kubernetes (Talos) pour les services applicatifs, d'un hôte d'inférence LLM dédié (gpu-01 / llama-server ROCm), et d'un agent autonome (Hermes Agent) sur storage-01. Stack IaC complète : Ansible + talhelper + ArgoCD.
**État actuel (2026-05-29)** :
- ✅ Hermes Agent opérationnel — multi-profils (funk-ai/system/monitor/brain)
- ✅ RAG opérationnel — Qdrant 339 chunks, `rag-ingest` / `rag-query`, skill funk-ai
- ✅ Monitoring complet — Prometheus + Grafana + AlertManager → webhook Hermes + n8n
- ✅ storage-01 installé — `192.168.10.1` (LAN cluster), `192.168.1.200` (WAN)
- ✅ gpu-01 installé — llama-server GPU (:1234) + CPU (:1236/:1237) opérationnels
- ✅ LiteLLM sur storage-01 — proxy multi-modèles + ask-agent (écoute `0.0.0.0:4000`)
- ✅ Cluster k8s Talos opérationnel (MetalLB + Traefik + wildcard DNS lab.local)
- ✅ postfix_relay — SMTP sortant via Gmail SMTP + App Password (aliyesilkaya93@gmail.com)
- ✅ Open WebUI opérationnel — `openwebui.lab.local`, namespace `ai`, backend LiteLLM
- ✅ n8n opérationnel — `n8n.lab.local`, namespace `ai`, 2 workflows actifs
- ⏳ WOL compute nodes non configuré (BIOS) — allumage manuel requis
Journal de progression : `PROGRESS.md` → `progress/YYYY-MM-DD.md`
---
## Architecture des machines
| Machine | IP | OS | Rôle |
|---|---|---|---|
| storage-01 | 192.168.10.1 / 192.168.1.200 | AlmaLinux 9.7 | Passerelle + bastion admin + données + Hermes Agent — **hors cluster** |
| compute-01 | 192.168.10.11 | Talos v1.13 | k8s control-plane |
| compute-02 | 192.168.10.12 | Talos v1.13 | k8s worker |
| compute-03 | 192.168.10.13 | Talos v1.13 | k8s worker |
| gpu-01 | 192.168.10.20 | AlmaLinux 9.7 | llama-server dédié (RX 6700XT, ROCm 7.x) — **hors cluster** |
**Points clés d'architecture :**
- `storage-01` et `gpu-01` sont **hors du cluster k8s** — consommés via `ExternalName` services ou `Endpoints` manuels
- Single control-plane assumé : si compute-01 tombe, `kubectl apply` ne fonctionne plus mais les workloads continuent
- Modèles LLM stockés sur NFS RAID5 de storage-01 (`/srv/data/models`), montés sur gpu-01 (`/mnt/models`)
---
## Stack IaC — trois outils, trois cibles
| Outil | Cible | Déclenchement |
|---|---|---|
| **Ansible** | storage-01, gpu-01 (AlmaLinux) | Push manuel : `make apply-storage` / `make apply-gpu` |
| **talhelper** | compute-01/02/03 (Talos) | Push manuel : `talosctl apply-config` |
| **ArgoCD** | Workloads k8s | Pull automatique depuis Git |
---
## Ansible
### Commandes via Makefile (depuis la racine du repo)
```bash
python3 -m venv .venv # créer le venv (une seule fois, avant make install)
make install # pip install + ansible-galaxy (à faire une fois)
make ping # vérifier la connectivité vers tous les hôtes
make check # dry-run site.yml (storage-01 + gpu-01)
make apply # appliquer site.yml complet
make apply-storage # appliquer uniquement storage-01.yml
make apply-gpu # appliquer uniquement gpu-01.yml
make vault-view # lire le vault chiffré
make vault-edit # éditer le vault (ouvre $EDITOR)
make vault-encrypt # (ré)chiffrer vault.yml
```
### Commandes directes (depuis `ansible/`)
```bash
ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm
ansible-playbook -i inventory.yml playbooks/gpu-01.yml --tags llama_server
```
Les tags correspondent aux noms de rôles. Tous les rôles sont idempotents.
### Inventaire et connectivité
- `storage-01` : accès direct SSH via `192.168.1.200` (WAN)
- `gpu-01` : accès via ProxyJump sur `storage-01` (configuré dans `inventory.yml`)
- Vault password dans `.vault_pass` (ignoré par git, chargé automatiquement via `ansible.cfg`)
### Rôles — storage-01
`hermes_user`, `common`, `gateway` (nftables + NAT), `dnsmasq`, `nfs_server`, `qdrant`, `postgresql`, `minio`, `litellm`, `hermes_agent`, `rag`, `node_exporter`, `alertmanager_webhook`, `postfix_relay`
### Rôles — gpu-01
`hermes_user`, `common`, `rocm`, `nfs_client`, `llama_server`, `node_exporter`
> `lm_studio` est présent dans `ansible/roles/` mais n'est plus utilisé dans aucun playbook.
### Caveat premier déploiement — hermes_agent
Le rôle `hermes_agent` installe le binaire via `curl | bash` seulement si le binaire est absent. La configuration (`.env`, `config.yaml`) est ensuite conditionnelle à `hermes_binary.stat.exists`. Sur un hôte vierge, il faut **deux runs consécutifs** : le premier installe, le second configure.
### Variables par hôte
`ansible/host_vars/<hostname>/vars.yml` contient les variables spécifiques à chaque machine :
- `storage-01` : UUID RAID5, exports NFS, chemins des services sous `/srv/data`
- `gpu-01` : chemin du modèle GGUF (`llama_model_path`), alias modèle, `llama_ctx_size`, montages NFS
Variables globales (non-secrètes) dans `ansible/group_vars/all/vars.yml` : `admin_user`, `dns_domain`, `ntp_servers`, `cluster_network`, `wan_gateway`.
### Secrets Ansible Vault
Variables chiffrées dans `ansible/group_vars/all/vault.yml` :
- `vault_anthropic_api_key` — clé Anthropic pour le profil brain
- `vault_pg_hermes_password`, `vault_pg_litellm_password`
- `vault_postfix_relay_password` — SMTP Brevo
---
## talhelper (nœuds Talos)
```bash
cd talos/
talhelper genconfig # régénérer configs nœuds
talhelper gencommand apply --node compute-02 | bash # appliquer sur un nœud
talhelper gencommand bootstrap --node compute-01 | bash # bootstrap (1ère fois seulement)
talhelper gencommand kubeconfig | bash # récupérer kubeconfig
```
`talos/clusterconfig/` est généré — gitignored, ne pas committer.
`talos/talsecret.sops.yaml` chiffré avec SOPS+age (clé dans `.config/sops/`, ignorée par git).
---
## ArgoCD (workloads k8s)
Pattern "App of Apps" : modifier un manifest → `git commit` + `git push` → ArgoCD poll automatiquement (~3 min).
```bash
git add k8s/apps/open-webui/
git commit -m "open-webui: bump to v0.4.0"
git push
```
ArgoCD utilise le repo `git@github.com:Alkatrazz24/Funk-lab.git` branche `main`. Les deux namespaces gérés actuellement : `infra` (Traefik, MetalLB, NFS-provisioner) et `monitoring` (kube-prometheus-stack 85.0.2).
---
## Stack IA — Hermes Agent
### Profils
| Profil | Modèle | Port | Usage |
|---|---|---|---|
| `funk-ai` | Qwen3-8B Q4_K_M | GPU :1234 | Agent principal (~35 tok/s) |
| `system` | Qwen3-1.7B Q4_K_M | CPU :1236 | Calculs, formatage, résumés |
| `monitor` | Qwen3-1.7B Q4_K_M | CPU :1237 | Analyse logs, métriques, état services |
| `brain` | Claude Sonnet 4.6 API | Anthropic | Raisonnement complexe — facturé |
Hermes écoute sur le port `8080` (gateway). Dashboard web sur le port `9119` (accessible uniquement depuis `192.168.1.10`).
### Switcher le modèle de Hermes à chaud
```bash
hermes-switch status # modèle actuel de hermes-default
hermes-switch qwen # → Qwen3-8B sur gpu-01 (local, gratuit)
hermes-switch claude # → Claude Sonnet 4.6 via API Anthropic (facturé)
```
`hermes-switch` modifie `/etc/litellm/config.yaml` puis redémarre `litellm`. L'alias `hermes-default` dans LiteLLM est ce que Hermes consomme — changer cet alias ne nécessite pas de reconfigurer Hermes.
### ask-agent (délégation inter-agents)
Binaire dans `/usr/local/bin/ask-agent` sur storage-01. Appel LiteLLM direct (:4000), réponse en ~2-5s.
**Règle** : ask-agent reçoit du **texte**, jamais des commandes shell. Toujours 2 étapes :
```bash
# Étape 1 — collecter les données
journalctl -u litellm -n 20 --no-pager --output=cat
# Étape 2 — passer le texte à ask-agent
ask-agent monitor "logs litellm : <résultat étape 1> — erreurs ?"
```
### RAG — Documentation Funk
Qdrant collection `funk-docs` indexée depuis `admin/` (284 chunks, score min 0.60).
```bash
rag-query "comment relancer dnsmasq ?"
rag-query "nftables port cluster configuration"
rag-query "hermes profils litellm modèles" --top 3
```
Scripts installés sur storage-01 : `/usr/local/bin/rag-query`, `/usr/local/bin/rag-ingest`
Après modification de `admin/`, re-déployer via la commande directe (voir section Ansible) :
```bash
ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags rag
```
Le script `admin/index_knowledge.py` est l'ingesteur Python brut.
### Hermes Skills — `hermes-skills/`
Versionnés dans ce repo, déployés par le rôle `hermes_agent` vers `~hermes/`.
```
hermes-skills/
├── funk/
│ ├── agent-delegation/SKILL.md # usage de ask-agent (2 étapes, agents dispo)
│ └── rag-docs/SKILL.md # usage de rag-query
└── souls/ # prompts système par profil
├── funk-ai.md # profil principal (agent sur storage-01)
├── system.md # profil calculs/formatage
├── monitor.md # profil analyse logs
└── brain.md # profil Claude API
```
---
## Base de connaissance — `admin/`
Documentation admin versionnée, indexée dans le RAG :
```
admin/
├── ia/ # hermes, litellm, llama_server, rocm, rag, alertmanager-webhook
├── infra/ # dnsmasq, nfs, réseau, ssh, email
├── install/ # procédures installation storage-01, gpu-01, k8s
├── k8s/ # argocd, talos, monitoring
├── ops/ # ansible, cluster, système
└── incidents.md # historique des incidents matériel/service avec résolutions
```
---
## Réseaux
- CNI Flannel — Pods : `10.42.0.0/16`
- Services : `10.43.0.0/16`
- MetalLB pool : `192.168.10.200-230` (IP virtuelles Traefik/services)
- DNS wildcard `*.lab.local` via dnsmasq → Traefik
nftables géré par le rôle `gateway` sur storage-01. Modifier `ansible/roles/gateway/templates/nftables.conf.j2` puis :
```bash
ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags gateway
```
---
## Contrainte GPU critique
La RX 6700XT (gfx1031) n'est **pas officiellement supportée** par ROCm. Variable obligatoire dans tous les services GPU :
```
HSA_OVERRIDE_GFX_VERSION=10.3.0
```
Gérée automatiquement par le rôle `llama_server`. ROCm tourne directement sur l'hôte AlmaLinux.
---
## Gestion du cluster
Ces commandes sont des **fonctions bash sur le poste perso** (configurées dans `~/.bashrc`) qui SSH sur storage-01 et invoquent `/usr/local/bin/funk-cluster`.
```bash
funk-status # état de tous les services (storage-01 + gpu-01 + k8s)
funk-start # WOL gpu-01 + démarrage services storage-01
funk-start --k8s # idem + nœuds k8s (WOL → drain-aware boot)
funk-stop # arrêt propre gpu-01 + services
funk-stop --k8s # idem + drain k8s → NFS check → talosctl shutdown
```
**etcd backup** (single control-plane → critique) :
```bash
talosctl etcd snapshot /path/to/backup.db --nodes compute-01
```
---
## Conventions
- **Git** : branches `main` (prod) / `feature/*` — conventional commits (`feat:`, `fix:`, `chore:`, `docs:`)
- **Secrets** : Ansible Vault (Ansible), SOPS+age (Talos), Sealed Secrets (k8s)
- **Namespaces k8s** : `argocd`, `infra`, `monitoring`, `external`
- **Hermes data** : `~hermes/` doit résider sur le RAID5 `/srv/data`, pas sur le SSD OS
- **RAM compute-02/03** : toujours définir `resources.requests` + `resources.limits` (8 GB RAM, OOM-killer actif)
Reference in a new issue View git blame Copy permalink