k3s-cluster/README.md

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

#### Secret per al Registre de Gitea

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

```bash
# 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:

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

## 🔍 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/)