Funk-lab/README.md

# 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