From bcd134a091ab4f406380e829e99fa2bfe033ac57 Mon Sep 17 00:00:00 2001 From: alkatrazz Date: Tue, 12 May 2026 17:22:26 +0200 Subject: [PATCH] docs: add README with cluster overview and architecture --- README.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..02f189e --- /dev/null +++ b/README.md @@ -0,0 +1,192 @@ +# Funk Lab + +> Homelab IA — Kubernetes (Talos) + GPU AMD + Agent autonome (Hermes) + + + +## 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