[DRAFT] Propuesta de Estructura del Proyecto: Manejador de Ambientes Cloud (Azure VMs, Go)

1. Propósito General

Desarrollar una herramienta en Go que permita definir y desplegar entornos completos de máquinas virtuales en Azure usando archivos de plantilla HCL, soportando automatización, validación, reproducibilidad y registro centralizado de operaciones.

2. Objetivos Específicos

Permitir que cualquier equipo pueda definir las características de su entorno cloud de manera declarativa y sin intervención manual.
Desplegar máquinas virtuales y sus componentes asociados en Azure, a partir de estas plantillas, orquestando recursos de manera ordenada y reproducible.
Registrar cada acción y resultado para facilitar troubleshooting y auditoría.
Facilitar la futura extensión hacia otros tipos de recursos (bases de datos, balanceadores), otros proveedores cloud, o nuevas formas de integración (API, UI).

3. Alcance de la Primera Versión (MVP)

Entrada por archivo HCL describiendo el ambiente y las VM.
Despliegue automatizado de máquinas virtuales, redes y recursos básicos asociados.
Logging y reporte de acciones realizadas.
Manejo de credenciales seguro (Service Principal, Managed Identity).
Posible operación en CLI local, contenedor o servidor dedicado.
No incluye rollback, monitoreo ni recursos avanzados en la primera etapa.

4. Componentes Principales

a. Motor de Parsing y Validación de Plantillas

Interpreta el archivo HCL, valida estructura, campos, y dependencias mínimas.
Informa claramente de errores de sintaxis o inconsistencias antes de proceder.

b. Orquestador de Provisión

Toma la estructura validada del template y decide el orden óptimo de creación de recursos (vnet → subnet → VM).
Ejecuta las llamadas a Azure y maneja los estados de éxito/fallo de cada recurso.

c. Módulo de Autenticación

Administra las credenciales para acceso seguro a la API de Azure.
Permite alternar fácilmente entre métodos soportados (Service Principal, Managed Identity).

Cada acción y resultado se registra en logs.
Estructura pensada para facilitar extension a almacenamiento centralizado o integración con sistemas de auditoría.

e. Interfaz de Usuario (CLI)

Permite realizar comandos apply, plan, validate, destroy, etc., con salida clara y humana.
Interfaz amigable para operación directa por ingenieros/sistemas.

5. Principios y Decisiones Clave

Declaratividad: El entorno cloud debe estar definido por lo que dice la plantilla, no por configuración mutable o ad-hoc.
Reproducibilidad: Ejecutando el mismo template varias veces debe producir resultados consistentes, posibilitando ambientes efímeros y replicables.
Extensibilidad: La arquitectura debe permitir añadir soporte a nuevos recursos Azure, otros clouds o futuras necesidades con mínimo retrabajo.
Seguridad: Manejo cuidadoso de credenciales y capacidades; nunca registrar secretos en logs ni exponer información sensible.
Clear Feedback: Cualquier error de usuario, validación, o del proveedor cloud debe ser reportado de forma comprensible y si es posible sugerir solución.

6. Evolución/Futuro

Añadir soporte para recursos avanzados (Base de datos, balanceadores, reglas complejas de red, etc.).
Modularización para soportar AWS, GCP u on-premises.
Plugin system para integración externa (ej.: monitoreo, alertado, reporting web).
Exportación y sincronización de estado de ambientes.
Integración con procesos CI/CD o API REST.

7. Ejemplo de Flujo de Uso

Usuario elabora archivo HCL con definición de entorno.
Corre el comando plan para simular y ver qué recursos serán creados.
Corre el comando apply para ejecutar el despliegue.
El sistema despliega los recursos en Azure en el orden y configuración requeridos.
Acciones y estados quedan registrados en logs.
Futuro: Posibilidad de destruir el entorno (destroy), visualizar estado, o integrarse con otros sistemas.

8. Restricciones Iniciales

En MVP no se consideran recursos fuera de VM y redes asociadas.
Sin integración con herramientas externas al inicio.
Rollback/destrucción manual en primeras versiones (funcionalidad destrucción (“destroy”) podría entrar en segunda fase).
Compatibilidad HCL total, JSON a considerar según prioridad de usuarios.

Esta estructura te permitirá guiar tanto el desarrollo técnico como la gestión del proyecto y la documentación, asegurando claridad en los entregables, trazabilidad de los alcances y apertura para evoluciones futuras.

19 June 2025