Guía de Instalación y Configuración de homelab-monorepo
El proyecto homelab-monorepo es una solución integral de Infraestructura como Código (IaC) diseñada para automatizar el ciclo de vida completo de un laboratorio doméstico sobre Proxmox VE. A diferencia de los scripts aislados, este monorepo implementa una metodología de "tridente" que garantiza la idempotencia y la replicabilidad en cada etapa del despliegue.
Para obtener detalles técnicos específicos sobre las capacidades del software, visita su ficha oficial: homelab-monorepo.
Arquitectura de "Tridente" (Packer + Terraform + Ansible)
El flujo de trabajo del proyecto se divide en tres capas críticas que permiten reconstruir el laboratorio completo de forma reproducible:
- Capa 1: Imagen (Packer): Genera plantillas personalizadas para Proxmox. Soporta distribuciones como Ubuntu y Rocky Linux, además de configuraciones para Windows mediante CloudBase-Init. Esto elimina la necesidad de instalar manualmente sistemas operativos en cada VM.
- Capa 2: Aprovisionamiento (Terraform): Utiliza el proveedor de Proxmox para crear recursos virtuales (VMs y contenedores LXC) basándose en las imágenes creadas por Packer. Gestiona CPU, memoria y redes.
- Capa 3: Configuración (Ansible): Una vez que la infraestructura existe, Ansible toma el control para instalar paquetes, configurar redes y desplegar servicios complejos como clústeres K3s o entornos de Active Directory.
Prerrequisitos del Sistema
Antes de comenzar la instalación, asegúrate de contar con los siguientes elementos:
- Infraestructura: Servidor físico con Proxmox VE instalado o nodos Raspberry Pi para clústeres K3s.
- Herramientas de IaC: Instalación local y funcional de Packer, Terraform y Ansible en tu máquina de administración.
- Acceso de Red: Credenciales de API de Proxmox (usuario con permisos suficientes) y acceso SSH a los nodos finales.
- Conocimientos Previos: Comprensión básica de redes para configurar las variables en el archivo
.tfvars.
Paso 1: Preparación del Entorno y Variables
El primer paso es preparar el repositorio local y definir la topología de red que Terraform utilizará.
- Clona el repositorio oficial:
git clone https://github.com/clayshek/homelab-monorepo - Navega al directorio raíz y localiza las carpetas de Terraform y Packer.
- Crea o edita un archivo de variables (ejemplo:
terraform.tfvars) para reflejar tu red real (ej. 192.168.x.x). Es crucial que los nombres de las redes y las IPs coincidan con tu infraestructura física.
Paso 2: Creación de Imágenes con Packer
Packer genera plantillas base que ya incluyen configuraciones básicas, eliminando la necesidad de instalaciones manuales.
- Linux: Soporta Ubuntu y Rocky Linux, optimizados para el uso en contenedores LXC o VMs.
- Windows: Utiliza CloudBase-Init para automatizar la configuración inicial de red y usuarios.
Ejecuta los scripts dentro de la carpeta correspondiente de Packer. Una vez generadas las imágenes, Proxmox podrá utilizarlas como plantillas base.
Paso 3: Aprovisionamiento con Terraform
Terraform leerá tus archivos de configuración y creará automáticamente los recursos en Proxmox VE.
- Inicializa el proyecto para descargar los proveedores necesarios:
terraform init - Ejecuta la aplicación del plan:
terraform apply
En esta etapa, Terraform gestionará la asignación de recursos. Si algo falla en este paso, utiliza terraform destroy para limpiar los recursos antes de reintentar.
Paso 4: Configuración con Ansible
Una vez que las máquinas están en línea y son accesibles por SSH, Ansible realiza la configuración final (hardening básico, instalación de paquetes y despliegue de servicios).
- Verifica la conectividad SSH a los nuevos nodos.
- Ejecuta el playbook principal:
ansible-playbook -i inventory.ini site.yml
Este paso es vital para desplegar clústeres de K3s o configurar servicios de Active Directory en entornos Windows.
Verificación, Backup y Rollback
- Comprobación: Verifica que los nodos K3s aparezcan como 'Ready' y que las máquinas Windows se unan correctamente al dominio.
- Backup: Se recomienda realizar snapshots en Proxmox antes de ejecutar cambios críticos a través de Ansible o durante la fase de Terraform.
- Rollback: En caso de error crítico, utiliza
terraform destroypara eliminar los recursos y vuelve a aplicar la configuración tras corregir las variables.
Seguridad y Limitaciones Importantes
- Las plantillas de Windows Server pueden requerir ajustes manuales adicionales según la versión específica (ej. Windows 2019).
- El uso de Active Directory es una dependencia lógica necesaria para las configuraciones de infraestructura Windows incluidas.
Preguntas Frecuentes (FAQ)
¿Es compatible con otros hipervisores como ESXi?
No directamente. La lógica de Terraform está acoplado a la API de Proxmox VE.
¿Qué es CloudInit y por qué se usa aquí?
Permite configurar sistemas Linux durante el primer arranque (red, usuarios, SSH), permitiendo que Terraform entregue máquinas listas para usar inmediatamente.
¿Puedo desplegar servicios críticos en internet con esta configuración?
No se recomienda. El proyecto carece de configuraciones de seguridad estándar como firewalls avanzados necesarios para la exposición pública.