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

K3s instal·lat: El clúster K3s ha d'estar funcionant
kubectl configurat: Accés al clúster amb kubectl
cert-manager: Per a certificats SSL (utilitza Cloudflare Origin Issuer)
DNS configurat: Els dominis *.rogi.casa han d'apuntar al clúster

Desplegar una Aplicació

Per desplegar una aplicació específica:

# 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

# 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ó

# 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 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/ 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:

# Veure ConfigMaps
kubectl get configmaps -n <namespace>

# Editar un ConfigMap
kubectl edit configmap <nom> -n <namespace>

Secrets

Els secrets es gestionen de forma segura:

# Crear un secret
kubectl create secret generic <nom> --from-literal=key=value -n <namespace>

# Veure secrets (encoded)
kubectl get secrets -n <namespace>

Secret per al Registre de Gitea

Per utilitzar imatges del registre privat de Gitea, cal crear un secret de tipus docker-registry:

# Crear el secret per al registre de Gitea (namespace default)
kubectl create secret docker-registry gitea-registry \
  --docker-server=gitea.rogi.casa \
  --docker-username=<teu-usuari-gitea> \
  --docker-password=<teu-password-o-token> \
  --docker-email=<teu-email>

# Si l'aplicació està en un namespace específic, afegeix -n <namespace>
kubectl create secret docker-registry gitea-registry \
  --docker-server=gitea.rogi.casa \
  --docker-username=<teu-usuari-gitea> \
  --docker-password=<teu-password-o-token> \
  --docker-email=<teu-email> \
  -n <namespace>

Nota: És recomanable utilitzar un token d'accés personal de Gitea en lloc de la contrasenya. Pots generar-lo a: Gitea > Settings > Applications > Generate New Token.

Les aplicacions que utilitzen imatges del registre de Gitea (com gym-tracker) han d'incloure imagePullSecrets al seu deployment:

spec:
  imagePullSecrets:
  - name: gitea-registry
  containers:
  - name: app
    image: gitea.rogi.casa/user/repo/image:tag

🔍 Troubleshooting

Verificar l'estat dels Pods

# 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

# Veure serveis
kubectl get services --all-namespaces

# Veure configuració d'Ingress
kubectl get ingress --all-namespaces
kubectl describe ingress <nom> -n <namespace>

Verificar Volums

# Veure PVCs
kubectl get pvc --all-namespaces

# Veure PVs
kubectl get pv

📝 Bones Pràctiques

Namespaces: Les aplicacions complexes utilitzen namespaces dedicats (n8n, monitoring, phoenix)
Labels: Tots els recursos utilitzen labels consistents per facilitar la gestió
Resources Limits: Configura limits de CPU/memòria per evitar overconsumption
Health Checks: Implementa liveness i readiness probes quan sigui possible
Backup: Fes còpies de seguretat regulars dels PVCs i ConfigMaps crítics

🔄 Actualitzacions

Per actualitzar una aplicació:

# 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 configura un servei extern que apunta al NAS local (10.88.88.238:5000) sense desplegar pods dins del clúster.

README.md

K3s Cluster Deployment