Empecé queriendo tener el rol de administrador en Microsoft 365 Lighthouse y acabé con un portal de autoservicio en el que el usuario del cliente pide la tarea, su responsable la aprueba con un clic desde el correo y la tarea se ejecuta sola en el tenant del cliente vía GDAP.

Esta es la historia de cómo llegué hasta ahí, con las decisiones, los callejones sin salida y los errores que me encontré por el camino.

La regla que me impuse: solo lectura hasta entender lo que hay

Antes de tocar nada en un entorno con decenas de clientes, todo lo que hice durante los primeros días fue de solo lectura: auditar, sondear APIs y medir. Solo cuando entendí el modelo de permisos pasé a escribir, y siempre primero en un tenant de laboratorio.

Y toda afirmación técnica, contrastada con Microsoft Learn. Para eso conecté el MCP oficial de Microsoft Learn a Claude y le pedí que cada respuesta viniera con su fuente. Varias veces me salvó de dar por buena una suposición.

Fase 0: dos capas de permisos que se confunden

Lo primero que aprendí es que en Lighthouse hay dos capas de permisos independientes, y casi todo el mundo las mezcla:

El rol RBAC de Lighthouse no da acceso a los datos del cliente. Si un técnico “no puede hacer X” sobre un cliente, casi siempre falta un rol en la relación GDAP o la pertenencia a un grupo, no un rol de Lighthouse.

Dos detalles que conviene saber antes de pedir permisos:

• El rol Administrador de Lighthouse concede automáticamente Administrador de roles con privilegios, Administrador de usuarios y Administrador de grupos en Entra ID, y Admin Agent en Partner Center. No es un rol para repartir a la ligera.
• Solo se puede asignar a un grupo con asignación de roles (requiere Entra ID P1). Cuando me ofrecieron reutilizar grupos existentes, resultó que eran de Azure Lighthouse, otro producto distinto. Usar uno de ellos habría dado control de GDAP sobre todos los clientes a gente que solo gestionaba Azure Arc. Creamos un grupo dedicado.

Fase 1: auditar lo que ya existe

Con el rol asignado, lo primero fue saber qué había. Escribí un script de PowerShell de solo lectura que vuelca a CSV las relaciones GDAP, sus asignaciones a grupos con los miembros de cada grupo, los tenants que ve Lighthouse y la directiva de costes de cada cliente:

Connect-MgGraph -TenantId $partnerTenantId -NoWelcome -Scopes @(
  'DelegatedAdminRelationship.Read.All', 'ManagedTenants.Read.All',
  'GroupMember.Read.All', 'RoleManagement.Read.Directory')

