docs: add README with cluster overview and architecture

2026-07-08 05:24:43 +02:00 · 2026-05-12 17:22:26 +02:00 · 2026-05-12 17:22:26 +02:00 · bcd134a091
commit bcd134a091
parent a2dee9fe1c
1 changed files with 192 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,192 @@
+# Funk Lab
+
+> Homelab IA — Kubernetes (Talos) + GPU AMD + Agent autonome (Hermes)
+
+<!-- Si tu as une image du rack/setup, ajoute-la ici :
+![Funk Lab](docs/funk-lab.jpg)
+-->
+
+## Vue d'ensemble
+
+**Funk** est un homelab orienté IA composé de 5 machines physiques :
+
+- un nœud de stockage/passerelle qui héberge tous les services de données et l'agent IA
+- un nœud GPU dédié à l'inférence LLM local (AMD RX 6700XT)
+- trois nœuds qui forment un cluster Kubernetes (Talos Linux)
+
+L'ensemble est géré en Infrastructure-as-Code : **Ansible** pour les hôtes AlmaLinux, **talhelper** pour Talos, **ArgoCD** pour les workloads Kubernetes.
+
+---
+
+## Architecture
+
+```
+                    Internet
+                       │
+                  [ Freebox ]
+                       │
+              ┌────────────────┐
+              │   storage-01   │  AlmaLinux 9.7
+              │  192.168.10.1  │  Gateway + NAT + DNS
+              │                │  NFS RAID5 · PostgreSQL
+              │                │  Qdrant · LiteLLM · Hermes
+              └───────┬────────┘
+                      │  LAN cluster (192.168.10.0/24)
+          ┌───────────┼───────────┐
+          │           │           │
+    [ compute-01 ] [ compute-02 ] [ compute-03 ]   Talos Linux
+    192.168.10.11  192.168.10.12  192.168.10.13    Kubernetes
+    control-plane     worker        worker
+
+          ┌───────────┘
+          │
+      [ gpu-01 ]   AlmaLinux 9.7
+    192.168.10.20  llama-server (ROCm)
+                   AMD RX 6700XT 12GB
+```
+
+---
+
+## Stack IA
+
+```
+Hermes Agent  →  LiteLLM :4000  →  Qwen3-8B  (local, gpu-01)
+                                →  Claude Sonnet / Opus  (API Anthropic)
+
+Hermes  ←→  Qdrant :6333  (mémoire vectorielle sémantique)
+```
+
+| Composant | Rôle | Hôte |
+|---|---|---|
+| **llama-server** | Inférence LLM + embeddings (ROCm 7.x) | gpu-01 |
+| **LiteLLM** | Proxy API — switch local/cloud transparent | storage-01 |
+| **Hermes Agent** | Agent IA autonome avec mémoire vectorielle | storage-01 |
+| **Qdrant** | Base vectorielle pour la mémoire sémantique | storage-01 |
+| **PostgreSQL 16** | Persistance Hermes + LiteLLM | storage-01 |
+
+---
+
+## Infrastructure
+
+### Machines
+
+| Machine | IP | OS | RAM | Rôle |
+|---|---|---|---|---|
+| storage-01 | 192.168.10.1 | AlmaLinux 9.7 | 32 GB | Gateway · NFS · Services IA |
+| gpu-01 | 192.168.10.20 | AlmaLinux 9.7 | 32 GB | Inférence LLM (RX 6700XT) |
+| compute-01 | 192.168.10.11 | Talos v1.10+ | 16 GB | k8s control-plane |
+| compute-02 | 192.168.10.12 | Talos v1.10+ | 8 GB | k8s worker |
+| compute-03 | 192.168.10.13 | Talos v1.10+ | 8 GB | k8s worker |
+
+### Stockage
+
+- RAID5 logiciel (`md0`) — 4 × 1 TB SATA → **2,7 TB** utiles sur storage-01
+- Point de montage `/srv/data` — héberge modèles LLM, bases de données, données Hermes
+
+---
+
+## Organisation du repo
+
+```
+├── ansible/              # Gestion storage-01 + gpu-01 (AlmaLinux)
+│   ├── inventory.yml
+│   ├── playbooks/
+│   │   ├── storage-01.yml
+│   │   └── gpu-01.yml
+│   ├── group_vars/       # Variables globales + vault chiffré
+│   ├── host_vars/        # Variables par machine
+│   └── roles/
+│       ├── common        # Paquets, sécurité, NTP
+│       ├── gateway       # nftables + NAT
+│       ├── dnsmasq       # DNS local (lab.local)
+│       ├── nfs_server    # Exports NFS (modèles, k8s)
+│       ├── nfs_client    # Montages NFS sur gpu-01
+│       ├── rocm          # Stack GPU AMD (ROCm 7.x)
+│       ├── llama_server  # Inférence LLM + embeddings
+│       ├── litellm       # Proxy LLM multi-modèles
+│       ├── hermes_agent  # Agent IA autonome
+│       ├── postgresql    # Base de données
+│       └── qdrant        # Base vectorielle
+├── talos/                # Cluster Kubernetes (talhelper)  [à venir]
+└── k8s/                  # Workloads ArgoCD               [à venir]
+```
+
+---
+
+## Démarrage rapide
+
+### Pré-requis
+
+```bash
+pip install ansible
+ansible-galaxy collection install ansible.posix community.general community.postgresql
+```
+
+### Déployer storage-01
+
+```bash
+cd ansible/
+ansible-playbook -i inventory.yml playbooks/storage-01.yml
+```
+
+### Déployer gpu-01
+
+```bash
+ansible-playbook -i inventory.yml playbooks/gpu-01.yml
+```
+
+### Déployer un rôle spécifique
+
+```bash
+ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm
+ansible-playbook -i inventory.yml playbooks/gpu-01.yml --tags llama_server
+```
+
+### Gestion du cluster
+
+```bash
+funk-start    # Allume gpu-01 (WOL) + démarre tous les services
+funk-stop     # Arrêt propre
+funk-status   # État de tous les services (13 checks)
+```
+
+---
+
+## Secrets
+
+Les secrets sont gérés via **Ansible Vault** (chiffrement AES256).
+
+```bash
+# Chiffrer le vault
+ansible-vault encrypt ansible/group_vars/all/vault.yml
+
+# Editer les secrets
+ansible-vault edit ansible/group_vars/all/vault.yml
+```
+
+Variables stockées dans le vault : `vault_anthropic_api_key`, `vault_pg_hermes_password`, `vault_pg_litellm_password`.
+
+---
+
+## Contrainte GPU
+
+La RX 6700XT (gfx1031) n'est pas officiellement supportée par ROCm. La variable suivante est obligatoire dans tous les services GPU :
+
+```
+HSA_OVERRIDE_GFX_VERSION=10.3.0
+```
+
+Elle est gérée automatiquement par le rôle Ansible `llama_server`.
+
+---
+
+## Roadmap
+
+- [x] Ansible — storage-01 (gateway, NFS, PostgreSQL, Qdrant, LiteLLM, Hermes)
+- [x] Ansible — gpu-01 (ROCm, llama-server, embeddings)
+- [x] Stack IA opérationnelle (Hermes + Qwen3-8B + mémoire vectorielle)
+- [ ] Route statique Freebox
+- [ ] Bootstrap cluster Kubernetes (Talos + talhelper)
+- [ ] ArgoCD + MetalLB + Traefik
+- [ ] Workloads IA en k8s (Open WebUI, n8n, monitoring)
+- [ ] Rôle MinIO