update readme

2026-01-30 23:53:31 +01:00
parent 72af2644a8
commit dd1bd118e3
1 changed files with 221 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,221 @@
+# K3s Cluster Deployment
+
+Aquest repositori conté les configuracions de Kubernetes per desplegar diverses aplicacions en un clúster K3s. Totes les aplicacions s'executen en l'entorn local amb accés a través del domini `rogi.casa`.
+
+## 📋 Visió General
+
+Aquest clúster K3s gestiona els següents serveis:
+
+- **Glance** - Dashboard personal
+- **Pi-hole** - Bloqueig de publicitat a nivell de xarxa
+- **LiteLLM** - Proxy per a models de llenguatge
+- **Gitea** - Servidor Git self-hosted
+- **Home Assistant** - Automatització de la llar
+- **Jellyfin** - Servidor multimèdia
+- **n8n** - Automatització de fluxos de treball
+- **OpenWebUI** - Interfície web per a LLMs
+- **Phoenix** - Observabilitat per a aplicacions d'IA
+- **Vaultwarden** - Gestor de contrasenyes
+- **qBittorrent** - Client de torrents
+- **Minecraft Server** - Servidor de Minecraft
+- **Monitoring** - Prometheus i Grafana per a monitorització
+
+## 🏗️ Estructura del Repositori
+
+```
+.
+├── README.md                    # Aquest fitxer
+├── ingress.yaml                 # Configuració d'Ingress principal (Traefik)
+├── nas.yaml                     # Servei extern per al NAS
+├── <aplicació>/                 # Cada aplicació té el seu directori
+│   ├── deployment.yaml          # Definició del Deployment
+│   ├── service.yaml             # Definició del Service
+│   ├── ingress.yaml             # Configuració d'Ingress (opcional)
+│   ├── namespace.yaml           # Namespace dedicat (opcional)
+│   ├── configmap.yaml           # ConfigMaps (opcional)
+│   └── pvc.yaml                 # PersistentVolumeClaims (opcional)
+└── monitoring/                  # Stack de monitorització complet
+```
+
+## 🚀 Desplegament
+
+### Prerequisits
+
+1. **K3s instal·lat**: El clúster K3s ha d'estar funcionant
+2. **kubectl configurat**: Accés al clúster amb `kubectl`
+3. **cert-manager**: Per a certificats SSL (utilitza Cloudflare Origin Issuer)
+4. **DNS configurat**: Els dominis `*.rogi.casa` han d'apuntar al clúster
+
+### Desplegar una Aplicació
+
+Per desplegar una aplicació específica:
+
+```bash
+# Desplegar una aplicació completa (tots els recursos del directori)
+kubectl apply -f <aplicació>/
+
+# Desplegar un recurs específic
+kubectl apply -f <aplicació>/<fitxer>.yaml
+```
+
+### Desplegar Tot el Clúster
+
+```bash
+# Desplegar totes les aplicacions
+for dir in */; do
+  kubectl apply -f "$dir"
+done
+
+# O aplicar recursos globals primer
+kubectl apply -f ingress.yaml
+kubectl apply -f nas.yaml
+```
+
+### Eliminar una Aplicació
+
+```bash
+# Eliminar tots els recursos d'una aplicació
+kubectl delete -f <aplicació>/
+
+# Eliminar un recurs específic
+kubectl delete -f <aplicació>/<fitxer>.yaml
+```
+
+## 🌐 Ingress i Networking
+
+### Configuració d'Ingress Principal
+
+El fitxer [ingress.yaml](ingress.yaml) conté la configuració centralitzada d'Ingress utilitzant **Traefik** (controlador per defecte de K3s). Característiques:
+
+- **TLS/SSL**: Certificats wildcard `*.rogi.casa` gestionats per cert-manager
+- **Cloudflare Origin Issuer**: Utilitzat per generar certificats
+- **Redirect HTTPS**: Redireccions automàtiques de HTTP a HTTPS
+- **Compressió**: Habilitada per defecte
+
+### Aplicacions amb Ingress Dedicat
+
+Algunes aplicacions tenen el seu propi fitxer `ingress.yaml` dins del seu directori per a configuracions específiques.
+
+## 💾 Persistència de Dades
+
+Les aplicacions que necessiten emmagatzematge persistent utilitzen:
+
+- **PersistentVolumeClaims (PVC)**: Per a volums dinàmics
+- **ConfigMaps**: Per a fitxers de configuració
+- **StatefulSets**: Per a aplicacions que requereixen identitat persistent (ex: bases de dades)
+
+Exemple: Minecraft utilitza `pvc.yaml` i `ss.yaml` (StatefulSet).
+
+## 📊 Monitorització
+
+El directori [monitoring/](monitoring/) conté un stack complet de monitorització:
+
+- **Prometheus**: Recollida de mètriques
+- **Grafana**: Visualització de dades
+- **RBAC**: Permisos per a Prometheus
+- **ServiceMonitors**: Descobriment automàtic de serveis (ex: Phoenix)
+
+Accés:
+- Grafana: Configurat a través de l'Ingress principal
+- Datasources preconfigurats per connectar amb Prometheus
+
+## 🔧 Gestió de Configuracions
+
+### ConfigMaps
+
+Les aplicacions utilitzen ConfigMaps per gestionar configuracions:
+
+```bash
+# Veure ConfigMaps
+kubectl get configmaps -n <namespace>
+
+# Editar un ConfigMap
+kubectl edit configmap <nom> -n <namespace>
+```
+
+### Secrets
+
+Els secrets es gestionen de forma segura:
+
+```bash
+# Crear un secret
+kubectl create secret generic <nom> --from-literal=key=value -n <namespace>
+
+# Veure secrets (encoded)
+kubectl get secrets -n <namespace>
+```
+
+## 🔍 Troubleshooting
+
+### Verificar l'estat dels Pods
+
+```bash
+# Veure tots els pods
+kubectl get pods --all-namespaces
+
+# Descriure un pod amb problemes
+kubectl describe pod <nom-pod> -n <namespace>
+
+# Veure logs
+kubectl logs <nom-pod> -n <namespace>
+kubectl logs <nom-pod> -n <namespace> --previous  # Logs del contenidor anterior
+```
+
+### Verificar Serveis i Ingress
+
+```bash
+# Veure serveis
+kubectl get services --all-namespaces
+
+# Veure configuració d'Ingress
+kubectl get ingress --all-namespaces
+kubectl describe ingress <nom> -n <namespace>
+```
+
+### Verificar Volums
+
+```bash
+# Veure PVCs
+kubectl get pvc --all-namespaces
+
+# Veure PVs
+kubectl get pv
+```
+
+## 📝 Bones Pràctiques
+
+1. **Namespaces**: Les aplicacions complexes utilitzen namespaces dedicats (n8n, monitoring, phoenix)
+2. **Labels**: Tots els recursos utilitzen labels consistents per facilitar la gestió
+3. **Resources Limits**: Configura limits de CPU/memòria per evitar overconsumption
+4. **Health Checks**: Implementa liveness i readiness probes quan sigui possible
+5. **Backup**: Fes còpies de seguretat regulars dels PVCs i ConfigMaps crítics
+
+## 🔄 Actualitzacions
+
+Per actualitzar una aplicació:
+
+```bash
+# Editar el fitxer YAML amb la nova versió de la imatge
+vim <aplicació>/deployment.yaml
+
+# Aplicar els canvis
+kubectl apply -f <aplicació>/deployment.yaml
+
+# Verificar el rollout
+kubectl rollout status deployment/<nom> -n <namespace>
+
+# Revertir si cal
+kubectl rollout undo deployment/<nom> -n <namespace>
+```
+
+## 🌟 Serveis Externs
+
+### NAS
+El fitxer [nas.yaml](nas.yaml) configura un servei extern que apunta al NAS local (10.88.88.238:5000) sense desplegar pods dins del clúster.
+
+## 📚 Recursos Addicionals
+
+- [Documentació de K3s](https://docs.k3s.io/)
+- [Documentació de Kubernetes](https://kubernetes.io/docs/)
+- [Traefik Ingress Controller](https://doc.traefik.io/traefik/providers/kubernetes-ingress/)
+- [cert-manager](https://cert-manager.io/docs/)