221 lines
6.5 KiB
Markdown
221 lines
6.5 KiB
Markdown
# 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/) |