Despliegue de un

Configuración

Después de instalar K3s, el clúster está listo para funcionar, pero para publicar aplicaciones al mundo exterior y garantizar su seguridad (HTTPS) se requerirá una configuración adicional. Desplegaremos un controlador Ingress y configuraremos la obtención automática de certificados TLS con Caddy.

1. Despliegue del controlador Ingress (Nginx Ingress Controller)

Aunque K3s incluye Traefik por defecto, lo deshabilitamos para tener más control. En su lugar, instalaremos el popular Nginx Ingress Controller, que ha demostrado ser muy eficaz.

# Instalamos Nginx Ingress Controller a través de Helm
# Primero añadimos el repositorio de Helm
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

# Instalamos el controlador Ingress en el namespace ingress-nginx
# Asumimos la versión 4.10.x para 2026
helm install ingress-nginx ingress-nginx/ingress-nginx \
    --namespace ingress-nginx --create-namespace \
    --set controller.service.type=NodePort \
    --set controller.service.nodePorts.http=30080 \
    --set controller.service.nodePorts.https=30443 \
    --version 4.10.1

Usamos NodePort para publicar el controlador Ingress en los puertos 30080 (HTTP) y 30443 (HTTPS) en el VPS. Esto nos permitirá proxyficar el tráfico a través de Caddy.

Verifica que los pods del controlador Ingress estén en ejecución:

# Verificamos los pods del controlador Ingress
kubectl get pods -n ingress-nginx

Asegúrate de que todos los pods estén en estado Running.

2. Instalación de Caddy como Reverse Proxy y cliente ACME

Caddy es un potente servidor web con HTTPS automático. Lo usaremos como un proxy inverso externo que aceptará tráfico de los puertos 80/443, obtendrá y renovará automáticamente los certificados TLS, y luego proxyficará las solicitudes al controlador Ingress de K3s.

Crea el archivo de configuración de Caddy en la ruta /etc/caddy/Caddyfile:

# Creamos el directorio para la configuración de Caddy
sudo mkdir -p /etc/caddy

# Abrimos el archivo Caddyfile para editarlo
sudo nano /etc/caddy/Caddyfile

Pega el siguiente contenido, reemplazando your-domain.com con tu dominio:

# /etc/caddy/Caddyfile
{
    email [email protected]
    # Habilitamos el registro para depuración
    log {
        output file /var/log/caddy/caddy.log
        level INFO
    }
}

your-domain.com {
    # HTTPS automático
    reverse_proxy localhost:30080 {
        # Necesario para el correcto funcionamiento del controlador Ingress
        header_up Host {http.request.host}
        header_up X-Real-IP {http.request.remote}
        header_up X-Forwarded-For {http.request.remote}
        header_up X-Forwarded-Proto {http.request.scheme}
    }
}

Guarda el archivo (Ctrl+X, Y, Enter).

Crea el directorio para los logs de Caddy:

# Creamos el directorio para los logs de Caddy y establecemos los permisos
sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy

Instala Caddy. Utilizaremos el repositorio oficial para Ubuntu:

# Instalamos las dependencias
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

# Añadimos la clave GPG de Caddy
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# Añadimos el repositorio de Caddy
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Actualizamos la lista de paquetes e instalamos Caddy
sudo apt update
sudo apt install -y caddy

Habilita e inicia el servicio Caddy:

# Iniciamos Caddy
sudo systemctl enable caddy
sudo systemctl start caddy
sudo systemctl status caddy

Asegúrate de que Caddy esté funcionando y no muestre errores. Si hay problemas, revisa los logs de Caddy: sudo journalctl -u caddy --no-pager.

Importante: asegúrate de que tu dominio (your-domain.com) apunte a la dirección IP de tu VPS en los registros DNS (registro A).

3. Despliegue de la primera aplicación (Nginx)

Desplegaremos una sencilla aplicación web Nginx para verificar el funcionamiento del clúster y del controlador Ingress.

Crea el archivo nginx-app.yaml:

# Creamos el archivo de manifiesto de Nginx
nano nginx-app.yaml

Pega el siguiente contenido:

# nginx-app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25.4-alpine # Versión actual para 2026
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx # Indicamos que este es un Ingress para Nginx Ingress Controller
  rules:
  - host: your-domain.com # Reemplaza con tu dominio
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-service
            port:
              number: 80