$rels = (Invoke-MgGraphRequest GET `
  "https://graph.microsoft.com/v1.0/tenantRelationships/delegatedAdminRelationships" -OutputType PSObject).value

Lo que conviene buscar en una auditoría así:

• Global Administrator permanente. Microsoft desaconseja sustituir GA por la suma de todos los roles, y además una relación con GA no admite auto-extensión: caduca y hay que volver a pedir la aprobación del cliente.
• Segregación de funciones. Si los grupos de soporte y de administración tienen exactamente los mismos roles, en la práctica no hay segregación.
• Caducidades próximas y relaciones activas sin ningún grupo asignado (que nadie puede usar).
• Solicitudes pendientes: caducan a los 90 días si el cliente no las aprueba.

La conclusión fue incómoda pero útil: antes de vender un servicio basado en accesos delegados, hay que ordenar los propios accesos. No se puede ofrecer un informe de transparencia de accesos al cliente con un modelo de permisos desordenado.

Fase 2: la visibilidad de costes, que era lo más fácil

Esta era la queja comercial más repetida. Resulta que un partner puede activar, cliente a cliente, una directiva que permite al cliente ver Cost Management en su propio tenant. Está en el portal de Azure, en la cuenta Microsoft Partner Agreement, en Clientes > cliente > Directivas, y también por API:

$body = @{ properties = @{ viewCharges = "Allowed" } } | ConvertTo-Json
Invoke-AzRestMethod -Method PUT `
  -Path "/providers/Microsoft.Billing/billingAccounts/$ba/customers/$customer/policies/default?api-version=2020-05-01" `
  -Payload $body

Con trampa: el cliente ve los costes a precio de lista (PAYG), sin descuentos ni créditos del partner, y el uso de reservas aparece a coste cero. La función de markup de Cost Management solo existe para EA indirectos y para Azure operado por 21Vianet, no para CSP.

Para enseñar al cliente su precio real hay que exportar los costes desde el tenant del partner y aplicar el precio en un informe propio. Aun así, activar la directiva ya resuelve buena parte de la queja.

Dos tropiezos de portal que me hicieron perder tiempo:

• La entrada Clientes solo aparece en la cuenta de tipo Microsoft Partner Agreement. En mi lista había dos cuentas con el mismo nombre, una MPA y otra MCA, y estaba entrando en la que no era.
• Para cambiar la directiva hay que ser Admin Agent. Ver la cuenta como administrador global no basta.

Fase 3: qué se puede hacer de verdad con Lighthouse por API

Lighthouse tiene una API en Microsoft Graph (/beta/tenantRelationships/managedTenants), pero está en beta y solo admite permisos delegados. En lugar de fiarme de la documentación, escribí un sondeo que llama a cada colección y anota qué responde:

Conclusión: por API, Lighthouse sirve para leer la postura de seguridad, no para aplicar configuraciones. Las baselines se despliegan desde el portal.

Además, Lighthouse solo gestiona por completo los tenants que cumplen sus requisitos: GDAP, al menos una suscripción de Microsoft 365 o similar, hasta 2.500 usuarios con licencia y misma región que el partner. El resto se queda en una experiencia limitada. En mi caso, la mayoría de tenants no eran aptos, y los de laboratorio tampoco, porque no tenían licencias de M365.

Y dos matices al leer los datos de MFA:

• El informe de registro de MFA requiere Entra ID P1 en el cliente. Un tenant Free que aparece con cero registros no significa que no tenga MFA: significa que no hay datos.
• El indicador de Lighthouse solo mira acceso condicional y security defaults. No detecta el MFA por usuario (el método heredado), que sí funciona sin licencia y se puede leer en Graph con perUserMfaState.

Fase 4: Graph con GDAP desde mi propia app

El siguiente paso era actuar, no solo leer. Mi primera prueba con Microsoft Graph Command Line Tools contra un tenant cliente falló. La razón: con GDAP, la app que usa el técnico tiene que estar autorizada en el tenant del cliente.

La solución fue registrar en el tenant del partner una app multi-tenant, cliente público, solo con permisos delegados. La app no puede hacer nada por sí misma: todo queda limitado a los roles GDAP del técnico que inicia sesión.

$appId = az ad app create --display-name "app-l0agent-gdap-cli" `
  --sign-in-audience AzureADMultipleOrgs `
  --public-client-redirect-uris http://localhost `
  --is-fallback-public-client true --query appId -o tsv

La app se consiente en cada cliente. En el laboratorio lo hice con la URL de admin consent y la cuenta de administrador del tenant; con clientes reales se hace con la API de consentimiento de Partner Center.

Y aquí el primer aprendizaje importante: cada permiso nuevo exige volver a consentir la app en cada cliente. Si no, aparece este error al iniciar sesión:

AADSTS90099: The application '<app-id>' has not been authorized in the tenant '<tenant-id>'.
Applications must be authorized to access the customer tenant before partner delegated administrators can use them.

Un técnico vía GDAP no puede conceder el consentimiento al vuelo como haría un usuario normal. Por eso conviene definir desde el principio el conjunto de permisos del catálogo completo.

Con la app consentida, el patrón es sencillo: me conecto con mi cuenta del partner, pero apuntando al tenant del cliente:

Connect-MgGraph -ClientId $appId -TenantId $customerTenantId -Scopes "User.Read.All"
Get-MgContext | Select-Object Account, TenantId   # mi cuenta del partner, en el tenant del cliente

Fase 5: las primeras tareas reales

Cambio de contraseña

La más sencilla: un PATCH sobre el usuario con passwordProfile y forceChangePasswordNextSignIn. Funcionó a la primera, y en los registros de auditoría del cliente aparece mi cuenta del partner como autora del cambio.

Móvil nuevo: reseteo de MFA

Es uno de los tickets más habituales. El flujo que buscaba: borrar los métodos MFA antiguos, emitir un Temporary Access Pass (TAP) de un solo uso y cerrar las sesiones, para que el usuario registre Authenticator en el móvil nuevo.

La primera ejecución falló con este error:

Cannot delete default method with other methods configured. Please change default method before deletion.

La API no deja borrar el método predeterminado mientras queden otros. La solución fue borrar en varias pasadas: primero lo que se puede, y el predeterminado al final, cuando ya es el último.

for ($pass = 1; $pass -le 4; $pass++) {
  Start-Sleep -Seconds 5   # margen para la replicación
  $pending = @(Get-AuthMethods | Where-Object { $segment.ContainsKey($_.Tipo) })
  if ($pending.Count -eq 0) { break }
  foreach ($m in $pending) {
    try   { Invoke-MgGraphRequest DELETE "$base/$($segment[$m.Tipo])/$($m.id)" -ErrorAction Stop | Out-Null }
    catch { }   # 400: es el predeterminado, siguiente pasada · 404: ya borrado
  }
}

Esa misma prueba destapó otro comportamiento: la consistencia eventual. Un teléfono recién añadido no aparecía en el siguiente listado, y un método recién borrado seguía apareciendo unos segundos después. Cualquier automatización tiene que reintentar y verificar el estado final, no fiarse de la primera respuesta, y distinguir un 404 (ya hecho) de un 400 (regla de negocio).

Fase 6: de ejecutar tareas a autorremediar

Con las piezas probadas, cambié el enfoque: no solo atender lo que pide el usuario, sino detectar la necesidad del cliente y corregirla sola. Monté un pequeño motor de reglas, cada una con el ciclo detectar → remediar → verificar → dejar evidencia:

Con modo informe, simulación (-WhatIf) y remediación, y tres salvaguardas que no se saltan nunca: no actuar sobre usuarios con roles de administrador, ni sobre un grupo de exclusión, ni sobre usuarios sincronizados desde AD local (su contraseña vive en el AD, no en la nube).

Fase 7: el portal para el cliente

Lo que buscaba al final era que el cliente pudiera pedirlo sin abrir un ticket. La primera versión del portal tenía un fallo de concepto: todo ocurría con identidades del partner. Yo pedía, yo aprobaba y yo ejecutaba. Al enseñárselo a mi jefe la pregunta fue obvia: “¿y el cliente dónde está?”.

La versión buena separa tres identidades:

flowchart LR
    A[Usuario del cliente<br/>inicia sesión con su cuenta<br/>y pide la tarea] --> B[Responsable del cliente<br/>recibe el correo<br/>y aprueba]
    B --> C[Portal del partner<br/>comprueba usuario, roles<br/>y aislamiento]
    C -->|GDAP| D[Tenant del cliente<br/>Graph aplica el cambio<br/>y queda auditado]
    C -.->|contraseña temporal o TAP| B

• El cliente pide y aprueba con su propia cuenta, mediante una segunda app que solo tiene User.Read. Nunca toca la app que ejecuta.
• El partner ejecuta con su identidad GDAP. En la demo, mi sesión iniciada una vez al arrancar; en producción, una cuenta de servicio con su propio grupo GDAP de roles mínimos y su token protegido en Key Vault, que es el patrón que Microsoft documenta para aplicaciones de partners.
• Los responsables se eligen según el usuario afectado: lista explícita para ese usuario, después su departamento, después su manager en Entra ID y, si no hay ninguno, los responsables por defecto. Se avisa a todos y basta con que apruebe uno.

Y las reglas de seguridad que considero no negociables:

• El cliente se deduce del tenant de quien inicia sesión, nunca de un desplegable. Un usuario solo puede pedir tareas sobre usuarios de su propia organización.
• Solo entran los tenants dados de alta: una app multi-tenant admite, en principio, cualquier cuenta de Entra ID.
• Nadie aprueba su propia solicitud ni una que le afecte.
• El enlace del correo no aprueba nada por sí mismo: abre una página de revisión con los botones. Así los escáneres de enlaces del correo no pueden aprobar solicitudes al abrir el mensaje.
• La contraseña temporal o el TAP solo llegan al responsable que aprueba. No se guardan ni se muestran en pantalla.

El resultado: la usuaria pide el cambio de contraseña, al responsable le llega el correo, lo aprueba, recibe la contraseña temporal y, cuando la usuaria entra, Entra ID le obliga a cambiarla. Con el reseteo de MFA, recibe el TAP y registra Authenticator en el móvil nuevo. Todo sin que intervenga un técnico.

Lo que aprendí por el camino

Los errores, otra vez, fueron lo más instructivo:

1. Un token obtenido de la caché no trae los datos de identidad. Al aprobar, MSAL reutilizaba la sesión anterior sin id_token_claims, el portal no sabía quién era el aprobador y lo rechazaba. La identidad hay que tomarla de la cuenta en caché.
2. 127.0.0.1 y localhost no son lo mismo para el navegador. Flask anuncia una dirección, Entra ID devuelve el inicio de sesión a la otra, la cookie de sesión no viaja y el login falla con un 400. Ahora el portal fuerza siempre la misma dirección.
3. Un ID de ejemplo en la configuración (<APP_ID_DEL_FRONT>) produce un AADSTS90013 poco descriptivo. Validar la configuración al arrancar ahorra tiempo.
4. La demo se rompe si la usuaria y el responsable usan la misma ventana. El portal ve a la usuaria intentando aprobar y, con razón, la rechaza. Añadí un botón de “Cambiar de cuenta” y, en las demos, siempre ventanas privadas distintas.
5. Un tenant de laboratorio sin licencias no tiene buzones. Los responsables necesitan un correo de aviso distinto de su cuenta de inicio de sesión.
6. El cambio de contraseña del propio usuario ya lo resuelve Microsoft con SSPR. Es la mejor tarea para una demo porque se entiende al instante, pero el valor del producto está en lo que SSPR no cubre: aprobaciones, móvil nuevo, altas y bajas, o un compañero que pide por quien no puede iniciar sesión.

Lo que queda

La demo funciona en mi equipo. Para que sea un servicio faltan tres cosas: la cuenta de servicio con su grupo GDAP de roles mínimos, el despliegue en Azure (Container Apps, Key Vault y una base de datos, con Terraform) y ordenar los accesos GDAP antes del primer cliente piloto.

Después, ampliar el catálogo. Con los roles GDAP habituales de un partner hay más de veinticinco tareas de Entra ID posibles: altas y bajas, licencias, grupos, invitados, inventario de privilegiados, secretos de aplicaciones a punto de caducar. Y con licencias de laboratorio, el salto a Exchange, Teams, SharePoint e Intune.

Reflexión final

Lo que más me ha enseñado este trabajo es que el problema no era técnico, era de modelo de identidad. Graph, GDAP y Lighthouse ya estaban ahí. Lo difícil fue decidir quién pide, quién aprueba y quién ejecuta, y que cada una de esas identidades tenga solo los permisos que necesita.

La automatización ejecuta la tarea en segundos. Pero la aprobación sigue siendo humana, y la responsabilidad sobre los accesos al tenant de un cliente también.

Si tienes preguntas sobre el modelo o quieres los scripts, puedes contactarme en luisadanmunoz@outlook.com.

Decidí ponerle orden con Obsidian, pero sin quedarme en “instalo plugins y a ver qué pasa”. Quería un sistema enterprise: versionado, con guardarraíles de seguridad, convenciones estrictas y conectado a Claude Code para que la IA pudiera consultar y escribir en él con las mismas reglas que yo.

Esta es la guía de cómo lo monté paso a paso, con las decisiones que tomé y, sobre todo, con los errores que cometí por el camino.

La regla que me impuse: no pasar de paso sin validar el anterior

El plan final tuvo 35 pasos agrupados en 8 fases. La disciplina fue sencilla: cada paso terminaba con una prueba verificable (un comando, una nota de prueba, una captura) y no avanzaba hasta que salía bien.

Suena lento, pero me ahorró horas. Varios de los problemas que cuento al final los detecté justo porque la prueba del paso falló.

Fase 0: las decisiones que condicionan todo

Antes de crear una sola carpeta tuve que decidir cuatro cosas. Y reconozco que cambié de opinión en la más importante.

Uno o dos vaults. Empecé diseñando dos vaults: uno “conectable” (Azure, IA, SysOps) enlazado a Claude y GitHub, y otro “cerrado”, solo local, para el material de clientes. Al avanzar vi que la separación me costaba más de lo que me aportaba, y acabé en un vault único, versionado en un repo privado de GitHub y conectado a Claude.

Si te planteas lo mismo, mi consejo es no decidirlo a la ligera: revisa qué dicen tus contratos y la política de tu empresa sobre almacenar datos de cliente en GitHub y procesarlos con IA. Esa decisión es tuya, no de la herramienta.

Binarios fuera de Git. Los pptx, xlsx, docx, pdf y zip no se versionan. Git está pensado para texto, y los binarios hacen crecer el repo sin aportar nada útil al historial. Los protejo con una copia de seguridad aparte.

Repos de código fuera del vault. Probé a meter los repos dentro de las carpetas de cliente, con su propio .git, y acabé sacándolos: cada repo vive en su sitio y desde las notas enlazo a su URL de GitHub.

Motor de consultas: Bases + Tasks. Bases es un plugin core de Obsidian: no añade código de terceros y trabaja directamente sobre las propiedades del frontmatter, que es donde está toda mi información estructurada. Tasks cubre lo que Bases no hace bien, que son las tareas sueltas dentro de las notas.

Fase 1: cimientos

Estructura de carpetas

Tras varias iteraciones, la estructura quedó así:

Vault-Consultoria/
├── 00-SysOps/          # Chuletas: AzCli, KQL, Docker, Kubernetes, Git, Terraform, PowerShell
├── 01-Azure/
│   ├── 01-Recursos/    # Un servicio de Azure por nota, agrupados por categoría
│   └── 02-Certificaciones/   # Una carpeta por certificación con sus apuntes
├── 02-Terraform/       # Un recurso azurerm por nota, mismas categorías
├── 03-IA/              # 01-MVP · 02-Skills · 03-Casos-de-Uso
├── 04-Clientes/<Cliente>/   # 01-Ofertas · 02-Proyectos · 03-Documentacion-Cliente · 04-Reuniones
├── 98-Documentos/      # Web-Clipper, Diagramas, Iconos-Azure
└── 99-Plantillas/      # Convenciones, registro de plugins, plantillas de Templater

Dos lecciones de diseño:

• Todo con guiones, sin tildes ni espacios. Las rutas pasan por Git, PowerShell y Claude Code, y cada carácter raro es un problema potencial.
• Numeración correlativa. Parece una manía, pero cuando quité una subcarpeta de cliente y quedó un hueco en la numeración, preferí renumerar. Eso me obligó a actualizar el router de plantillas y las convenciones, y fue la mejor prueba de que todo estaba bien acoplado.

Toda la estructura se crea con un script de PowerShell idempotente: lo puedo relanzar para añadir un cliente o una certificación sin tocar lo que ya existe.

Git + Gitleaks: la red de seguridad

Si el vault se sube a GitHub, un secreto pegado por descuido en una nota acaba en internet. Por eso el primer guardarraíl fue un hook pre-commit con Gitleaks, que bloquea cualquier commit que contenga algo con aspecto de credencial:

$hook = "#!/bin/sh`ngitleaks git --pre-commit --staged --redact -v`n"
[IO.File]::WriteAllText("$PWD\.git\hooks\pre-commit", $hook)

Lo probé con un token falso con formato de GitHub, y Gitleaks lo detectó, lo tapó (REDACTED) y abortó el commit. Justo lo que quería.

Y al día siguiente me bloqueó a mí. Al subir la carpeta .obsidian/plugins, Gitleaks encontró “API keys” en el main.js minificado de un plugin: eran falsos positivos. La solución no fue silenciar a Gitleaks, sino no versionar el código de los plugins, que se reinstala desde la tienda, y quedarme solo con su configuración:

.obsidian/plugins/*/*
!.obsidian/plugins/*/manifest.json
!.obsidian/plugins/*/data.json

El repo pasó de 22 MB a unos pocos KB, y Gitleaks sigue vigilando los data.json, que es donde de verdad podría colarse un secreto.

Otras exclusiones que no deberían faltar en ningún vault con código: *.tfstate, *.tfplan, .terraform/, *.env, *.pfx, *.pem y *.key. El state de Terraform puede contener secretos en claro.

Fase 2: convenciones antes que contenido

Este es el paso que más me costó y el que más valor aporta: definir el esquema antes de escribir una sola nota. Si cargas contenido primero, luego te toca rehacer el frontmatter a mano.

Definí 14 tipos de nota, cada uno con sus campos y sus estados válidos. Un extracto:

Los campos verificado y fuente son los que más aprecio. Azure cambia constantemente, así que cada nota técnica registra con qué URL oficial y en qué fecha se validó. Una vez al mes reviso las notas con más de seis meses.

Completé el esquema con dos reglas más:

• Nombres: Git - Deshacer ultimo commit, azurerm_key_vault, 2026-09-23 Oferta Cliente Landing Zone. La fecha va delante en todo lo que ocurre en un momento concreto.
• Tags en lista cerrada, agrupados por pilares WAF, metodologías CAF, herramienta e IA. Un tag nuevo solo existe si antes lo añado a la tabla. Así evito tener #terraform, #Terraform y #tf conviviendo.

Todo vive en una nota, 99-Plantillas/Convenciones.md, que es la fuente de verdad para mí y, como veremos, también para Claude.

Fase 3: plugins y plantillas

Pocos plugins y con registro

Instalé 14 plugins de la comunidad. Todos son código de terceros con acceso completo al vault, así que los gobierno como gobernaría dependencias en un proyecto:

• Un script genera Registro-Plugins.md leyendo el manifest.json de cada plugin: nombre, versión, autor y para qué lo uso.
• Nunca pulso “Actualizar todo”. Actualizo de uno en uno, revisando antes el changelog.
• Antes de instalar uno, reviso sus descargas y su fecha de última actualización.

El router de Templater: la pieza clave

Templater permite asignar una plantilla por carpeta, pero no admite comodines. Eso choca con rutas como 04-Clientes/<cualquier cliente>/01-Ofertas.

La solución fue una única plantilla “router” asignada a todo el vault, que mira dónde se ha creado la nota y aplica la plantilla que le corresponde:

<%*
const p = tp.file.folder(true);
const s = p.split("/");
let t = null;
if (s[0] === "00-SysOps" && s.length >= 2) t = "chuleta";
else if (p.startsWith("01-Azure/01-Recursos/")) t = "recurso-azure";
else if (p.startsWith("01-Azure/02-Certificaciones/")) t = "apunte";
else if (s[0] === "02-Terraform" && s.length >= 2) t = "modulo-terraform";
else if (s[0] === "04-Clientes" && s[2] === "01-Ofertas") t = "oferta";
// ...resto de tipos
if (tp.file.title.endsWith(".excalidraw")) t = null;
if (t) { tR += await tp.file.include("[[99-Plantillas/Templater/T-" + t + "]]"); }
-%>

Además, cada plantilla deduce campos de la ruta. Si creo una nota en 00-SysOps/05-Git, aparece sola con tipo: chuleta y herramienta: Git. Si la creo en la carpeta de una certificación, sale con tipo: apunte y el código de la certificación ya relleno.

La línea de .excalidraw la añadí más tarde, al darme cuenta de que el router aplicaría la plantilla de documento dentro de los ficheros de Excalidraw y los rompería.

Linter, Git automático y Web Clipper

• Linter, con solo dos reglas: mantener actualizado al día y normalizar los tags. Con la carpeta de plantillas excluida, porque si no “corrige” los bloques <% %> de Templater.
• Plugin Git: commit y push automáticos 15 minutos después de dejar de editar. El hook de Gitleaks también se ejecuta en esos commits.
• Obsidian Web Clipper en Chrome, apuntando a 98-Documentos/Web-Clipper con propiedades alineadas con mi esquema. Capturo documentación de Microsoft Learn con un clic y luego la muevo a su sitio.

Fase 5: explotación

Dashboard con Bases

Una nota Inicio se abre al arrancar Obsidian con vistas de Bases incrustadas: ofertas abiertas agrupadas por cliente, proyectos en curso, MVP de IA activos, certificaciones en curso y todo lo que está en borrador pendiente de revisar.

filters:
  and:
    - 'tipo == "oferta"'
    - or:
        - 'estado == "borrador"'
        - 'estado == "enviada"'
views:
  - type: table
    name: Ofertas abiertas
    groupBy:
      property: cliente
      direction: ASC

Como todo se alimenta del frontmatter, el dashboard nunca se desincroniza.

Por qué no usé Kanban para las ofertas

Pensé en un tablero Kanban de ofertas, pero lo descarté: mover una tarjeta de “Enviada” a “Ganada” no cambia el estado de la nota de la oferta. Tendría el estado duplicado en dos sitios, y tarde o temprano el tablero y el dashboard dirían cosas distintas. Kanban quedó solo como tablero de trabajo personal, sin ligarlo a propiedades.

Flashcards, diagramas y enlaces

• Spaced Repetition: cada apunte de certificación lleva una sección de flashcards, y cada certificación se convierte automáticamente en un mazo.
• Excalidraw con los iconos oficiales de Azure, descargados del Azure Architecture Center. Microsoft permite usarlos en diagramas de arquitectura, formación y documentación. Los excluyo de Git porque se pueden volver a descargar.
• Sección ## Relacionado en las plantillas, para enlazar un recurso con su módulo Terraform, sus chuletas y los proyectos donde lo usé. El panel de enlaces entrantes hace el resto.

Fase 6: Claude Code como coautor del vault

Esta era la parte que más me interesaba. Descarté la vía del plugin Local REST API con MCP: Claude Code trabaja directamente sobre los ficheros, así que no necesitaba ni plugin ni puerto abierto ni API key.

CLAUDE.md: las reglas de la casa

En la raíz del vault hay un CLAUDE.md que Claude Code carga en cada sesión. Resumido:

• Leer Convenciones.md antes de crear o editar nada.
• Ubicar cada nota según su tipo, usar la plantilla correspondiente sustituyendo las expresiones de Templater y escribir la nota completa de una vez. Si creara un fichero vacío, Templater le aplicaría su plantilla encima.
• Rigor técnico: toda afirmación sobre Azure, respaldada por Microsoft Learn, con fuente y verificado rellenos. Si no puede verificar algo, lo dice y añade el tag revisar. Nada de inventar límites, SKUs ni precios.
• Prohibido sin confirmación: borrar o mover notas, tocar la configuración, hacer commits y mezclar información entre clientes.

Permisos: defensa en profundidad

El CLAUDE.md son instrucciones. Los permisos son la segunda capa:

{
  "permissions": {
    "deny": [
      "Edit(./.obsidian/**)",
      "Edit(./.git/**)",
      "Edit(./99-Plantillas/**)",
      "Bash(git commit:*)",
      "Bash(git push:*)"
    ],
    "ask": ["Bash(Remove-Item:*)", "Bash(Move-Item:*)"]
  }
}

Cuando probé a pedirle “haz commit y push”, Claude Code lo intentó y el permiso lo bloqueó. Aun así, no trato estas reglas como una barrera infalible: la red de seguridad real sigue siendo Git más Gitleaks.

MCP de Microsoft Learn

Para que la regla de “verificar contra Microsoft Learn” tenga una fuente real detrás, conecté el MCP oficial a nivel de proyecto:

claude mcp add --transport http --scope project microsoft-learn https://learn.microsoft.com/api/mcp

Un detalle de seguridad: Claude Code también cargó mis conectores de claude.ai (correo, calendario, Drive). Los desactivé para este proyecto. No quiero que el contenido de mi correo acabe volcado en una nota que se sube a GitHub.

La prueba de fuego

Le pedí: “Crea la nota del recurso Azure Key Vault verificando los datos en Microsoft Learn”. Buscó en la documentación oficial, creó la nota en 01-Azure/01-Recursos/Security con el frontmatter completo, la fuente enlazada y la fecha de verificación. Días después, al preguntarle por los límites de Key Vault, respondió desde mi propia nota, citando la fuente, sin volver a buscar en internet.

Eso es exactamente lo que quería: un segundo cerebro que se alimenta de fuentes oficiales y al que puedo consultar en lenguaje natural.

Fase 7: mantenimiento

Un sistema sin mantenimiento se degrada, así que lo automaticé con tareas recurrentes de Tasks que aparecen solas en el dashboard:

• Cada viernes: vaciar las capturas del Web Clipper, actualizar los estados de ofertas y proyectos, lanzar la copia de binarios y comprobar que Git está limpio.
• El día 1 de cada mes: revisar borradores, reverificar notas antiguas, revisar plugins y tags, y archivar clientes inactivos.

La copia de binarios es un script con robocopy que nunca borra en destino: si un fichero desaparece del portátil por error, la copia lo conserva. La validé como se debe validar una copia de seguridad, restaurando un fichero y comparando su hash con el original. Una copia que no se ha restaurado nunca no es una copia.

Lo que aprendí por el camino

Los errores fueron lo más instructivo:

1. Algunos ajustes de Obsidian no viven en data.json. El disparador de Templater al crear notas se guarda por dispositivo, así que mi script de configuración no podía activarlo. Tuve que hacerlo a mano.
2. Una regla de Linter configurada no sirve si su interruptor principal está apagado. La prueba del paso lo destapó en segundos.
3. Hacer clic en un enlace a una nota que no existe la crea en la carpeta actual, con la plantilla equivocada. Ahora mi regla es: primero creo la nota en su sitio y después la enlazo.
4. Pegar un bloque de prueba dentro del propio script crea un bucle infinito: el script se llama a sí mismo. Me pasó, y me hizo pensar que la unidad de red estaba colgada.
5. Las unidades de red mapeadas no existen en todas las sesiones. Uso siempre la ruta UNC en los scripts.
6. PowerShell 5.1 y la codificación UTF-8. Las tildes rotas y la marca BOM en un JSON me recordaron que para estos scripts hay que usar PowerShell 7.

Reflexión final

Lo que más valor me ha dado no ha sido ningún plugin, sino decidir las convenciones antes del contenido y validar cada paso antes de avanzar. Con un esquema claro, las plantillas, el dashboard y Claude trabajan sobre la misma estructura y no se contradicen.

La IA escribe notas, verifica contra la documentación oficial y responde a mis preguntas. Pero las reglas del vault las decidí yo, y la última revisión antes de usar cualquier dato con un cliente sigue siendo humana.

Si tienes preguntas sobre la configuración o quieres los scripts, puedes contactarme en luisadanmunoz@outlook.com.

~15 MB de JSON. Un índice en memoria. Cero alucinaciones de atributos. Así funciona el SchemaManager.

Si llegaste desde el post anterior, ya sabes que el Paso 1 definió los contratos de datos entre agentes. Este post cubre el Paso 2: el componente que convierte el schema real del provider azurerm en la única fuente de verdad que el Builder puede consultar.

El Paso 2 tampoco llama a ningún LLM. Tampoco toca Azure. Pero sin él, todo lo que venga después es frágil.

El problema concreto

Los LLMs cometen un tipo de error muy específico cuando generan Terraform: inventan atributos que no existen o usan nombres de versiones anteriores del provider.

Algunos ejemplos reales con azurerm 4.x:

# ❌ enable_https_traffic_only fue renombrado en azurerm 3.x
resource "azurerm_storage_account" "main" {
  enable_https_traffic_only = true  # no existe en 4.x
}

# ❌ address_prefix no existe en azurerm_virtual_network
resource "azurerm_virtual_network" "main" {
  address_prefix = "10.0.0.0/16"  # el atributo es address_space (lista)
}

# ❌ subnet inline está deprecated
resource "azurerm_virtual_network" "main" {
  subnet {
    name           = "snet-app"
    address_prefix = "10.0.1.0/24"
  }
}

Ninguno de estos errores se detecta en el prompt. Se detectan en terraform validate, que es la cuarta etapa del pipeline de revisión. Si el Builder llega hasta ahí antes de enterarse, ha desperdiciado tres etapas y una iteración completa del bucle de reintentos.

El SchemaManager mueve esa detección al origen: antes de generar una sola línea de HCL.

Qué se construyó

Un módulo Python con tres modelos internos y una interfaz pública de ocho métodos:

schema/
├── schema_manager.py        # módulo principal
└── azurerm_4_0.json         # generado con terraform providers schema -json (~15 MB)

tests/
└── schema/
    ├── test_schema_manager.py
    └── fixtures/
        └── azurerm_minimal.json  # 3 recursos para CI, sin depender del JSON real

Cómo funciona por dentro

El JSON que produce terraform providers schema -json tiene esta estructura para cada recurso:

{
  "provider_schemas": {
    "registry.terraform.io/hashicorp/azurerm": {
      "resource_schemas": {
        "azurerm_virtual_network": {
          "version": 0,
          "block": {
            "attributes": {
              "address_space": { "type": ["list","string"], "required": true },
              "location":      { "type": "string", "required": true },
              "id":            { "type": "string", "computed": true }
            },
            "block_types": {
              "ddos_protection_plan": { "nesting_mode": "list", "block": {...} }
            }
          }
        }
      }
    }
  }
}

El SchemaManager carga este JSON una sola vez en __init__, navega hasta resource_schemas y construye un índice en memoria. Cada recurso se convierte en un objeto ResourceSchema con cuatro colecciones ya clasificadas:

@dataclass
class ResourceSchema:
    resource_type: str
    required_attributes:      dict[str, AttributeSchema]
    optional_attributes:      dict[str, AttributeSchema]
    computed_only_attributes: dict[str, AttributeSchema]
    blocks:                   dict[str, BlockSchema]

    def summary(self) -> dict:
        """Versión compacta para prompts del Builder."""
        return {
            "required_attributes":      list(self.required_attributes.keys()),
            "optional_attributes":      list(self.optional_attributes.keys()),
            "computed_only_attributes": list(self.computed_only_attributes.keys()),
            "required_blocks":          [k for k,v in self.blocks.items() if v.required],
            "optional_blocks":          [k for k,v in self.blocks.items() if not v.required],
        }

El Builder no recibe el JSON crudo. Recibe summary(): una lista de nombres. Con eso tiene suficiente para saber qué puede usar, qué es obligatorio y qué no debe tocar porque es computed_only.

Las decisiones no obvias

1. SchemaError en lugar de None para recursos inexistentes

La primera versión devolvía None si un recurso no existía en el schema. El problema: cada caller tenía que manejar el caso nulo.

# ❌ con None — el error puede propagarse silenciosamente
schema = sm.get_resource_schema("azurerm_nonexistent")
if schema:
    attrs = schema.required_attributes  # nunca llega aquí
# pero nadie se entera del fallo hasta más tarde

# ✅ con SchemaError — el fallo es inmediato y trazable
try:
    schema = sm.get_resource_schema("azurerm_nonexistent")
except SchemaError as e:
    # e.resource_type = "azurerm_nonexistent"
    # el contexto está en la excepción

SchemaError hereda de la jerarquía de excepciones del sistema y lleva resource_type como atributo. El Orquestador puede capturarla, loguearla con pipeline_id y escalar al usuario sin perder contexto.

2. Carga única con índice en memoria

El JSON se parsea una sola vez en __init__. Las consultas posteriores son búsquedas en un dict Python: O(1).

La alternativa —leer el JSON en cada consulta— parece más “pura” pero introduce latencia variable en el hot path del Builder. Con ~847 recursos y un JSON de 15 MB, la primera carga tarda ~2-3 segundos. Cada consulta posterior tarda microsegundos.

3. Normalización de tipos

El schema de Terraform representa los tipos como listas anidadas:

"type": ["list", "string"]
"type": ["map", "number"]
"type": ["object", {"ip_configuration": [...]}]

El SchemaManager normaliza esto a strings legibles antes de exponerlo:

["list", "string"]          → "list(string)"
["map", "number"]           → "map(number)"
["object", {"a": ..., "b": ...}] → "object(a, b)"

El Builder trabaja con "list(string)", no con ["list", "string"]. Es un detalle pequeño con impacto grande en la legibilidad de los prompts y en los tests.

4. Fixture minimal para CI

Los tests no dependen del JSON real de 15 MB. Un fixture de 3 recursos cubre toda la interfaz pública:

• azurerm_resource_group — recurso simple, solo atributos
• azurerm_virtual_network — recurso con bloques anidados
• azurerm_storage_account — recurso con atributos sensitive y computed

Esto permite ejecutar la suite completa en CI en menos de un segundo, sin Terraform instalado, sin descargar el provider, sin conexión a internet.

La interfaz completa

from schema import SchemaManager

sm = SchemaManager("schema/azurerm_4_0.json")

# Cuántos recursos hay
print(sm.resource_count)  # 847

# Existe un recurso?
sm.resource_exists("azurerm_virtual_network")  # True
sm.resource_exists("azurerm_nonexistent")       # False

# Schema completo
schema = sm.get_resource_schema("azurerm_virtual_network")
schema.required_attributes   # {"address_space": AttributeSchema(...), ...}
schema.optional_attributes   # {"bgp_community": ..., "dns_servers": ..., ...}
schema.computed_only_attributes  # {"id": ..., "guid": ...}
schema.blocks                # {"ddos_protection_plan": BlockSchema(...), ...}

# Resumen para prompts
sm.get_summary("azurerm_virtual_network")
# {
#   "required_attributes": ["address_space", "location", "name", "resource_group_name"],
#   "optional_attributes": ["bgp_community", "dns_servers", "tags", ...],
#   "computed_only_attributes": ["guid", "id"],
#   "required_blocks": [],
#   "optional_blocks": ["ddos_protection_plan", "encryption", "timeouts"]
# }

Con summary(), el Builder puede construir un prompt del tipo:

“Genera HCL para azurerm_virtual_network. Atributos requeridos: address_space, location, name, resource_group_name. No incluyas atributos computed_only: guid, id.”

El LLM no adivina. Trabaja con una lista exacta extraída del schema real del provider.

Cómo replicarlo

# 1. Generar el JSON del provider (solo la primera vez)
mkdir -p schema
cd /tmp && cat > provider.tf << 'EOF'
terraform {
  required_providers {
    azurerm = { source = "hashicorp/azurerm", version = "~> 4.0" }
  }
}
provider "azurerm" { features {} }
EOF
terraform init
terraform providers schema -json > /ruta/proyecto/schema/azurerm_4_0.json

# 2. Añadir a .gitignore (no commitear los 15 MB)
echo "schema/azurerm_4_0.json" >> .gitignore

# 3. Ejecutar los tests (con fixture minimal, sin el JSON real)
pytest tests/schema/ -v --cov=schema --cov-report=term-missing

# 4. Verificación manual con el JSON real
python -c "
from schema import SchemaManager
sm = SchemaManager('schema/azurerm_4_0.json')
print(f'Recursos indexados: {sm.resource_count}')
print(sm.get_summary('azurerm_virtual_network'))
"

Resultado esperado:

Recursos indexados: 847
{
  'required_attributes': ['address_space', 'location', 'name', 'resource_group_name'],
  'optional_attributes': ['bgp_community', 'dns_servers', 'edge_zone', 'tags', ...],
  'optional_blocks': ['ddos_protection_plan', 'encryption', 'timeouts']
}

Lo que este paso no hace

No valida que los valores de los atributos sean correctos. Sabe que address_space existe y es de tipo list(string), pero no sabe si ["10.0.0.0/8", "192.168.0.0/16"] es una combinación válida para ese entorno.

Esa validación semántica ocurre en el Revisor, en la etapa checkov y terraform plan. El SchemaManager resuelve un problema más acotado: que el Builder no use atributos que no existen. Lo demás tiene su sitio más adelante en el pipeline.

Siguiente paso

El Paso 3 configura el backend remoto de tfstate en Azure Blob Storage y la autenticación OIDC desde GitHub Actions.

Con los contratos y el SchemaManager en su sitio, el siguiente bloque es la infraestructura de soporte que hace posible ejecutar terraform plan desde el pipeline sin secretos de larga duración. Sin esto, el Revisor no puede ejecutar el plan porque no tiene acceso al state ni credenciales seguras para Azure.

Es el primer paso que requiere recursos reales en Azure.

El código de este paso, la documentación técnica completa y los tests están disponibles en el repositorio del proyecto.

Tags: terraform azure python multiagent llm iac platform-engineering software-architecture

Antes de un solo LLM, antes de Terraform, antes de Azure: modelos de datos. Aquí está el razonamiento y las decisiones no obvias.

Si llegaste desde el post anterior, ya sabes qué estoy construyendo. Si no, la versión corta: un pipeline multiagente que convierte lenguaje natural en infraestructura Azure desplegada con Terraform. Este post cubre el Paso 1 en detalle.

El Paso 1 no llama a ningún LLM. No genera HCL. No toca Azure. Tampoco es aburrido.

El problema que resuelve este paso

Un sistema con cinco agentes tiene cinco fronteras de datos. Cada frontera es un sitio donde el sistema puede fallar silenciosamente si no tienes contratos explícitos.

Sin contratos formales, un agente que produce un diccionario con clave resource_typ (sin ‘e’) no falla al crearse. Falla cuando el siguiente agente intenta leer resource_type y obtiene None. Si ese fallo ocurre dentro de una llamada LLM que está generando HCL, el error que ves es un problema de Terraform, no un problema de tipado Python. La pila de traza no te lleva al sitio real.

Pydantic v2 resuelve esto en el borde: si un modelo no valida, lanza ValidationError antes de que el dato contaminado cruce la frontera. El fallo es explícito, localizado y tiene contexto.

Qué se construyó

Seis modelos de contrato, un módulo de utilidades, configuración del paquete y tests:

contracts/
├── __init__.py              # exports centralizados
├── requirements.py          # InfraRequirements
├── recommendations.py       # ArchitectRecommendations
├── hcl_output.py            # HCLOutput
├── review_result.py         # ReviewResult
├── pipeline_state.py        # PipelineState
└── conversation.py          # ConversationOutput

core/
├── exceptions.py            # excepciones tipadas
└── logging.py               # logging estructurado

tests/
├── conftest.py              # fixtures reutilizables
└── contracts/
    └── test_contracts.py    # suite completa

Cada modelo define exactamente qué agente lo produce, qué agente lo consume, y qué invariantes debe cumplir.

Las decisiones no obvias

1. pipeline_id se genera una sola vez y solo se propaga

El Orquestador crea un uuid.UUID antes de invocar al primer agente. Desde ahí, ese UUID viaja en todos los contratos sin regenerarse.

Ningún agente crea su propio pipeline_id. Solo lo recibe y lo reenvía.

La consecuencia práctica: puedes hacer grep de un UUID en los logs y ver la traza completa de una ejecución a través de cinco agentes. Sin esto, correlacionar un fallo del Revisor en la iteración 3 con los requisitos originales del Conversacional requiere heurísticas.

El tipo elegido es uuid.UUID, no str. En serialización JSON con model_dump(mode="json") se convierte automáticamente a string. Al deserializar, model_validate reconstruye el UUID. El coste operativo es mínimo; la precisión semántica vale la pena.

2. ReviewResult.passed es una @property, no un campo

El Revisor ejecuta cinco etapas: fmt, tflint, checkov, validate, plan. Cada una produce un ReviewCheck con su estado. El resultado global passed es True si y solo si todas las etapas pasaron.

Si passed fuera un campo editable, podría desincronizarse con la lista de checks. Un agente podría construir un ReviewResult con tres checks fallidos y passed=True, y el Orquestador lo trataría como éxito.

@property
def passed(self) -> bool:
    return all(c.status == ReviewCheckStatus.PASSED for c in self.checks)

El problema secundario: Pydantic no incluye @property en model_dump(). Para persistencia, se usa to_snapshot():

def to_snapshot(self) -> dict:
    data = self.model_dump(mode="json")
    data["passed"] = self.passed  # inclusión explícita
    return data

3. SubnetSpec como modelo, no como dict

La primera versión usaba list[dict[str, str]] para las subredes. Funcionaba. Pero Pydantic no puede validar el contenido de un diccionario genérico: si address_prefix tiene un valor malformado, no te enteras hasta que el Builder genera HCL inválido.

class SubnetSpec(BaseModel):
    name: str
    address_prefix: str  # próximo paso: @field_validator con ip_network()

# En NetworkSpec:
subnets: list[SubnetSpec] = []

La interfaz es idéntica desde fuera. La capacidad de añadir validación de CIDR en el futuro sin cambiar la interfaz es lo que lo justifica.

4. config: dict[str, object], no dict a secas

ResourceSpec tiene un campo config para atributos específicos de cada recurso Terraform. No puedes modelar estos atributos con un esquema fijo sin duplicar el schema del provider.

dict en Pydantic v2 equivale a dict[Any, Any]. dict[str, object] fuerza que las claves sean strings (que es lo que Terraform espera) y documenta la intención. Los valores siguen siendo libres, pero eso es correcto: el Builder los validará contra el schema del provider en el Paso 2.

5. AgentStepStatus como Enum, no como str

Los estados posibles de un paso del agente son un conjunto cerrado: PENDING, RUNNING, SUCCESS, FAILED, SKIPPED. Un str libre no falla al construirse con el valor "succes". Un Enum sí.

class AgentStepStatus(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    SUCCESS = "success"
    FAILED = "failed"
    SKIPPED = "skipped"

Hereda de str para que model_dump(mode="json") serialice el valor como string, no como objeto Enum.

6. Logging estructurado desde el principio

El logging estándar de Python no acepta kwargs arbitrarios. Este código lanza TypeError en runtime:

# ❌ no funciona con logging estándar
logger.info("Builder iteration", pipeline_id="abc", iteration=2)

La forma correcta, compatible con cualquier handler JSON (Loki, Datadog, etc.):

# ✅
logger.info("Builder iteration", extra={"pipeline_id": str(pipeline_id), "iteration": 2})

Es un detalle pequeño que, si no lo corriges desde el principio, se reproduce en cada agente y se convierte en una deuda técnica difusa.

Diagrama 1 — modelos de datos:

graph TB
    CO[ConversationOutput] -->|contiene| IR[InfraRequirements]
    IR -->|contiene| RS[ResourceSpec]
    IR -->|contiene| TS[TagsSpec]
    RS -.->|opcional| NS[NetworkSpec]
    NS -->|lista| SS[SubnetSpec]
    AR[ArchitectRecommendations] -.->|referencia| IR
    HCL[HCLOutput] -.->|referencia| IR
    RR[ReviewResult] -->|lista| RC[ReviewCheck]
    PS[PipelineState] -->|lista| AS[AgentStep]
    PS -.->|snapshot| IR
    PS -.->|snapshot| HCL
    PS -.->|snapshot| RR

    style CO fill:#2a1a3a,stroke:#8b5cf6,color:#fff
    style IR fill:#2a1a3a,stroke:#8b5cf6,color:#fff
    style AR fill:#2a1a3a,stroke:#8b5cf6,color:#fff
    style HCL fill:#2a1a3a,stroke:#8b5cf6,color:#fff
    style RR fill:#2a1a3a,stroke:#8b5cf6,color:#fff
    style PS fill:#2a1a3a,stroke:#8b5cf6,color:#fff
    style AS fill:#1a2a3a,stroke:#3b82f6,color:#fff
    style RC fill:#1a2a3a,stroke:#3b82f6,color:#fff
    style RS fill:#1a2a3a,stroke:#3b82f6,color:#fff
    style NS fill:#1a2a3a,stroke:#3b82f6,color:#fff
    style SS fill:#1a2a3a,stroke:#3b82f6,color:#fff
    style TS fill:#1a2a3a,stroke:#3b82f6,color:#fff

Diagrama 2 — flujo de agentes:

graph LR
    ORC([Orquestador]) -->|genera pipeline_id| CONV[Conversacional]
    CONV -->|produce ConversationOutput| ARQ[Arquitecto]
    CONV -->|produce ConversationOutput| BUILDER[Builder]
    ARQ -->|produce ArchitectRecommendations| BUILDER
    BUILDER -->|produce HCLOutput| REVISOR[Revisor]
    REVISOR -->|produce ReviewResult| BUILDER
    REVISOR -->|passed=true| ORC
    ORC -->|mantiene PipelineState| ORC

    style ORC fill:#1F4E79,stroke:#2E75B6,color:#fff
    style CONV fill:#1e3a5f,stroke:#6366f1,color:#fff
    style ARQ fill:#1e3a5f,stroke:#6366f1,color:#fff
    style BUILDER fill:#1a3a2a,stroke:#10b981,color:#fff
    style REVISOR fill:#3a2a1a,stroke:#f59e0b,color:#fff

Cómo replicarlo

Prerequisitos: Python 3.11+, pip.

# 1. Crear entorno virtual
python -m venv .venv

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

# 2. Instalar en modo editable con dependencias de dev
pip install -e ".[dev]"

# 3. Ejecutar los tests
pytest tests/ -v --cov=contracts --cov=core --cov-report=term-missing

Resultado esperado: 30 tests en verde, cobertura >90% en la capa de contratos.

Verificación manual rápida para confirmar los invariantes críticos:

from uuid import uuid4
from contracts import InfraRequirements, ResourceSpec, TagsSpec
from contracts import ReviewResult, ReviewCheck, ReviewStage, ReviewCheckStatus
import json

pid = uuid4()

# UUID serializa a str en JSON
req = InfraRequirements(
    pipeline_id=pid, client="acme", environment="dev",
    location="westeurope",
    tags=TagsSpec(environment="dev", owner="alice@example.com"),
    resources=[ResourceSpec(resource_type="azurerm_virtual_network", logical_name="vnet")]
)
data = req.model_dump(mode="json")
assert isinstance(data["pipeline_id"], str)
json.dumps(data)  # no lanza

# passed es propiedad calculada, no campo editable
result = ReviewResult(pipeline_id=pid, iteration=1, checks=[
    ReviewCheck(stage=ReviewStage.FMT, status=ReviewCheckStatus.PASSED),
    ReviewCheck(stage=ReviewStage.TFLINT, status=ReviewCheckStatus.FAILED, errors=["E001"]),
])
assert result.passed is False
assert "passed" not in ReviewResult.model_fields  # no es campo
snap = result.to_snapshot()
assert snap["passed"] is False  # sí aparece en snapshot

Lo que este paso no hace (y no debe hacer)

No valida que address_prefix sea un CIDR real. No comprueba que location sea una región Azure válida. No verifica que los atributos en config existan en el schema del provider.

Esas validaciones tienen su sitio en pasos posteriores: el Arquitecto valida convenciones, el Builder valida contra el schema del provider, el Revisor valida con herramientas reales. Los contratos del Paso 1 validan estructura y tipos, no semántica de dominio.

Esta separación es deliberada. Si los contratos hicieran validación de dominio, cambiar la versión del provider o añadir una nueva región Azure requeriría modificar los contratos base. Con la separación actual, los contratos son estables; la lógica de dominio vive donde le corresponde.

Siguiente paso

El Paso 2 construye el SchemaManager: el módulo que carga el JSON generado por terraform providers schema -json (~15MB para azurerm 4.x) y expone una interfaz limpia para que el Builder consulte exactamente qué atributos existen en cada recurso, cuáles son requeridos y cuáles son opcionales.

Sin el SchemaManager, el Builder no tiene más referencia que su entrenamiento para saber si enable_https_traffic_only existe en azurerm_storage_account versión 4.x o si fue renombrado. Con él, las alucinaciones de atributos se convierten en un error detectable antes de ejecutar un solo comando de Terraform.

El código de este paso, la documentación técnica completa y los tests estarán disponibles en el repositorio del proyecto.

Tags: terraform azure pydantic python multiagent llm iac platform-engineering software-architecture

Infraestructura como código generada, validada y desplegada por agentes de IA. Sin templates. Sin alucinaciones. Con Terraform real.

Llevo un tiempo pensando en el mismo problema que muchos equipos de plataforma tienen pero pocos verbalizan bien: Terraform es potente, pero la barrera de entrada sigue siendo alta. Un desarrollador que necesita un entorno en Azure no debería tener que aprender HCL, entender el modelo de recursos de azurerm o saber qué atributos son opcionales en la versión 4.x del provider.

Pero la solución obvia —generar el Terraform con un LLM— tiene un problema estructural que no se resuelve simplemente con un buen prompt: los modelos de lenguaje alucinen atributos que no existen, usan versiones deprecadas del provider y producen HCL que no pasa ni el terraform validate.

Así que decidí construir algo distinto. Y en esta serie de posts voy a documentar cómo.

La idea en una frase

Un pipeline multiagente que toma requisitos en lenguaje natural, los convierte en HCL válido para Azure, lo valida con herramientas reales y lo despliega con aprobación humana en el bucle.

No es un chatbot que genera código. Es un sistema de producción con contratos, reintentos, estado persistente y seguridad desde el principio.

Por qué los enfoques existentes no me convencían

He evaluado varias aproximaciones antes de construir esto:

Módulos Terraform con variables: siguen requiriendo que alguien sepa Terraform. La barrera no desaparece, solo baja un escalón.

Terraform CDK: añade una capa de abstracción útil, pero sigue siendo código. El desarrollador de aplicaciones que necesita un entorno a las 3pm no quiere aprender TypeScript para eso.

LLM + prompt directo: el problema ya mencionado. Sin una fuente de verdad del schema del provider, el modelo inventa. Y cuando el HCL llega a terraform plan, explota.

Herramientas comerciales de IaC con AI: existen, pero son cajas negras, costosas y no se adaptan a las restricciones de seguridad de muchas organizaciones (OIDC, tenants propios, políticas de red).

Lo que faltaba era un sistema que use el schema real del provider como fuente de verdad, valide el HCL generado con las mismas herramientas que usaría un ingeniero senior, y mantenga un humano en el bucle antes de aplicar cualquier cambio.

La arquitectura a alto nivel

Sin entrar en detalles de implementación todavía, el sistema tiene estas piezas:

Agentes especializados, cada uno con una responsabilidad única:

• Uno que recoge requisitos en lenguaje natural y los estructura
• Uno que consulta documentación oficial de Azure para extraer best practices
• Uno que genera el HCL usando el schema exacto del provider como única referencia
• Uno que ejecuta un pipeline de validación con herramientas reales
• Uno que orquesta el estado, los reintentos y las métricas

Infraestructura de soporte diseñada para producción desde el día uno:

• Estado remoto en Azure Blob Storage con locking nativo
• Autenticación sin secretos de larga duración (OIDC)
• Flujo de aprobación humana antes de cualquier terraform apply

Un bucle de corrección automática entre el generador y el validador, con límite de reintentos y escalado explícito cuando se agota.

El roadmap que estoy siguiendo

Estoy construyendo esto en fases pequeñas, donde cada paso produce algo funcional antes de avanzar al siguiente. El orden no es arbitrario: cada componente desbloquea el siguiente.

Fase 1 — Fundamentos
  ├── Paso 1: Capa de contratos (interfaces entre agentes)
  ├── Paso 2: Fuente de verdad del provider
  └── Paso 3: Backend remoto de estado + autenticación OIDC

Fase 2 — Agentes Core
  ├── Paso 4: Agente Conversacional
  ├── Paso 5: Agente Arquitecto (integración con docs oficiales)
  └── Paso 6: Agente Builder (generación de HCL)

Fase 3 — Pipeline de Revisión
  ├── Paso 7: Pipeline fmt → tflint → checkov → validate → plan
  └── Paso 8: Bucle Builder ↔ Revisor con reintentos

Fase 4 — Despliegue y Aprobación
  ├── Paso 9: Flujo de aprobación humana
  ├── Paso 10: Agente Deployer
  └── Paso 11: Orquestador con estado persistente y métricas

Fase 5 — Post-MVP
  ├── Validación de políticas con OPA
  ├── Outputs sensibles a Key Vault
  ├── Observabilidad completa
  ├── Operaciones Day 2 (modificar, destruir, importar)
  └── Detección de drift

Cada post de esta serie cubre un paso. Cuando termine, el repositorio completo estará disponible.

Lo que he aprendido en el Paso 1

El primer paso no genera infraestructura. No llama a ningún LLM. No toca Azure.

Define los contratos de datos entre agentes: qué información existe, qué forma tiene, y qué invariantes debe cumplir. Es la decisión de diseño más importante del sistema, y la que más se subestima.

Algunas decisiones no obvias que tomé aquí y que evitaron problemas más adelante:

• Por qué un UUID de correlación generado una sola vez cambia completamente la depurabilidad del sistema
• Por qué passed no puede ser un campo editable si quieres que el sistema sea coherente
• Por qué un diccionario genérico y un modelo Pydantic no son intercambiables, aunque en Python parezca que sí

El siguiente post entra en esos detalles.

Por qué lo estoy documentando públicamente

Dos razones.

La primera es práctica: documentar mientras construyes obliga a entender lo que estás haciendo. Si no puedes explicar una decisión de diseño, probablemente no la has tomado bien.

La segunda es que este tipo de sistema —multiagente, con herramientas reales, con seguridad desde el principio— no tiene muchos referentes documentados desde cero. La mayoría de los tutoriales de “AI + Terraform” son demos de 5 minutos que no sobrevivirían un entorno real.

Esto pretende ser diferente.

Siguiente post: Paso 1 en detalle — cómo definir contratos Pydantic v2 que hacen que un sistema multiagente sea depurable, testeable y mantenible.

Tags: terraform azure llm multiagent iac python pydantic devops platform-engineering

• Objetivo: Implementar una estrategia enterprise de Azure Policy para garantizar cumplimiento normativo, seguridad consistente y gobernanza centralizada a través de toda la jerarquía de Management Groups, usando Policy as Code (PaC) con Enterprise Policy as Code (EPAC) como framework principal.

• Dependencias:

  • [[Azure-Management-Groups-Enterprise]] - Jerarquía donde se asignan las políticas
  • [[Azure-RBAC]] - Identidades para remediation tasks y policy assignments
  • [[Azure-Log-Analytics]] - Workspace destino para diagnostic settings via policy
  • [[Microsoft-Sentinel]] - SIEM que consume eventos de compliance
  • [[Azure-Automation]] - Runbooks para remediation tasks complejas
  • [[Cost-Management]] - Presupuestos gobernados via policy

[!tip] Notas Importantes

• Las políticas con efecto Deny pueden bloquear despliegues en producción; prueba siempre en Sandbox primero
• DeployIfNotExists y Modify requieren una Managed Identity asignada al Policy Assignment
• El compliance state se actualiza cada ~24h; usa az policy state trigger-scan para forzar evaluación
• Las Policy Exemptions deben tener fecha de expiración y aprobación formal
• EPAC es el framework recomendado por Microsoft para Policy as Code a escala enterprise
• Built-in policies tienen ahora versionado (Public Preview 2024): usa versiones fijas en producción
• Diagrama de anatomía de políticas: _assets/diagrams/policy-anatomy.drawio
• Terraform modules en terraform/modules/azure-policy/

🏛️ 2. Arquitectura

Flujo de Policy as Code con EPAC

flowchart TB
    subgraph Source["📁 Source Control (Git)"]
        Definitions["📜 Policy Definitions\n/Definitions"]
        Assignments["📋 Policy Assignments\n/Assignments"]
        Exemptions["⚠️ Exemptions\n/Exemptions"]
    end

    subgraph CICD["🔄 CI/CD Pipeline"]
        Validate["✅ Validate\nEPAC plan"]
        Test["🧪 Test\nPSRule + EPAC"]
        Deploy["🚀 Deploy\nEPAC deploy"]
    end

    subgraph Azure["☁️ Azure"]
        Root["🏢 Root MG\nGlobal Policies"]
        Platform["⚙️ Platform MG\nInfra Policies"]
        LZ["🎯 Landing Zones MG\nWorkload Policies"]
        Sandbox["🧪 Sandbox MG\nRelaxed Policies"]
    end

    subgraph Compliance["📊 Compliance"]
        Dashboard["📈 Policy Dashboard\nAzure Portal"]
        Remediation["🔧 Remediation Tasks"]
        Alerts["🔔 Compliance Alerts\nAzure Monitor"]
        Reports["📄 Reports\nAzDOC / AzAdvertizer"]
    end

    Source --> CICD
    CICD --> Azure
    Azure --> Compliance

    style Source fill:#e3f2fd
    style CICD fill:#fff3e0
    style Azure fill:#e8f5e9
    style Compliance fill:#fce4ec

Anatomía de una Azure Policy

flowchart LR
    subgraph PolicyDef["📜 Policy Definition"]
        Meta["📋 Metadata\n- displayName\n- description\n- category\n- version"]
        Mode["⚙️ Mode\n- All\n- Indexed\n- Microsoft.xxx"]
        Params["🔧 Parameters\n- effect\n- listOfAllowedX\n- tagName"]
        Rule["📐 Policy Rule\n- if (condition)\n- then (effect)"]
    end

    subgraph Effects["⚡ Effects (por orden de evaluación)"]
        Disabled["🔕 Disabled"]
        Append["➕ Append"]
        Modify["✏️ Modify"]
        Audit["👁️ Audit"]
        AuditIfNotExists["👁️ AuditIfNotExists"]
        Deny["🚫 Deny"]
        DenyAction["🚫 DenyAction"]
        DeployIfNotExists["🔧 DeployIfNotExists"]
        Manual["📝 Manual"]
    end

    Rule --> Effects
    style PolicyDef fill:#e8f5e9
    style Effects fill:#fff3e0

Jerarquía de Assignments y Herencia

flowchart TB
    Root["🏢 Root MG\n📜 Require-Tags [Deny]\n📜 Allowed-Locations [Deny]\n📜 Audit-Diagnostics [AuditIfNotExists]\n📜 ENS-Baseline [Audit]"]

    Root -->|Hereda todo| Platform["⚙️ Platform MG\n📜 Deny-Public-IPs [Deny]\n📜 Enforce-Private-Endpoints [Deny]\n📜 Require-NSG [Deny]"]

    Root -->|Hereda todo| LZ["🎯 Landing Zones MG\n📜 Allowed-VM-Sizes [Deny]\n📜 Require-Backup [DINE]\n📜 Enforce-TLS [Deny]"]

    Root -->|Hereda todo| Sandbox["🧪 Sandbox MG\n📜 Auto-Shutdown [DINE]\n📜 Budget-Alert [Audit]\n❌ Exemption: Public-IPs"]

    LZ -->|Hereda| CorpProd["🟢 Corp-Prod\n📜 Require-Delete-Lock [Append]\n📜 Require-Monitoring [DINE]"]

    LZ -->|Hereda| CorpNonProd["🟡 Corp-NonProd\n📜 Auto-Shutdown [DINE]"]

    style Root fill:#ffebee
    style Platform fill:#fff3e0
    style LZ fill:#e3f2fd
    style Sandbox fill:#e8f5e9
    style CorpProd fill:#f3e5f5
    style CorpNonProd fill:#fff9c4

Diagrama detallado: _assets/diagrams/policy-assignments-matrix.drawio

🎨 3. Diseño

Naming Convention

Policy Definitions:
  Formato: pol-<category>-<action>-<resource>-<version>
  Ejemplos:
  - pol-sec-deny-publicip-v1
  - pol-net-require-nsg-subnet-v2
  - pol-tag-require-costcenter-v1
  - pol-mon-dine-diagnostics-v3

Policy Initiatives (Sets):
  Formato: ini-<framework>-<scope>
  Ejemplos:
  - ini-security-baseline-platform
  - ini-ens-esquema-nacional-seguridad
  - ini-cis-benchmark-azure
  - ini-cost-governance-landingzones

Policy Assignments:
  Formato: pa-<initiative/policy>-<mg-scope>
  Ejemplos:
  - pa-security-baseline-root
  - pa-require-tags-landingzones
  - pa-auto-shutdown-sandbox

Matriz de Efectos por Entorno

Categorías de Políticas

📊 4. Observabilidad

Compliance Dashboard

{
  "Alertas_Compliance": {
    "compliance_drop": {
      "metric": "NonCompliantResources",
      "threshold": "20% increase in 24h",
      "severity": "High",
      "notification": "governance-team@contoso.com"
    },
    "new_deny_triggered": {
      "operation": "Microsoft.Authorization/policyAssignments/deny",
      "severity": "Medium",
      "notification": "platform-team@contoso.com"
    },
    "exemption_expiring": {
      "check": "Exemptions expiring in 7 days",
      "severity": "Medium",
      "notification": "compliance-team@contoso.com"
    },
    "remediation_failed": {
      "operation": "Microsoft.PolicyInsights/remediations/write",
      "status": "Failed",
      "severity": "High",
      "notification": "sre-team@contoso.com"
    }
  }
}

KPIs de Gobernanza

Métricas clave a monitorear semanalmente:

├── Overall Compliance Rate
│   ├── Target: > 95% en Production MGs
│   ├── Target: > 80% en NonProd MGs
│   └── Target: > 60% en Sandbox
│
├── Non-Compliant Resources por categoría
│   ├── Security (crítico - resolver en <24h)
│   ├── Tagging (alto - resolver en <72h)
│   └── Monitoring (medio - resolver en <1 semana)
│
├── Policy Exemptions activas
│   ├── Count total (target: < 20 activas)
│   ├── Próximas a expirar (< 7 días)
│   └── Sin fecha de expiración (target: 0)
│
├── Remediation Tasks
│   ├── Pendientes
│   ├── En progreso
│   ├── Completadas (última semana)
│   └── Fallidas (requiere atención)
│
└── EPAC Drift Detection
    ├── Políticas fuera de source control
    ├── Assignments sin definición en repo
    └── Exemptions no registradas en Git

Logs y Diagnósticos

• Activity Logs: Todas las operaciones de policy (create, modify, delete, deny triggered)
  • Retención: 90 días en Log Analytics
  • Alertas en Azure Monitor para cambios críticos
• Policy Insights: Estado de compliance en tiempo real
  • Dashboard URL: https://portal.azure.com/#view/Microsoft_Azure_Policy/PolicyComplianceBlade
  • Export a Storage Account para análisis histórico
• AzAdvertizer: Herramienta externa para explorar y visualizar políticas
  • URL: https://www.azadvertizer.net/

Backup y DR

• Todo como código: EPAC en repositorio Git con ramas main, staging, dev
• State management: EPAC usa Azure Storage como backend de estado
• Rollback: Revert en Git + epac deploy restaura estado anterior en minutos
  • RPO: 1 hora (commits frecuentes)
  • RTO: 30 minutos (re-despliegue EPAC)

⚙️ 5. Implementación (IaC)

Estructura EPAC (Enterprise Policy as Code)

epac-root/
├── .github/
│   └── workflows/
│       ├── epac-plan.yml          # PR: valida cambios
│       └── epac-deploy.yml        # main: despliega
├── Definitions/
│   ├── policyDefinitions/
│   │   ├── Security/
│   │   │   ├── pol-deny-publicip.jsonc
│   │   │   ├── pol-require-nsg-subnet.jsonc
│   │   │   └── pol-enforce-tls-storage.jsonc
│   │   ├── Tagging/
│   │   │   ├── pol-require-tag-costcenter.jsonc
│   │   │   └── pol-inherit-tags-rg.jsonc
│   │   ├── Monitoring/
│   │   │   ├── pol-dine-diagnostics-vm.jsonc
│   │   │   └── pol-dine-diagnostics-storage.jsonc
│   │   ├── Cost/
│   │   │   ├── pol-deny-vm-size.jsonc
│   │   │   └── pol-dine-autoshutdown.jsonc
│   │   └── Networking/
│   │       ├── pol-require-private-endpoint.jsonc
│   │       └── pol-manage-nsg-subnet.jsonc
│   ├── policySetDefinitions/
│   │   ├── ini-security-baseline.jsonc
│   │   ├── ini-tagging-governance.jsonc
│   │   ├── ini-monitoring-baseline.jsonc
│   │   ├── ini-cost-governance.jsonc
│   │   ├── ini-ens-spain.jsonc
│   │   └── ini-network-governance.jsonc
│   └── global-settings.jsonc
├── Assignments/
│   ├── root-mg/
│   │   ├── pa-security-baseline.jsonc
│   │   ├── pa-tagging-governance.jsonc
│   │   └── pa-monitoring-baseline.jsonc
│   ├── platform-mg/
│   │   └── pa-network-governance.jsonc
│   ├── landingzones-mg/
│   │   ├── pa-cost-governance.jsonc
│   │   └── pa-bcdr-requirements.jsonc
│   └── sandbox-mg/
│       └── pa-sandbox-governance.jsonc
├── Exemptions/
│   └── sandbox/
│       └── exempt-publicip-sandbox.jsonc
└── README.md

Terraform - Módulo de Azure Policy

# terraform/modules/azure-policy/main.tf

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.90.0, < 5.0.0"
    }
  }
}

# ─────────────────────────────────────────────
# Custom Policy Definition
# ─────────────────────────────────────────────
resource "azurerm_policy_definition" "this" {
  for_each = var.create ? var.custom_policy_definitions : {}

  name         = each.key
  display_name = each.value.display_name
  description  = each.value.description
  policy_type  = "Custom"
  mode         = each.value.mode # "All" | "Indexed" | "Microsoft.Kubernetes.Data" etc.

  management_group_id = each.value.management_group_id

  metadata = jsonencode({
    category = each.value.category
    version  = each.value.version
  })

  parameters  = each.value.parameters != null ? jsonencode(each.value.parameters) : null
  policy_rule = jsonencode(each.value.policy_rule)
}

# ─────────────────────────────────────────────
# Policy Initiative (Set Definition)
# ─────────────────────────────────────────────
resource "azurerm_policy_set_definition" "this" {
  for_each = var.create ? var.policy_initiatives : {}

  name         = each.key
  display_name = each.value.display_name
  description  = each.value.description
  policy_type  = "Custom"

  management_group_id = each.value.management_group_id

  metadata = jsonencode({
    category = each.value.category
    version  = each.value.version
  })

  parameters = each.value.parameters != null ? jsonencode(each.value.parameters) : null

  dynamic "policy_definition_reference" {
    for_each = each.value.policy_references
    content {
      policy_definition_id = policy_definition_reference.value.policy_definition_id
      reference_id         = policy_definition_reference.value.reference_id
      parameter_values     = policy_definition_reference.value.parameter_values != null ? jsonencode(policy_definition_reference.value.parameter_values) : null
    }
  }

  depends_on = [azurerm_policy_definition.this]
}

# ─────────────────────────────────────────────
# Policy Assignment (con soporte para DINE/Modify → Managed Identity)
# DEPENDENCY: El scope (MG/Subscription/RG) debe existir previamente
# ─────────────────────────────────────────────
resource "azurerm_management_group_policy_assignment" "this" {
  for_each = {
    for k, v in(var.create ? var.policy_assignments : {}) :
    k => v if v.scope_type == "management_group"
  }

  name                 = each.key
  display_name         = each.value.display_name
  description          = each.value.description
  management_group_id  = each.value.scope_id
  policy_definition_id = each.value.policy_definition_id
  enforce              = each.value.enforce # false = "DoNotEnforce" (audit-only mode)
  not_scopes           = each.value.not_scopes

  parameters = each.value.parameters != null ? jsonencode(each.value.parameters) : null

  # Managed Identity requerida para efectos DINE y Modify
  dynamic "identity" {
    for_each = each.value.identity_type != null ? [1] : []
    content {
      type         = each.value.identity_type
      identity_ids = each.value.identity_type == "UserAssigned" ? each.value.identity_ids : null
    }
  }

  location = each.value.identity_type != null ? each.value.location : null

  dynamic "non_compliance_message" {
    for_each = each.value.non_compliance_messages
    content {
      content                        = non_compliance_message.value.content
      policy_definition_reference_id = non_compliance_message.value.reference_id
    }
  }

  depends_on = [
    azurerm_policy_definition.this,
    azurerm_policy_set_definition.this
  ]
}

# ─────────────────────────────────────────────
# Role Assignment para Managed Identity de la Policy
# DEPENDENCY: Requiere que el assignment con managed identity ya exista
# ─────────────────────────────────────────────
resource "azurerm_role_assignment" "policy_remediation" {
  for_each = {
    for k, v in(var.create ? var.policy_assignments : {}) :
    k => v if v.identity_type != null && v.remediation_role != null
  }

  scope                = each.value.remediation_scope != null ? each.value.remediation_scope : each.value.scope_id
  role_definition_name = each.value.remediation_role
  principal_id         = azurerm_management_group_policy_assignment.this[each.key].identity[0].principal_id

  depends_on = [azurerm_management_group_policy_assignment.this]
}

# ─────────────────────────────────────────────
# Remediation Task (para recursos ya existentes no conformes)
# ─────────────────────────────────────────────
resource "azurerm_management_group_policy_remediation" "this" {
  for_each = {
    for k, v in(var.create ? var.policy_assignments : {}) :
    k => v if v.create_remediation_task == true
  }

  name                    = "remediation-${each.key}"
  management_group_id     = each.value.scope_id
  policy_assignment_id    = azurerm_management_group_policy_assignment.this[each.key].id
  resource_discovery_mode = "ReEvaluateCompliance"

  depends_on = [
    azurerm_management_group_policy_assignment.this,
    azurerm_role_assignment.policy_remediation
  ]
}

# ─────────────────────────────────────────────
# Policy Exemption
# DEPENDENCY: El assignment al que se exime debe existir
# ─────────────────────────────────────────────
resource "azurerm_management_group_policy_exemption" "this" {
  for_each = var.create ? var.policy_exemptions : {}

  name                            = each.key
  display_name                    = each.value.display_name
  description                     = each.value.description
  management_group_id             = each.value.scope_id
  policy_assignment_id            = each.value.policy_assignment_id
  exemption_category              = each.value.exemption_category # "Waiver" | "Mitigated"
  expires_on                      = each.value.expires_on         # ISO 8601, obligatorio en este módulo
  policy_definition_reference_ids = each.value.policy_definition_reference_ids
  metadata = each.value.metadata != null ? jsonencode(each.value.metadata) : jsonencode({
    approvedBy   = each.value.approved_by
    ticketNumber = each.value.ticket_number
    reviewDate   = each.value.review_date
  })
}

# terraform/modules/azure-policy/variables.tf

variable "create" {
  description = "Controla si el módulo crea recursos."
  type        = bool
  default     = true
}

variable "custom_policy_definitions" {
  description = "Mapa de custom policy definitions a crear."
  type = map(object({
    display_name        = string
    description         = string
    mode                = string
    category            = string
    version             = string
    management_group_id = string
    parameters          = optional(any, null)
    policy_rule         = any
  }))
  default = {}
}

variable "policy_initiatives" {
  description = "Mapa de policy initiatives (set definitions) a crear."
  type = map(object({
    display_name        = string
    description         = string
    category            = string
    version             = string
    management_group_id = string
    parameters          = optional(any, null)
    policy_references = list(object({
      policy_definition_id = string
      reference_id         = string
      parameter_values     = optional(any, null)
    }))
  }))
  default = {}
}

variable "policy_assignments" {
  description = "Mapa de policy assignments a Management Groups."
  type = map(object({
    display_name         = string
    description          = string
    scope_type           = string  # "management_group"
    scope_id             = string  # DEPENDENCY: MG debe existir
    policy_definition_id = string
    enforce              = optional(bool, true)
    not_scopes           = optional(list(string), [])
    parameters           = optional(any, null)
    identity_type        = optional(string, null)   # null | "SystemAssigned" | "UserAssigned"
    identity_ids         = optional(list(string), [])
    location             = optional(string, null)   # Requerido si identity_type != null
    remediation_role     = optional(string, null)
    remediation_scope    = optional(string, null)
    create_remediation_task = optional(bool, false)
    non_compliance_messages = optional(list(object({
      content      = string
      reference_id = optional(string, null)
    })), [])
  }))
  default = {}
}

variable "policy_exemptions" {
  description = "Mapa de exemptions. TODAS deben tener expires_on y ticket de aprobación."
  type = map(object({
    display_name                    = string
    description                     = string
    scope_id                        = string
    policy_assignment_id            = string
    exemption_category              = string  # "Waiver" | "Mitigated"
    expires_on                      = string  # ISO 8601 - OBLIGATORIO
    policy_definition_reference_ids = optional(list(string), [])
    approved_by                     = string
    ticket_number                   = string
    review_date                     = string
    metadata                        = optional(any, null)
  }))
  default = {}
}

variable "tags" {
  description = "Tags aplicados a recursos que lo soportan."
  type        = map(string)
  default     = {}
}

# terraform/modules/azure-policy/outputs.tf

output "policy_definition_ids" {
  description = "Mapa de IDs de custom policy definitions creadas."
  value = {
    for k, v in azurerm_policy_definition.this : k => v.id
  }
}

output "initiative_ids" {
  description = "Mapa de IDs de policy initiatives creadas."
  value = {
    for k, v in azurerm_policy_set_definition.this : k => v.id
  }
}

output "assignment_ids" {
  description = "Mapa de IDs de policy assignments."
  value = {
    for k, v in azurerm_management_group_policy_assignment.this : k => v.id
  }
}

output "assignment_principal_ids" {
  description = "Principal IDs de las Managed Identities de los assignments (para RBAC externo)."
  value = {
    for k, v in azurerm_management_group_policy_assignment.this :
    k => try(v.identity[0].principal_id, null)
    if try(v.identity[0].principal_id, null) != null
  }
}

output "exemption_ids" {
  description = "Mapa de IDs de policy exemptions."
  value = {
    for k, v in azurerm_management_group_policy_exemption.this : k => v.id
  }
}

Ejemplo de Custom Policy Definition (Deny Public IP)

// Definitions/policyDefinitions/Security/pol-deny-publicip.jsonc
{
  "name": "pol-sec-deny-publicip-v1",
  "type": "Microsoft.Authorization/policyDefinitions",
  "properties": {
    "displayName": "[Contoso] Deny creation of Public IP Addresses",
    "description": "Denies creation of Public IP resources except for approved SKUs.",
    "policyType": "Custom",
    "mode": "All",
    "metadata": {
      "category": "Security",
      "version": "1.0.0",
      "preview": false
    },
    "parameters": {
      "effect": {
        "type": "String",
        "allowedValues": ["Deny", "Audit", "Disabled"],
        "defaultValue": "Deny",
        "metadata": {
          "displayName": "Effect",
          "description": "Deny | Audit | Disabled"
        }
      },
      "allowedSKUs": {
        "type": "Array",
        "defaultValue": [],
        "metadata": {
          "displayName": "Allowed Public IP SKUs",
          "description": "Empty array = deny all. Add SKUs to allow specific ones."
        }
      }
    },
    "policyRule": {
      "if": {
        "allOf": [
          {
            "field": "type",
            "equals": "Microsoft.Network/publicIPAddresses"
          },
          {
            "not": {
              "field": "Microsoft.Network/publicIPAddresses/sku.name",
              "in": "[parameters('allowedSKUs')]"
            }
          }
        ]
      },
      "then": {
        "effect": "[parameters('effect')]"
      }
    }
  }
}

Ejemplo de Policy DINE - Diagnostic Settings

// Definitions/policyDefinitions/Monitoring/pol-dine-diagnostics-storage.jsonc
{
  "name": "pol-mon-dine-diagnostics-storage-v2",
  "properties": {
    "displayName": "[Contoso] Deploy Diagnostic Settings for Storage Accounts",
    "description": "Deploys diagnostic settings to Storage Accounts sending logs to central Log Analytics Workspace.",
    "mode": "Indexed",
    "metadata": {
      "category": "Monitoring",
      "version": "2.0.0"
    },
    "parameters": {
      "effect": {
        "type": "String",
        "allowedValues": ["DeployIfNotExists", "AuditIfNotExists", "Disabled"],
        "defaultValue": "DeployIfNotExists"
      },
      "logAnalyticsWorkspaceId": {
        "type": "String",
        "metadata": {
          "displayName": "Log Analytics Workspace Resource ID",
          "description": "DEPENDENCY: Must be an existing Log Analytics Workspace.",
          "strongType": "omsWorkspace"
        }
      }
    },
    "policyRule": {
      "if": {
        "field": "type",
        "equals": "Microsoft.Storage/storageAccounts"
      },
      "then": {
        "effect": "[parameters('effect')]",
        "details": {
          "type": "Microsoft.Insights/diagnosticSettings",
          "roleDefinitionIds": [
            "/providers/Microsoft.Authorization/roleDefinitions/92aaf0da-9dab-42b6-94a3-d43ce8d16293"
          ],
          "deployment": {
            "properties": {
              "mode": "incremental",
              "template": {
                "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
                "contentVersion": "1.0.0.0",
                "parameters": {
                  "resourceName": { "type": "string" },
                  "workspaceId": { "type": "string" }
                },
                "resources": [
                  {
                    "type": "Microsoft.Storage/storageAccounts/providers/diagnosticSettings",
                    "apiVersion": "2021-05-01-preview",
                    "name": "[concat(parameters('resourceName'), '/Microsoft.Insights/setByPolicy')]",
                    "properties": {
                      "workspaceId": "[parameters('workspaceId')]",
                      "logs": [
                        { "category": "StorageRead", "enabled": true },
                        { "category": "StorageWrite", "enabled": true },
                        { "category": "StorageDelete", "enabled": true }
                      ],
                      "metrics": [
                        { "category": "Transaction", "enabled": true }
                      ]
                    }
                  }
                ]
              },
              "parameters": {
                "resourceName": { "value": "[field('name')]" },
                "workspaceId": { "value": "[parameters('logAnalyticsWorkspaceId')]" }
              }
            }
          }
        }
      }
    }
  }
}

Pipeline EPAC (GitHub Actions)

# .github/workflows/epac-plan.yml
name: EPAC Plan (PR Validation)

on:
  pull_request:
    branches: [main]
    paths:
      - 'Definitions/**'
      - 'Assignments/**'
      - 'Exemptions/**'

jobs:
  epac-plan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Azure Login (OIDC)
        uses: azure/login@v2
        with:
          client-id: $
          tenant-id: $
          subscription-id: $

      - name: Install EPAC
        shell: pwsh
        run: Install-Module EnterprisePolicyAsCode -Force -AllowClobber

      - name: EPAC Build-DeploymentPlans
        shell: pwsh
        run: |
          Build-DeploymentPlans `
            -DefinitionsRootFolder ./Definitions `
            -OutputFolder ./Output `
            -GlobalSettingsFile ./Definitions/global-settings.jsonc

      - name: PSRule Validation
        uses: microsoft/psrule-action@v2
        with:
          inputPath: './Output'
          modules: 'PSRule.Rules.Azure'
          option: '.ps-rule/ps-rule.yaml'

      - name: Comment PR with Plan
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const plan = fs.readFileSync('./Output/plan-summary.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## EPAC Deployment Plan\n\n${plan}`
            });

# .github/workflows/epac-deploy.yml
name: EPAC Deploy (main branch)

on:
  push:
    branches: [main]
    paths:
      - 'Definitions/**'
      - 'Assignments/**'
      - 'Exemptions/**'

jobs:
  deploy-definitions:
    name: Deploy Policy Definitions
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: $
          tenant-id: $
          subscription-id: $

      - name: Install EPAC
        shell: pwsh
        run: Install-Module EnterprisePolicyAsCode -Force

      - name: Deploy Policy Definitions
        shell: pwsh
        run: |
          Deploy-PolicyPlan `
            -DefinitionsRootFolder ./Definitions `
            -PlanFile ./Output/policy-plan.json

  deploy-assignments:
    name: Deploy Policy Assignments
    needs: deploy-definitions
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: $
          tenant-id: $
          subscription-id: $

      - name: Deploy Assignments
        shell: pwsh
        run: |
          Deploy-RolesPlan `
            -DefinitionsRootFolder ./Definitions `
            -PlanFile ./Output/roles-plan.json

🔒 6. Seguridad

Políticas Críticas por Dominio

Seguridad de Red

{
  "network_policies": [
    {
      "name": "Deny-Public-IPs",
      "effect": "Deny",
      "scope": "Platform MG",
      "description": "Previene exposición accidental a internet"
    },
    {
      "name": "Require-NSG-Subnet",
      "effect": "Deny",
      "scope": "Landing Zones MG",
      "description": "Toda subnet debe tener NSG asociado",
      "ref": "https://techcommunity.microsoft.com/blog/azurenetworkingblog/manage-nsg-association-on-subnets-via-azure-policy/4243157"
    },
    {
      "name": "Enforce-Private-Endpoints",
      "effect": "Deny",
      "scope": "Platform + Corp Prod",
      "description": "Storage, SQL, KeyVault deben usar Private Endpoints"
    },
    {
      "name": "DNS-Private-Endpoint",
      "effect": "DeployIfNotExists",
      "scope": "Landing Zones MG",
      "description": "Registra automáticamente Private Endpoints en DNS privado"
    }
  ]
}

Cumplimiento ENS (España)

{
  "ens_initiative": {
    "name": "ini-ens-spain",
    "displayName": "Spain ENS - Esquema Nacional de Seguridad",
    "description": "Initiative aligning with Spain's National Security Framework",
    "ref": "https://learn.microsoft.com/es-es/azure/governance/policy/samples/spain-ens",
    "categories": [
      "Acceso al sistema",
      "Gestión de activos",
      "Continuidad del negocio",
      "Control de acceso",
      "Criptografía",
      "Auditoría y responsabilidad"
    ]
  }
}

Seguridad de Datos

{
  "data_security_policies": [
    {
      "name": "Require-Encryption-At-Rest",
      "effect": "Deny",
      "resources": ["Storage", "SQL", "CosmosDB", "KeyVault"]
    },
    {
      "name": "Enforce-TLS-1.2-Minimum",
      "effect": "Deny",
      "resources": ["Storage", "AppService", "APIManagement"]
    },
    {
      "name": "Deny-HTTP-AppService",
      "effect": "Deny",
      "description": "Fuerza HTTPS en todas las App Services"
    }
  ]
}

DenyAction - Protección contra Borrado

{
  "denyaction_policies": [
    {
      "name": "DenyAction-Delete-Recovery-Vault",
      "effect": "DenyAction",
      "action": "delete",
      "resource": "Microsoft.RecoveryServices/vaults",
      "description": "Previene borrado accidental de Recovery Services Vaults",
      "ref": "https://journeyofthegeek.com/2024/05/08/azure-authorization-resource-locks-and-azure-policy-denyactions/"
    },
    {
      "name": "DenyAction-Delete-Network-Hub",
      "effect": "DenyAction",
      "action": "delete",
      "resource": "Microsoft.Network/virtualNetworks",
      "scope": "Connectivity MG"
    }
  ]
}

Govern de Identidad y RBAC para Policy

Policy Management Permissions:
  Root MG:
    - Resource Policy Contributor: Governance-Team-Group
    - Policy Insights Data Writer: Automation-Service-Principal

  All MGs:
    - Reader: Security-Team (para auditoría de compliance)

  Remediation Managed Identities (por assignment):
    DINE-Diagnostics:
      - Role: Log Analytics Contributor
      - Scope: Landing Zones MG

    DINE-Backup:
      - Role: Backup Contributor
      - Scope: Corp-Prod MG

    Modify-Tags:
      - Role: Tag Contributor
      - Scope: Root MG

Custom Role "Policy Exemption Manager":
  Actions:
    - Microsoft.Authorization/policyExemptions/write
    - Microsoft.Authorization/policyExemptions/delete
    - Microsoft.Authorization/policyExemptions/read
  AssignableScope: Root MG
  Principals: Governance-Team-Group (via PIM)

💰 7. Costes

Modelo de Costes de Azure Policy

Nota: Solo cuentan evaluaciones de políticas con Guest Configuration, las demás son gratuitas. Las políticas de Regulatory Compliance (ENS, CIS, etc.) pueden tener coste.

Estimación para Enterprise (500+ suscripciones)

ROI de Gobernanza via Policy

Cost Governance via Policy

# Policy que fuerza tags de CostCenter en todos los recursos
az policy assignment create \
  --name "require-costcenter-tag" \
  --display-name "Require CostCenter tag" \
  --policy "/providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62" \
  --scope "/providers/Microsoft.Management/managementGroups/mg-root" \
  --params '{"tagName": {"value": "CostCenter"}}'

# Policy que hereda tags del Resource Group a recursos hijos
az policy assignment create \
  --name "inherit-rg-tags" \
  --policy-set-definition "Inherit a tag from the resource group" \
  --scope "/providers/Microsoft.Management/managementGroups/mg-root"

🧪 8. Pruebas y Validación

Azure CLI

# ============================================
# GESTIÓN DE POLICY DEFINITIONS
# ============================================

# Listar custom policies en un Management Group
az policy definition list \
  --management-group "mg-root" \
  --query "[?policyType=='Custom'].{Name:displayName, Mode:mode, Category:metadata.category}" \
  -o table

# Ver detalles de una policy definition
az policy definition show \
  --name "pol-sec-deny-publicip-v1" \
  --management-group "mg-root"

# Crear custom policy desde archivo JSON
az policy definition create \
  --name "pol-sec-deny-publicip-v1" \
  --display-name "[Contoso] Deny Public IPs" \
  --description "Denies creation of Public IP resources" \
  --rules "policy-rules.json" \
  --params "policy-params.json" \
  --mode "All" \
  --management-group "mg-root"

# Listar built-in policies por categoría
az policy definition list \
  --query "[?policyType=='BuiltIn' && metadata.category=='Security'].{Name:displayName, ID:name}" \
  -o table

# ============================================
# GESTIÓN DE INITIATIVES
# ============================================

# Listar todas las initiatives
az policy set-definition list \
  --management-group "mg-root" \
  --query "[?policyType=='Custom'].{Name:displayName, Policies:length(policyDefinitions)}" \
  -o table

# Ver políticas en una initiative
az policy set-definition show \
  --name "ini-security-baseline" \
  --management-group "mg-root" \
  --query "policyDefinitions[].{Policy:policyDefinitionId, Effect:parameters.effect.defaultValue}" \
  -o table

# ============================================
# GESTIÓN DE ASSIGNMENTS
# ============================================

# Listar todos los assignments en un MG (heredados inclusive)
az policy assignment list \
  --scope "/providers/Microsoft.Management/managementGroups/mg-corp-prod" \
  --disable-scope-strict-match \
  --query "[].{Name:displayName, Enforce:enforcementMode, Scope:scope}" \
  -o table

# Crear assignment con Managed Identity (para DINE)
az policy assignment create \
  --name "pa-diagnostics-baseline" \
  --display-name "Deploy Diagnostic Settings" \
  --policy-set-definition "ini-monitoring-baseline" \
  --scope "/providers/Microsoft.Management/managementGroups/mg-root" \
  --mi-system-assigned \
  --location "westeurope" \
  --identity-scope "/providers/Microsoft.Management/managementGroups/mg-root" \
  --role "Log Analytics Contributor"

# Deshabilitar enforcement (modo DoNotEnforce / Audit-only)
az policy assignment update \
  --name "pa-diagnostics-baseline" \
  --scope "/providers/Microsoft.Management/managementGroups/mg-root" \
  --enforcement-mode DoNotEnforce

# ============================================
# COMPLIANCE Y REMEDIATION
# ============================================

# Forzar evaluación de compliance (trigger scan)
az policy state trigger-scan \
  --resource-group "rg-app-prod"

# Ver resumen de compliance por Management Group
az policy state summarize \
  --management-group "mg-corp-prod" \
  --query "{Compliant:results.resourceDetails[?complianceState=='Compliant'].count, NonCompliant:results.resourceDetails[?complianceState=='NonCompliant'].count}"

# Listar recursos no conformes con detalle
az policy state list \
  --management-group "mg-corp-prod" \
  --filter "complianceState eq 'NonCompliant'" \
  --query "[].{Resource:resourceId, Policy:policyDefinitionName, Effect:additionalProperties.policyDefinitionEffect}" \
  -o table

# Crear Remediation Task
az policy remediation create \
  --name "remediate-diagnostics-$(date +%Y%m%d)" \
  --management-group "mg-corp-prod" \
  --policy-assignment "pa-diagnostics-baseline" \
  --resource-discovery-mode ReEvaluateCompliance

# Ver estado de remediation tasks
az policy remediation list \
  --management-group "mg-corp-prod" \
  --query "[].{Name:name, Status:properties.provisioningState, Succeeded:properties.deploymentStatus.successfulDeployments, Failed:properties.deploymentStatus.failedDeployments}" \
  -o table

# ============================================
# EXEMPTIONS
# ============================================

# Crear exemption con expiración obligatoria
az policy exemption create \
  --name "exempt-publicip-sandbox-2026" \
  --display-name "Temporary: Allow Public IPs in Sandbox" \
  --scope "/providers/Microsoft.Management/managementGroups/mg-sandbox" \
  --policy-assignment "/providers/Microsoft.Management/managementGroups/mg-root/providers/Microsoft.Authorization/policyAssignments/pa-deny-publicip-root" \
  --exemption-category Waiver \
  --expires-on "2026-06-30T00:00:00Z" \
  --description "Approved by: Governance Team | Ticket: GOV-2026-042 | Justification: Dev testing requires public access"

# Listar exemptions activas
az policy exemption list \
  --scope "/providers/Microsoft.Management/managementGroups/mg-root" \
  --query "[].{Name:displayName, Category:properties.exemptionCategory, Expires:properties.expiresOn}" \
  -o table

# ============================================
# EPAC WORKFLOW
# ============================================

# Instalar EPAC
Install-Module EnterprisePolicyAsCode -Force

# Build deployment plans
Build-DeploymentPlans \
  -DefinitionsRootFolder ./Definitions \
  -OutputFolder ./Output

# Deploy definitions
Deploy-PolicyPlan \
  -DefinitionsRootFolder ./Definitions \
  -PlanFile ./Output/policy-plan.json

# Export current state to source control
Export-AzPolicyResources \
  -DefinitionsRootFolder ./ExportedDefinitions \
  -Mode Export

PowerShell

# ============================================
# VALIDACIÓN DE ESTRUCTURA
# ============================================

Connect-AzAccount

# Listar todas las custom policies de un tenant
Get-AzPolicyDefinition -Custom |
  Select-Object -Property `
    @{N="Name"; E={$_.Properties.DisplayName}},
    @{N="Category"; E={$_.Properties.Metadata.Category}},
    @{N="Mode"; E={$_.Properties.Mode}},
    @{N="Effect"; E={$_.Properties.PolicyRule.then.effect}} |
  Format-Table -AutoSize

# Ver compliance general del tenant
Get-AzPolicyStateSummary -ManagementGroupName (Get-AzContext).Tenant.Id |
  Select-Object -ExpandProperty Results

# Exportar todas las non-compliant resources a CSV
Get-AzPolicyState `
  -ManagementGroupName "mg-corp-prod" `
  -Filter "complianceState eq 'NonCompliant'" |
  Select-Object ResourceId, PolicyDefinitionName, PolicyAssignmentName, ComplianceState |
  Export-Csv "./reports/noncompliant-$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation

# ============================================
# GESTIÓN DE ASSIGNMENTS
# ============================================

# Obtener todos los assignments con managed identity
Get-AzPolicyAssignment `
  -Scope "/providers/Microsoft.Management/managementGroups/mg-root" `
  -IncludeDescendent |
  Where-Object { $_.Identity.Type -ne $null } |
  Select-Object Name, @{N="IdentityType"; E={$_.Identity.Type}},
    @{N="PrincipalId"; E={$_.Identity.PrincipalId}} |
  Format-Table

# Verificar role assignments de managed identities de policies
$policyAssignments = Get-AzPolicyAssignment `
  -Scope "/providers/Microsoft.Management/managementGroups/mg-root" `
  -IncludeDescendent |
  Where-Object { $_.Identity.Type -eq "SystemAssigned" }

foreach ($pa in $policyAssignments) {
  $roles = Get-AzRoleAssignment -ObjectId $pa.Identity.PrincipalId
  if (-not $roles) {
    Write-Warning "Policy Assignment '$($pa.Properties.DisplayName)' has no role assignments!"
  }
}

# ============================================
# REMEDIATION MONITORING
# ============================================

function Get-PolicyRemediationStatus {
  param([string]$ManagementGroupId)

  $remediations = Get-AzPolicyRemediation -ManagementGroupId $ManagementGroupId

  $summary = $remediations | Group-Object { $_.ProvisioningState } |
    Select-Object Name, Count

  Write-Host "`n=== Remediation Summary for $ManagementGroupId ===" -ForegroundColor Cyan
  $summary | Format-Table

  $failed = $remediations | Where-Object { $_.ProvisioningState -eq "Failed" }
  if ($failed) {
    Write-Warning "Failed remediations detected:"
    $failed | Select-Object Name, PolicyAssignmentId | Format-Table
  }
}

Get-PolicyRemediationStatus -ManagementGroupId "mg-corp-prod"

# ============================================
# COMPLIANCE REPORT GENERATOR
# ============================================

function New-PolicyComplianceReport {
  param(
    [string]$ManagementGroupId,
    [string]$OutputPath = "./reports"
  )

  $date = Get-Date -Format 'yyyy-MM-dd'
  $states = Get-AzPolicyState -ManagementGroupName $ManagementGroupId
  $summary = $states | Group-Object ComplianceState |
    Select-Object @{N="State"; E={$_.Name}}, Count

  $byPolicy = $states |
    Where-Object { $_.ComplianceState -eq "NonCompliant" } |
    Group-Object PolicyDefinitionName |
    Select-Object @{N="Policy"; E={$_.Name}}, Count |
    Sort-Object Count -Descending

  $html = @"
<!DOCTYPE html>
<html>
<head><title>Policy Compliance Report - $date</title></head>
<body>
<h1>Azure Policy Compliance Report</h1>
<h2>Management Group: $ManagementGroupId</h2>
<h3>Date: $date</h3>
<h2>Summary</h2>
$(($summary | ConvertTo-Html -Fragment))
<h2>Top Non-Compliant Policies</h2>
$(($byPolicy | Select-Object -First 20 | ConvertTo-Html -Fragment))
</body>
</html>
"@

  New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null
  $html | Out-File "$OutputPath/compliance-report-$date.html"
  $states | Export-Csv "$OutputPath/compliance-raw-$date.csv" -NoTypeInformation
  Write-Host "Report saved to $OutputPath" -ForegroundColor Green
}

New-PolicyComplianceReport -ManagementGroupId "mg-root"

Tests Automatizados (Pester + PSRule)

# tests/AzurePolicy.Tests.ps1
Describe "Azure Policy Governance Tests" {

  BeforeAll {
    Connect-AzAccount -Identity
    $tenantId = (Get-AzContext).Tenant.Id
  }

  Context "Policy Definition Quality" {

    It "All custom policies should have a version in metadata" {
      $policies = Get-AzPolicyDefinition -Custom
      foreach ($policy in $policies) {
        $policy.Properties.Metadata.Version | Should -Not -BeNullOrEmpty `
          -Because "$($policy.Properties.DisplayName) must be versioned"
      }
    }

    It "All custom policies should have a category" {
      $policies = Get-AzPolicyDefinition -Custom
      foreach ($policy in $policies) {
        $policy.Properties.Metadata.Category | Should -Not -BeNullOrEmpty
      }
    }

    It "DINE policies should use parameterized effect" {
      $dinePolicies = Get-AzPolicyDefinition -Custom |
        Where-Object { $_.Properties.PolicyRule.then.effect -like "*DeployIfNotExists*" }
      foreach ($policy in $dinePolicies) {
        $effect = $policy.Properties.PolicyRule.then.effect
        $effect | Should -Match "\[parameters\(" `
          -Because "Effects should be parameterized, not hardcoded"
      }
    }
  }

  Context "Assignment Coverage" {

    It "Root MG should have Require-Tags policy" {
      $assignment = Get-AzPolicyAssignment `
        -Scope "/providers/Microsoft.Management/managementGroups/$tenantId" |
        Where-Object { $_.Properties.DisplayName -match "tag" }
      $assignment | Should -Not -BeNullOrEmpty
    }

    It "All Production MGs should have backup policy assigned" {
      $prodMGs = Get-AzManagementGroup |
        Where-Object { $_.DisplayName -like "*Production*" -or $_.DisplayName -like "*Prod*" }
      foreach ($mg in $prodMGs) {
        $backupPolicy = Get-AzPolicyAssignment -Scope $mg.Id |
          Where-Object { $_.Properties.DisplayName -match "backup" }
        $backupPolicy | Should -Not -BeNullOrEmpty `
          -Because "$($mg.DisplayName) must enforce backup"
      }
    }

    It "DINE assignments should have managed identity" {
      $allAssignments = Get-AzPolicyAssignment `
        -Scope "/providers/Microsoft.Management/managementGroups/$tenantId" `
        -IncludeDescendent
      foreach ($pa in $allAssignments) {
        $policyDef = Get-AzPolicyDefinition -Id $pa.Properties.PolicyDefinitionId -ErrorAction SilentlyContinue
        if ($policyDef.Properties.PolicyRule.then.effect -like "*DeployIfNotExists*") {
          $pa.Identity | Should -Not -BeNullOrEmpty `
            -Because "$($pa.Properties.DisplayName) is DINE and needs managed identity"
        }
      }
    }
  }

  Context "Exemption Governance" {

    It "All exemptions should have expiration date" {
      $exemptions = Get-AzPolicyExemption -Scope "/providers/Microsoft.Management/managementGroups/$tenantId"
      foreach ($ex in $exemptions) {
        $ex.Properties.ExpiresOn | Should -Not -BeNullOrEmpty `
          -Because "Exemption '$($ex.Properties.DisplayName)' must have expiry date"
      }
    }

    It "No exemptions should be expired" {
      $exemptions = Get-AzPolicyExemption -Scope "/providers/Microsoft.Management/managementGroups/$tenantId"
      $expired = $exemptions | Where-Object {
        $_.Properties.ExpiresOn -ne $null -and
        [DateTime]$_.Properties.ExpiresOn -lt (Get-Date)
      }
      $expired | Should -BeNullOrEmpty -Because "Expired exemptions must be removed"
    }
  }

  Context "Compliance Thresholds" {

    It "Production MGs compliance rate should exceed 90%" {
      $states = Get-AzPolicyState -ManagementGroupName "mg-corp-prod"
      $total = $states.Count
      $compliant = ($states | Where-Object { $_.ComplianceState -eq "Compliant" }).Count
      $rate = if ($total -gt 0) { ($compliant / $total) * 100 } else { 100 }
      $rate | Should -BeGreaterThan 90 -Because "Production compliance must exceed 90%"
    }
  }
}

Invoke-Pester -Path "./tests/AzurePolicy.Tests.ps1" -Output Detailed

📝 9. Decisiones (ADR)

ADR-001: EPAC como framework principal de Policy as Code

• Fecha: 2025-09-01
• Estado: ✅ Aceptado
• Contexto: Necesitábamos gestionar 200+ policy assignments a través de 15 Management Groups de forma reproducible y auditada
• Decisión: Adoptar Enterprise Policy as Code (EPAC) como framework oficial de Policy as Code
• Alternativas consideradas:
  1. Terraform puro (azurerm provider)
  2. Bicep + ARM Templates
  3. Azure CLI scripts en pipelines
  4. Manual via portal
• Consecuencias:
  • ✅ Framework diseñado específicamente para Azure Policy a escala
  • ✅ Soporte oficial de Microsoft
  • ✅ Integración nativa con AMBA (Azure Monitor Baseline Alerts)
  • ✅ Drift detection incorporado
  • ✅ Export de estado actual a código
  • ⚠️ Curva de aprendizaje en JSONC y estructura EPAC
  • ⚠️ Dependencia de módulo PowerShell (no HCL)
  • ⚠️ No gestiona otros recursos Azure (solo policy)

ADR-002: Efecto parametrizado en todas las custom policies

• Fecha: 2025-09-15
• Estado: ✅ Aceptado
• Contexto: Necesitábamos poder cambiar el efecto (Deny→Audit) sin modificar la definición
• Decisión: Toda custom policy debe exponer el efecto como parámetro con defaultValue apropiado por entorno
• Consecuencias:
  • ✅ Una definición → múltiples comportamientos según entorno
  • ✅ Rollout gradual: empezar en Audit, promover a Deny
  • ✅ Testing seguro en Sandbox sin riesgo de bloqueos
  • ⚠️ Assignments más verbosos con parámetros

ADR-003: Versionado explícito de built-in policies en assignments

• Fecha: 2025-11-01
• Estado: ✅ Aceptado
• Contexto: Microsoft actualiza built-in policies automáticamente, lo que puede romper comportamientos esperados
• Decisión: Usar versiones fijas en Policy Assignments en producción (feature en Public Preview 2024)
• Ref: Public Preview Built-in Policy Versioning: https://techcommunity.microsoft.com/t5/azure-governance-and-management/public-preview-announcement-azure-policy-built-in-versioning/ba-p/4186105
• Consecuencias:
  • ✅ Cambios en built-ins no afectan producción sin revisión
  • ✅ Pipeline de actualización controlada de versiones
  • ⚠️ Requiere proceso activo de actualización de versiones

ADR-004: Exemptions siempre con expiración y ticket

• Fecha: 2025-10-01
• Estado: ✅ Aceptado
• Contexto: Las exemptions sin control crean deuda de gobernanza
• Decisión: Toda exemption DEBE tener: expires_on (máximo 90 días), approvedBy, ticketNumber en metadata
• Consecuencias:
  • ✅ No hay exemptions eternas
  • ✅ Trazabilidad completa de excepciones
  • ✅ Revisión trimestral obligatoria
  • ⚠️ Proceso formal de aprobación requerido

ADR-005: Initiative de Monitoring aplicada en Root MG

• Fecha: 2025-10-20
• Estado: ✅ Aceptado
• Contexto: Necesitábamos garantizar que TODOS los recursos envíen telemetría a Log Analytics
• Decisión: DINE Diagnostic Settings initiative asignada en Root MG, en modo DoNotEnforce inicialmente, promovida a Enforce tras 60 días
• Consecuencias:
  • ✅ Cobertura de monitoring al 100% del tenant
  • ✅ Remediación automática de recursos existentes
  • ⚠️ Managed Identity con permisos amplios sobre el tenant

ADR-006: AMBA para alertas de Azure Monitor vía Policy

• Fecha: 2025-12-01
• Estado: ✅ Aceptado
• Contexto: Necesitábamos alertas de monitoreo consistentes sin configuración manual
• Decisión: Adoptar Azure Monitor Baseline Alerts (AMBA) deployado via EPAC
• Ref: https://www.azuredoctor.com/posts/automate-azure-alerts-with-amba/
• Consecuencias:
  • ✅ Alertas baseline para 40+ tipos de recursos automáticamente
  • ✅ Mantenido por Microsoft/comunidad
  • ✅ Integración nativa con EPAC
  • ⚠️ Requiere Action Groups configurados previamente

🔗 10. Referencias

📚 Recursos Adicionales

Scripts Útiles

• Export Policy State: scripts/export-policy-state.ps1 → Exporta estado actual a EPAC
• Compliance Report: scripts/generate-compliance-report.ps1 → Reporte HTML semanal
• Remediation Trigger: scripts/trigger-remediation.ps1 → Lanza remediación masiva
• Exemption Audit: scripts/audit-exemptions.ps1 → Lista exemptions próximas a expirar
• Policy Drift Check: scripts/check-epac-drift.ps1 → Detecta drift vs source control

Diagramas

• Policy Anatomy: _assets/diagrams/policy-anatomy.drawio
• EPAC Pipeline: _assets/diagrams/epac-cicd-flow.drawio
• Assignment Matrix: _assets/diagrams/policy-assignments-matrix.xlsx
• Effect Decision Tree: _assets/diagrams/policy-effect-decision-tree.drawio

Runbooks

• Nueva Custom Policy: runbooks/create-custom-policy.md
• Proceso de Exemption: runbooks/policy-exemption-request.md
• Rollout de Deny Policy: runbooks/deny-policy-rollout.md (Audit → Enforce en fases)
• Remediation Masiva: runbooks/mass-remediation.md
• Actualización de Built-in: runbooks/update-builtin-policy-version.md

Última actualización: 2026-02-18 Próxima revisión: 2026-05-18 Owner: Luis Adán Muñoz (@LuisAdan) Reviewers: Platform Team, Security Team, Compliance Team

🎯 Quick Start Commands

# Ver compliance actual del tenant
az policy state summarize --management-group "$(az account show --query tenantId -o tsv)"

# Ver top 10 non-compliant policies
az policy state list --management-group "mg-root" \
  --filter "complianceState eq 'NonCompliant'" \
  --query "[].policyDefinitionName" -o tsv | sort | uniq -c | sort -rn | head -10

# Desplegar con EPAC
Build-DeploymentPlans -DefinitionsRootFolder ./Definitions -OutputFolder ./Output
Deploy-PolicyPlan -DefinitionsRootFolder ./Definitions -PlanFile ./Output/policy-plan.json

# Generar reporte de compliance
pwsh ./scripts/generate-compliance-report.ps1 -ManagementGroupId "mg-root"

# Auditar exemptions próximas a expirar
pwsh ./scripts/audit-exemptions.ps1 -DaysToExpiry 14

¿Preguntas? Contacta al equipo de Governance en Slack: #governance-team o abre un issue en el repositorio.

Introducción: De Documentación a Security Intelligence

En la primera versión de DocAzureAutomatic, revolucionamos cómo documentamos infraestructura Azure: exportación automática de ARM templates, generación de Markdown detallado y reportes HTML profesionales. Pero en el mundo cloud actual, documentar qué tienes ya no es suficiente. Necesitas saber si lo que tienes es seguro.

DocAzureAutomatic v2 da el siguiente paso evolutivo: combina documentación automática con análisis de seguridad de clase enterprise usando Prowler y Checkov, las herramientas preferidas por equipos de DevSecOps a nivel mundial.

🎯 ¿Qué hay de nuevo en v2?

1. Unificación Total: DocAzureAutomatic_AllInOne.ps1

La arquitectura se simplifica drásticamente. Lo que antes requería dos scripts separados (PowerShell + Python) ahora es un solo archivo ejecutable:

graph TB
    A[DocAzureAutomatic_AllInOne.ps1] --> B[Azure Login & Export]
    B --> C[ARM Templates JSON]
    C --> D[Markdown Generation]
    D --> E[Python Embebido]
    E --> F[HTML + CSS]
    
    style A fill:#0078D4,color:#fff
    style F fill:#00AA00,color:#fff

Beneficios de la unificación:

• ✅ Un solo comando para ejecutar todo el pipeline
• ✅ Python embebido dentro del script PowerShell
• ✅ Cero dependencias de archivos externos (excepto styles.css)
• ✅ Deployment más simple en entornos corporativos
• ✅ Menos superficie de error

2. Análisis de Seguridad con Prowler + Checkov

La estrella de v2: make-report.v2.ps1, un orchestrator de seguridad que:

graph LR
    A[ARM JSON Files] --> B[Prowler Azure Runtime]
    A --> C[Checkov Static Analysis]
    B --> D[Prowler Reports]
    C --> E[Checkov SARIF]
    D --> F[Unified HTML Dashboard]
    E --> F
    
    style B fill:#FF6B35,color:#fff
    style C fill:#4ECDC4,color:#fff
    style F fill:#95E1D3,color:#000

Prowler: Análisis en tiempo real contra las suscripciones de Azure. Detecta misconfigurations, vulnerabilidades de compliance y desviaciones de best practices directamente en tu tenant.

Checkov: Análisis estático de tus ARM templates exportados. Encuentra issues antes de desplegar, valida contra CIS Benchmarks, PCI-DSS, HIPAA y más.

3. Entorno Virtual Python para Aislamiento

v2 introduce gestión profesional de dependencias con virtual environments:

# Instalación aislada de herramientas
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install prowler checkov

Ventajas del venv:

• 🔒 Aislamiento de dependencias (no contaminas el Python global)
• 🔄 Versionado reproducible de herramientas
• 🚀 Portabilidad: lleva tu .venv a cualquier máquina
• 👥 Colaboración en equipo sin conflictos de versiones

🏗️ Arquitectura Completa del Sistema v2

sequenceDiagram
    participant User
    participant AllInOne as DocAzureAutomatic_AllInOne.ps1
    participant Azure as Azure ARM API
    participant MakeReport as make-report.v2.ps1
    participant Prowler
    participant Checkov
    
    User->>AllInOne: Ejecutar pipeline
    AllInOne->>Azure: az login + export ARM
    Azure-->>AllInOne: JSON templates
    AllInOne->>AllInOne: Generate Markdown
    AllInOne->>AllInOne: Python MD→HTML
    AllInOne-->>User: Documentación HTML
    
    User->>MakeReport: Ejecutar análisis seguridad
    MakeReport->>Azure: Crear SP temporal + RBAC
    MakeReport->>Prowler: Scan runtime Azure
    Prowler-->>MakeReport: HTML + JSON reports
    MakeReport->>Checkov: Scan ARM JSON
    Checkov-->>MakeReport: SARIF findings
    MakeReport->>MakeReport: Parse + HTML unificado
    MakeReport-->>User: Dashboard seguridad
    MakeReport->>Azure: Cleanup SP temporal

🛠️ Componentes Técnicos en Detalle

DocAzureAutomatic_AllInOne.ps1: El Nuevo Monolito Inteligente

Fase 1: Autenticación y Descubrimiento

# Login interactivo con selección de suscripciones
az login --tenant $TenantId

# Lista todas las suscripciones del tenant
$subscriptions = az account list --all --output json | ConvertFrom-Json

Fase 2: Exportación Masiva de ARM Templates

# Por cada suscripción → Por cada Resource Group
foreach ($rg in $resourceGroups) {
    az group export --name $rg --include-parameter-default-value --output json
}

Genera estructura:

PlantillasARM/
├── Produccion/
│   ├── RG-WebApps_template.json
│   ├── RG-Databases_template.json
│   └── Resumen.md
└── Desarrollo/
    ├── RG-DevEnv_template.json
    └── Resumen.md

Fase 3: Procesamiento JSON → Markdown

El script implementa un flatten algorithm que descompone objetos JSON anidados en propiedades planas:

function Expand-FlattenObject {
    param([hashtable]$Object, [string]$Prefix = '')
    # Convierte { properties: { config: { value: 10 } } }
    # En: properties.config.value = 10
}