admin/aiworker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete documentation for future sessions

Browse Source 
- CLAUDE.md for AI agents to understand the codebase
- GITEA-GUIDE.md centralizes all Gitea operations (API, Registry, Auth)
- DEVELOPMENT-WORKFLOW.md explains complete dev process
- ROADMAP.md, NEXT-SESSION.md for planning
- QUICK-REFERENCE.md, TROUBLESHOOTING.md for daily use
- 40+ detailed docs in /docs folder
- Backend as submodule from Gitea

Everything documented for autonomous operation.

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hector Ros
2026-01-20 00:36:53 +01:00
commit db71705842
49 changed files with 19162 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

311
CLUSTER-READY.md Normal file
View File

@@ -0,0 +1,311 @@
# 🚀 AiWorker Kubernetes Cluster - PRODUCTION READY
**Status**: ✅ Completamente Funcional
**Fecha**: 2026-01-19
**Ubicación**: Houston, Texas (us-hou-1)
---
## 🎯 Infraestructura Desplegada
### Servidores (8 VPS)
| Tipo | Hostname | IP Pública | IP Privada | Specs | Estado |
|----------------|----------------|-----------------|-------------|----------------------|--------|
| Control Plane | k8s-cp-01 | 108.165.47.233 | 10.100.0.2 | 4 vCPU, 8 GB RAM | ✅ |
| Control Plane | k8s-cp-02 | 108.165.47.235 | 10.100.0.3 | 4 vCPU, 8 GB RAM | ✅ |
| Control Plane | k8s-cp-03 | 108.165.47.215 | 10.100.0.4 | 4 vCPU, 8 GB RAM | ✅ |
| Worker | k8s-worker-01 | 108.165.47.225 | 10.100.0.5 | 8 vCPU, 16 GB RAM | ✅ |
| Worker | k8s-worker-02 | 108.165.47.224 | 10.100.0.6 | 8 vCPU, 16 GB RAM | ✅ |
| Worker | k8s-worker-03 | 108.165.47.222 | 10.100.0.7 | 8 vCPU, 16 GB RAM | ✅ |
| Load Balancer | k8s-lb-01 | 108.165.47.221 | 10.100.0.8 | 2 vCPU, 4 GB RAM | ✅ |
| Load Balancer | k8s-lb-02 | 108.165.47.203 | 10.100.0.9 | 2 vCPU, 4 GB RAM | ✅ |
**Total**: 48 vCPU, 104 GB RAM, ~2.9 TB Storage
**Costo**: $148/mes
---
## 🌐 URLs de Acceso
| Servicio | URL | Credenciales | Estado |
|-------------|----------------------------|----------------------------|--------|
| Gitea | https://git.fuq.tv | (setup inicial pendiente) | ✅ |
| ArgoCD | https://argocd.fuq.tv | admin / LyPF4Hy0wvp52IoU | ✅ |
| Longhorn UI | https://longhorn.fuq.tv | admin / aiworker2026 | ✅ |
| HAProxy LB1 | http://108.165.47.221:8404/stats | admin / aiworker2026 | ✅ |
| HAProxy LB2 | http://108.165.47.203:8404/stats | admin / aiworker2026 | ✅ |
| Test App | https://test.fuq.tv | (público) | ✅ |
---
## 💾 Bases de Datos
### MariaDB 11.4.9 LTS
**Conexión interna (desde pods)**:
```
Host: mariadb.control-plane.svc.cluster.local
Port: 3306
```
**Credenciales Root:**
```
Usuario: root
Password: AiWorker2026_RootPass!
```
**Credenciales Aplicación:**
```
Database: aiworker
Usuario: aiworker
Password: AiWorker2026_UserPass!
```
**Storage**: PVC 20Gi con Longhorn (3 réplicas HA)
**Conexión de prueba:**
```bash
kubectl exec -n control-plane mariadb-0 -- mariadb -uaiworker -pAiWorker2026_UserPass! aiworker -e "SHOW TABLES;"
```
### Gitea Database
**Base de datos**: `gitea` (creada en MariaDB)
**Conexión**: Configurada automáticamente en Gitea
---
## 🗂️ Storage HA con Longhorn
### Configuración
- **StorageClass**: `longhorn` (default)
- **Replicación**: 3 réplicas por volumen
- **Tolerancia a fallos**: Puede perder 2 nodos sin pérdida de datos
- **UI**: https://longhorn.fuq.tv
### Volúmenes Actuales
| PVC | Namespace | Tamaño | Réplicas | Nodos |
|--------------|----------------|--------|----------|--------------------------------------|
| mariadb-pvc | control-plane | 20Gi | 3 | worker-01, worker-02, worker-03 |
| gitea-data | gitea | 50Gi | 3 | worker-01, worker-02, worker-03 |
---
## 🔧 Software Instalado
| Componente | Versión | Namespace | Estado |
|-------------------------|--------------|----------------|--------|
| K3s | v1.35.0+k3s1 | - | ✅ |
| Nginx Ingress | latest | ingress-nginx | ✅ |
| Cert-Manager | v1.16.2 | cert-manager | ✅ |
| Longhorn | v1.8.0 | longhorn-system| ✅ |
| ArgoCD | stable | argocd | ✅ |
| MariaDB | 11.4.9 | control-plane | ✅ |
| Gitea | 1.22 | gitea | ✅ |
| HAProxy | 2.8.16 | (en LBs) | ✅ |
---
## 🔐 Kubeconfig
**Path local**: `~/.kube/aiworker-config`
**Configurar como default:**
```bash
export KUBECONFIG=~/.kube/aiworker-config
```
**Crear alias:**
```bash
alias k='kubectl --kubeconfig ~/.kube/aiworker-config'
```
**Uso:**
```bash
kubectl --kubeconfig ~/.kube/aiworker-config get nodes
kubectl --kubeconfig ~/.kube/aiworker-config get pods -A
```
---
## 📋 Namespaces
| Namespace | Propósito | Resource Quota |
|-----------------|-------------------------------|---------------------|
| control-plane | Backend, API, MySQL, Redis | 8 CPU, 16 GB |
| agents | Claude Code agents | 20 CPU, 40 GB |
| gitea | Git server | 2 CPU, 4 GB |
| monitoring | Prometheus, Grafana (futuro) | - |
| argocd | GitOps | - |
| ingress-nginx | Ingress controller | - |
| cert-manager | TLS management | - |
| longhorn-system | Distributed storage | - |
---
## 🔒 Seguridad
### TLS/SSL
- ✅ Certificados automáticos con Let's Encrypt
- ✅ Force HTTPS redirect
- ✅ Email notificaciones: hector+aiworker@teamsuqad.io
### Secrets Creados
```bash
# MariaDB
kubectl get secret mariadb-secret -n control-plane
# Longhorn UI
kubectl get secret longhorn-basic-auth -n longhorn-system
# ArgoCD
kubectl get secret argocd-initial-admin-secret -n argocd
```
---
## 🧪 Verificación Funcional
### Cluster Health
```bash
kubectl get nodes
kubectl get pods -A
kubectl top nodes
kubectl get pvc -A
```
### Storage Replication
```bash
# Ver volúmenes
kubectl get volumes.longhorn.io -n longhorn-system
# Ver réplicas
kubectl get replicas.longhorn.io -n longhorn-system
# UI Web
https://longhorn.fuq.tv
```
### Ingress & TLS
```bash
# Ver ingress
kubectl get ingress -A
# Ver certificados
kubectl get certificate -A
# Probar acceso
curl https://test.fuq.tv
curl https://git.fuq.tv
curl https://argocd.fuq.tv
```
---
## 📦 Próximos Pasos
### 1. Configurar Gitea (https://git.fuq.tv)
- Completar instalación inicial
- Crear organización "aiworker"
- Crear usuario bot con token
- Configurar webhooks
### 2. Desplegar Backend
```bash
kubectl apply -f k8s/backend/
```
### 3. Desplegar Frontend
```bash
kubectl apply -f k8s/frontend/
```
### 4. Configurar ArgoCD
- Login en https://argocd.fuq.tv
- Conectar repositorio Gitea
- Crear Applications
- Configurar auto-sync
---
## 🎨 Arquitectura Final
```
Internet
↓
[DNS: *.fuq.tv]
(108.165.47.221 + .203)
↓
┌─────────────┴─────────────┐
↓ ↓
[HAProxy LB-01] [HAProxy LB-02]
:80, :443 :80, :443
↓ ↓
└─────────────┬─────────────┘
↓
[Private Network]
10.100.0.0/24
↓
┌───────────────────┼───────────────────┐
↓ ↓ ↓
[CP etcd HA] [CP etcd HA] [CP etcd HA]
10.100.0.2 10.100.0.3 10.100.0.4
↓ ↓ ↓
─────┴───────────────────┴───────────────────┴─────
↓ ↓ ↓
[Worker + Storage] [Worker + Storage] [Worker + Storage]
10.100.0.5 10.100.0.6 10.100.0.7
↓ ↓ ↓
[Pods] [Pods] [Pods]
│ │ │
[MariaDB PVC]────────[Longhorn 3x Replica]────────[Gitea PVC]
```
---
## 🎓 Lo que aprendimos
1. ✅ Desplegar K3s HA con embedded etcd (3 control planes)
2. ✅ Configurar red privada para comunicación interna
3. ✅ Setup HAProxy para load balancing HTTP/HTTPS
4. ✅ DNS round-robin para HA de load balancers
5. ✅ Nginx Ingress Controller con NodePort
6. ✅ Cert-Manager con Let's Encrypt automático
7. ✅ Longhorn distributed storage con replicación
8. ✅ MariaDB 11.4 LTS con storage HA
9. ✅ Gitea con storage HA y MariaDB
10. ✅ ArgoCD para GitOps
---
## 💪 Características HA Implementadas
| Componente | HA Implementado | Tolerancia a Fallos |
|-------------------|-----------------|---------------------|
| Control Plane | ✅ 3 nodos etcd | Pierde 1 nodo |
| Workers | ✅ 3 nodos | Pierde 2 nodos |
| Load Balancers | ✅ DNS RR | Pierde 1 LB |
| Storage (Longhorn)| ✅ 3 réplicas | Pierde 2 workers |
| Ingress | ✅ En workers | Redundante |
| DNS | ✅ 2 IPs | Auto failover |
**Cluster puede perder simultáneamente:**
- 1 Control Plane
- 2 Workers
- 1 Load Balancer
- Y seguir funcionando! 🎉
---
## 📞 Soporte
- **CubePath**: https://cubepath.com/support
- **K3s**: https://docs.k3s.io
- **Longhorn**: https://longhorn.io/docs/
- **Cert-Manager**: https://cert-manager.io/docs/
---
**🎉 ¡Cluster listo para desplegar AiWorker!**