Problema

Muchos entusiastas de homelab quieren automatizar despliegues, versionar configuraciones y mantener sus servicios disponibles sin invertir tiempo excesivo. La pregunta recurrente es si montar un clúster Kubernetes (por ejemplo k3s) aporta suficiente valor frente a una arquitectura basada en Docker Compose, especialmente cuando el objetivo principal es GitOps y no se necesita alta disponibilidad. La decisión impacta en la curva de aprendizaje, el consumo de recursos y la flexibilidad para escalar o migrar a máquinas virtuales.

Causa

  1. Sobre‑ingeniería percibida – Kubernetes introduce conceptos (pods, CRDs, controladores) que pueden resultar innecesarios si la carga de trabajo es limitada.
  2. Recursos limitados – Cada nodo k3s consume CPU y RAM para el plano de control y los agentes, reduciendo la capacidad disponible para los contenedores reales.
  3. Falta de experiencia en operaciones – Sin antecedentes en networking avanzado, RBAC o gestión de certificados, la configuración inicial se vuelve un cuello de botella.
  4. Objetivo de GitOps mal alineado – GitOps es una metodología, no una herramienta exclusiva. Se puede aplicar con Docker Compose + Ansible, con ArgoCD + k8s, o con otras pipelines CI/CD.
  5. Tiempo disponible – El mantenimiento de un clúster implica actualizaciones, backup de etcd, monitoreo de componentes y resolución de drift, lo que consume tiempo que muchos usuarios no pueden dedicar.

Solución

Adoptar un enfoque modular que permita empezar con Docker Compose y Ansible y migrar a Kubernetes solo cuando los requisitos lo justifiquen.

1. Arquitectura base con Proxmox

  • Mantener Proxmox como hipervisor principal.
  • Crear dos VMs dedicadas: una para GitOps controller (por ejemplo, un contenedor con ArgoCD o una máquina con Ansible) y otra para servicios críticos (Home Assistant, bases de datos).
  • Reservar los nodos Dell Optiplex para cargas de trabajo ligeras o para pruebas de Kubernetes futuro.

2. GitOps con Docker Compose + Ansible

  1. Repositorio Git: estructura estándar (/compose, /ansible, /configs).
  2. Pipeline CI (GitHub Actions, GitLab CI) que:
    • Lanza docker-compose pull && docker-compose up -d en la VM objetivo mediante SSH.
    • Ejecuta playbooks Ansible para ajustes de red, usuarios y backup.
  3. Ventajas:
    • Menor overhead de recursos.
    • Curva de aprendizaje corta: solo Docker Compose y Ansible.
    • Fácil rollback mediante docker-compose down && docker-compose up -d con versiones de imágenes.

3. Preparación para una migración a k3s

Si la carga crece o aparecen requisitos de HA, seguir estos pasos:

  • Instalar k3s en modo agente en los Optiplex, manteniendo un nodo maestro ligero (puede ser la VM de control).
  • Convertir stacks: usar kompose para traducir docker-compose.yml a manifiestos k8s y versionarlos en Git.
  • Mantener ArgoCD: una vez k3s está operativo, conectar ArgoCD al mismo repositorio; los manifests ya versionados se sincronizan automáticamente.
  • Desactivar Ansible para despliegues de contenedores; conservarlo solo para configuraciones del host (firewall, usuarios).

4. Herramientas complementarias

  • Portainer o Rancher Desktop para inspección rápida de contenedores cuando se usa Compose.
  • Prometheus + Grafana (ligeros) para monitoreo tanto de Docker como de k3s.
  • Restic + borg para backups de volúmenes; pueden ser orquestados por Ansible.

Cuándo aplicar esta solución

Señal Acción recomendada
< 5 servicios críticos, uso < 8 CPU y 16 GB RAM Docker Compose + Ansible desde el inicio
Necesidad de despliegues frecuentes desde Git, pero sin HA Mantener la arquitectura anterior y añadir ArgoCD como controlador de GitOps
Crecimiento > 10 servicios, requisitos de escalado automático o multi‑zona Migrar a k3s, usar ArgoCD para sincronización y dejar Ansible para host
Limitación de tiempo para aprender k8s Priorizar Docker Compose; planificar migración cuando haya margen de aprendizaje
Requerimientos de alta disponibilidad para bases de datos o MQTT Implementar k3s con al menos 3 nodos y habilitar StatefulSets

Código

# Ejemplo de pipeline CI que actualiza un stack Docker Compose vía SSH
ssh user@docker-host <<'EOF'
cd /opt/homelab/compose
git pull origin main
docker-compose pull
docker-compose up -d --remove-orphans
EOF

# Conversión rápida de docker-compose a manifiestos k8s con kompose
kompose convert -f docker-compose.yml -o k8s/
git add k8s/
git commit -m "Add k8s manifests generated from compose"
git push origin main

Verificación

  1. Docker Compose

    • Ejecutar docker ps y confirmar que los contenedores están en el estado Up.
    • Verificar que los puertos expuestos responden (curl http://host:port).

  2. ArgoCD

    • Acceder a la UI de ArgoCD y comprobar que el proyecto está en estado Synced y Healthy.
    • Revisar los logs del pod argocd-repo-server para detectar errores de sincronización.

  3. k3s

    • kubectl get nodes debe listar todos los nodos con Ready.
    • kubectl get pods -A muestra los pods del stack sin CrashLoopBackOff.

  4. Backup

    • Ejecutar el playbook Ansible que lanza Restic y validar que el snapshot aparece en el repositorio remoto.

Notas adicionales

  • Recursos de k3s: un nodo maestro con 2 CPU y 2 GB RAM es suficiente para pruebas; los agentes pueden compartir recursos con otras VMs siempre que no superen el 70 % de uso total.
  • Persistencia: Docker Compose requiere volúmenes host; en k3s usar hostPath o un CSI ligero (local-path-provisioner) para evitar dependencias externas.
  • Seguridad: habilitar ssh-key sin contraseña para los pipelines y restringir el acceso a la VM de control mediante firewall.
  • Rollback rápido: con Docker Compose basta con cambiar la etiqueta de la imagen en docker-compose.yml; con k8s, ArgoCD permite revertir a una versión anterior del commit.
  • Monitoreo unificado: exportar métricas de Docker (/metrics) y de k3s a la misma instancia de Prometheus simplifica la observabilidad.