Guarda el archivo y aplícalo al clúster:

# Aplicamos el manifiesto de Nginx
kubectl apply -f nginx-app.yaml

Verifica el estado del despliegue:

# Verificamos los pods de Nginx
kubectl get pods -l app=nginx

# Verificamos el servicio de Nginx
kubectl get service nginx-service

# Verificamos el Ingress de Nginx
kubectl get ingress nginx-ingress

Asegúrate de que el pod de Nginx esté en ejecución, y que el servicio y el Ingress existan.

4. Verificación del funcionamiento

Ahora que todo está configurado, abre tu dominio (https://your-domain.com) en el navegador. Deberías ver la página de bienvenida estándar de Nginx. Si la ves, significa que K3s, Nginx Ingress Controller y Caddy funcionan correctamente, y el certificado HTTPS ha sido emitido e instalado automáticamente.

Si surgen problemas, verifica:

• Logs de los pods del Nginx Ingress Controller: kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
• Logs de Caddy: sudo journalctl -u caddy --no-pager
• Registros DNS de tu dominio.
• Estado de K3s: sudo systemctl status k3s

También puedes usar curl para verificar la accesibilidad:

# Verificamos el acceso HTTP
curl http://your-domain.com

# Verificamos el acceso HTTPS
curl -k https://your-domain.com # -k ignora la verificación del certificado si hay problemas

Copias de seguridad y mantenimiento

Las copias de seguridad regulares y el mantenimiento oportuno son la clave para la estabilidad y seguridad de su clúster K3s.

¿Qué hacer una copia de seguridad?

Para K3s en un solo nodo, los datos clave para la copia de seguridad son:

• Configuración de K3s: Archivos /etc/rancher/k3s/k3s.yaml y /var/lib/rancher/k3s/server/node-token.
• Estado del clúster (etcd): K3s utiliza SQLite por defecto, por lo que el archivo de la base de datos se encuentra en la ruta /var/lib/rancher/k3s/server/db/state.db. Si ha reconfigurado K3s para usar un etcd externo, deberá hacer una copia de seguridad de etcd.
• Datos de las aplicaciones: Si sus aplicaciones utilizan volúmenes persistentes (Persistent Volumes), asegúrese de que sus datos se respalden. K3s utiliza por defecto un aprovisionador de PV local, lo que significa que los datos se almacenan en el disco del propio VPS. La ruta suele ser /var/lib/rancher/k3s/storage/....
• Archivos de configuración de Caddy/Nginx: /etc/caddy/Caddyfile.

Script sencillo de copia de seguridad automática

Puede crear un script sencillo para hacer una copia de seguridad de los archivos clave y la base de datos de K3s. Ejemplo usando rsync y tar:

# Cree el archivo /usr/local/bin/backup_k3s.sh
sudo nano /usr/local/bin/backup_k3s.sh

Contenido del script (reemplace /path/to/backup/destination por su ruta):

#!/bin/bash

BACKUP_DIR="/tmp/k3s_backup_$(date +%Y%m%d%H%M%S)"
DESTINATION="/path/to/backup/destination" # Cambie a la ruta real o al bucket S3

mkdir -p $BACKUP_DIR
mkdir -p $DESTINATION

echo "Starting K3s backup at $(date)"

# Copia de seguridad de la configuración de K3s
cp /etc/rancher/k3s/k3s.yaml $BACKUP_DIR/k3s.yaml
cp /var/lib/rancher/k3s/server/node-token $BACKUP_DIR/node-token

# Copia de seguridad de la base de datos SQLite de K3s
# K3s proporciona un comando para crear una instantánea de la base de datos
sudo k3s etcd-snapshot --etcd-snapshot-dir $BACKUP_DIR

# Copia de seguridad de los datos de los Volúmenes Persistentes (si se usan localmente)
# Atención: para PV reales se necesita una estrategia más compleja (por ejemplo, Velero)
# cp -R /var/lib/rancher/k3s/storage/ $BACKUP_DIR/k3s-storage/

# Copia de seguridad de la configuración de Caddy
cp /etc/caddy/Caddyfile $BACKUP_DIR/Caddyfile

# Archivamos todas las copias de seguridad
tar -czvf $DESTINATION/k3s_backup_$(date +%Y%m%d%H%M%S).tar.gz -C $BACKUP_DIR .

# Limpiamos el directorio temporal
rm -rf $BACKUP_DIR

echo "K3s backup finished at $(date)"

Haga el script ejecutable:

# Hacemos el script ejecutable
sudo chmod +x /usr/local/bin/backup_k3s.sh

Añádalo a cron para ejecución diaria (por ejemplo, a las 3:00 de la mañana):

# Abrimos crontab para editar
sudo crontab -e

Añada la línea:

# Copia de seguridad diaria de K3s a las 03:00
0 3   * /usr/local/bin/backup_k3s.sh >> /var/log/k3s_backup.log 2>&1

Dónde almacenar las copias de seguridad

Nunca almacene las copias de seguridad en el mismo servidor del que está haciendo la copia. Considere las siguientes opciones:

• Almacenamiento externo compatible con S3: Solución económica y fiable (por ejemplo, Backblaze B2, DigitalOcean Spaces). Use s3cmd o rclone para la carga.
• VPS separado: Puede alquilar un VPS pequeño solo para almacenar copias de seguridad y usar rsync con claves SSH para transferirlas.
• Compartición NFS: Si tiene almacenamiento en red.

Actualizaciones: rolling vs ventana de mantenimiento

Para K3s en un solo nodo, el concepto de "actualización continua" (rolling update) no es aplicable, ya que no hay otros nodos a los que se pueda transferir la carga. La actualización de K3s siempre implicará un tiempo de inactividad del clúster durante un breve período.

• Actualización de K3s: Compruebe regularmente las nuevas versiones de K3s (por ejemplo, cada 3-6 meses). La actualización de K3s se realiza volviendo a ejecutar el script de instalación con la nueva versión o utilizando la utilidad k3s-upgrade.

  
  # Ejemplo de actualización de K3s a una nueva versión
  curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.32.0+k3s1" sh -s - --disable traefik
  

  Esto provocará un reinicio de K3s y un breve tiempo de inactividad.

• Actualización del SO y paquetes: Actualice regularmente el sistema operativo: sudo apt update && sudo apt upgrade -y. Programe estas actualizaciones durante períodos de bajo tráfico, ya que pueden requerir un reinicio del servidor.
• Actualización de aplicaciones: Actualice sus imágenes de contenedor y Helm charts. Kubernetes permite hacerlo sin tiempo de inactividad, utilizando actualizaciones continuas (rolling updates) para los Deployments.

Siempre pruebe las actualizaciones en un entorno de prueba antes de aplicarlas al servidor de producción.

Solución de problemas + Preguntas frecuentes

En esta sección, abordaremos problemas comunes que pueden surgir al trabajar con K3s y proporcionaremos respuestas a preguntas frecuentes.

No puedo conectarme al clúster usando kubectl

Qué verificar: Asegúrese de que la variable de entorno KUBECONFIG esté configurada correctamente (echo $KUBECONFIG debería devolver /home/su_usuario/.kube/config). Verifique los permisos del archivo ~/.kube/config (deben ser 600). Asegúrese de que el servicio K3s esté en ejecución (sudo systemctl status k3s) y que el firewall (UFW) permita el puerto 6443/tcp.

Cómo solucionarlo: Reinicie K3s: sudo systemctl restart k3s. Verifique los logs de K3s: sudo journalctl -u k3s --no-pager. Asegúrese de que en el archivo ~/.kube/config la dirección IP del servidor esté especificada correctamente.

Mi aplicación no está disponible a través del dominio, Caddy muestra un error

Qué verificar: Verifique el registro DNS de su dominio (el registro A debe apuntar a la IP de su VPS). Asegúrese de que Caddy esté en ejecución (sudo systemctl status caddy) y que su Caddyfile esté configurado correctamente, apuntando a localhost:30080. Verifique los logs de Caddy (sudo journalctl -u caddy --no-pager) en busca de errores con Let's Encrypt o el proxy. Asegúrese de que el controlador Ingress esté en ejecución y sus pods estén en estado Running (kubectl get pods -n ingress-nginx).

Cómo solucionarlo: Corrija los registros DNS. Verifique la sintaxis de Caddyfile con el comando sudo caddy validate --config /etc/caddy/Caddyfile. Reinicie Caddy: sudo systemctl reload caddy. Asegúrese de que su recurso Ingress en Kubernetes (kubectl get ingress) tenga el host correcto y haga referencia a un servicio y puerto existentes.

Los pods de las aplicaciones están en estado Pending o CrashLoopBackOff

Qué verificar: Si el pod está en estado Pending, esto a menudo significa falta de recursos (CPU/RAM) o problemas con el Persistent Volume. Si está en CrashLoopBackOff, significa que la aplicación dentro del contenedor falla constantemente. Verifique los logs del pod: kubectl logs <nombre_del_pod> y la descripción del pod: kubectl describe pod <nombre_del_pod>.

Cómo solucionarlo: Para Pending: aumente los recursos del VPS o disminuya las solicitudes de recursos en el manifiesto del pod. Para CrashLoopBackOff: examine los logs de la aplicación, es posible que el problema esté en su configuración, variables de entorno o la falta de dependencias necesarias.

¿Qué configuración mínima de VPS es adecuada?

Para K3s sin aplicaciones pesadas, 1 núcleo de CPU, 1 GB de RAM y 20-30 GB de SSD son suficientes. Esto bastará para ejecutar K3s y algunos servicios muy ligeros. Sin embargo, si planea ejecutar aplicaciones web o bases de datos reales, se recomienda un mínimo de 2 núcleos de CPU, 4 GB de RAM y 50 GB de SSD para un funcionamiento cómodo y la posibilidad de escalar.

¿Qué elegir: VPS o dedicado para esta tarea?

Para el despliegue de K3s en un solo nodo para la mayoría de proyectos personales, startups o entornos de prueba, un VPS es la opción óptima en términos de relación precio/rendimiento. Los servidores dedicados se justifican cuando se requiere el máximo rendimiento, recursos garantizados, un gran volumen de espacio en disco o si planea ejecutar muchos clústeres/aplicaciones que consumen muchos recursos, donde un VPS ya no puede manejar la carga o las limitaciones de CPU/RAM/IOPS.

K3s no se inicia después de reiniciar el servidor

Qué verificar: Asegúrese de que el servicio K3s esté habilitado para el inicio automático: sudo systemctl is-enabled k3s. Si no está habilitado, ejecute sudo systemctl enable k3s. Verifique los logs del servicio: sudo journalctl -u k3s --no-pager.

Cómo solucionarlo: Si hay errores en los logs relacionados con el firewall o la red, asegúrese de que UFW permita todos los puertos necesarios y que las interfaces de red estén activas. Si es un error de la base de datos, es posible que el archivo /var/lib/rancher/k3s/server/db/state.db esté dañado. En tal caso, podría ser necesaria una restauración desde una copia de seguridad.

¿Cómo actualizar K3s a una nueva versión?

Qué verificar: Antes de actualizar, asegúrese de hacer una copia de seguridad del clúster. Verifique la documentación oficial de K3s para detectar cambios en la nueva versión que puedan afectar sus aplicaciones o configuración.

Cómo solucionarlo: La actualización de K3s en un solo nodo se realiza volviendo a ejecutar el script de instalación con la nueva versión especificada: curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="vX.Y.Z+k3s1" sh -. Esto descargará automáticamente la nueva versión, actualizará los binarios y reiniciará K3s. Sus aplicaciones estarán temporalmente no disponibles durante la actualización de K3s.

Conclusiones y próximos pasos

¡Felicidades! Ha desplegado con éxito un clúster Kubernetes ligero K3s en su VPS, ha configurado un controlador Ingress con HTTPS automático y ha publicado su primera aplicación. Ahora tiene una plataforma potente y flexible para alojar sus aplicaciones en contenedores, gestionada de forma declarativa y con gastos generales mínimos.

¿Hacia dónde ir a continuación?

1. Monitorización y registro (logging): Instale sistemas de monitorización como Prometheus y Grafana, así como un registro centralizado (por ejemplo, Loki o la pila ELK) para rastrear el estado del clúster y las aplicaciones.
2. Gestión de secretos: Explore herramientas para el almacenamiento y la gestión segura de secretos en Kubernetes (por ejemplo, HashiCorp Vault, Sealed Secrets) en lugar de usar variables de entorno o archivos.
3. Escalabilidad y tolerancia a fallos: Si su proyecto crece, considere agregar nodos de trabajo K3s adicionales o migrar a un clúster Kubernetes de múltiples nodos completo para aumentar la tolerancia a fallos y el rendimiento.