azure-resource-visualizer

Descripción general

¿Qué es azure-resource-visualizer?

azure-resource-visualizer es una skill de visualización centrada en Azure diseñada para examinar tus grupos de recursos de Azure y convertirlos en documentación de arquitectura clara y legible para personas. Inspecciona los recursos, sus configuraciones y sus relaciones, y luego produce diagramas Mermaid detallados y archivos markdown que describen tu topología en la nube.

En lugar de reconstruir manualmente cómo encajan redes virtuales, subredes, app services, bases de datos y componentes de seguridad, azure-resource-visualizer automatiza el descubrimiento y la creación de diagramas para que obtengas una vista actualizada de tu entorno.

Capacidades principales

• Descubrimiento de grupos de recursos: lista y te ayuda a seleccionar grupos de recursos de Azure cuando no se especifica ninguno.
• Análisis profundo de recursos: examina los recursos, sus configuraciones y sus interdependencias dentro de un grupo de recursos.
• Mapeo de relaciones: identifica y documenta conexiones entre recursos de cómputo, red, datos y seguridad.
• Generación de diagramas Mermaid: genera diagramas Mermaid completos y con sintaxis correcta, listos para markdown, sitios de documentación o wikis.
• Documentación de arquitectura: genera páginas en markdown que pueden incluir inventarios, resúmenes de alto nivel y diagramas incrustados.

¿Para quién es esta skill?

Utiliza azure-resource-visualizer si eres:

• Un arquitecto cloud que necesita diagramas de arquitectura visuales y rápidos para revisiones y documentos de diseño.
• Un desarrollador o ingeniero DevOps que quiere entender cómo se conectan los servicios dentro de un grupo de recursos.
• Un ingeniero de plataforma/infraestructura que busca estandarizar la documentación entre suscripciones y equipos.
• Un ingeniero de seguridad u operaciones que necesita una visión clara de los flujos de red y las dependencias.

Encaja mejor cuando ya tienes recursos en Azure desplegados y necesitas visibilidad, documentación o material de onboarding, no cuando solo estás planificando un diseño sobre el papel.

Problemas que resuelve

• Pasar horas dibujando manualmente diagramas de Azure en herramientas de diagramación.
• Dificultad para entender cómo se relacionan los recursos dentro de un grupo de recursos grande.
• Documentación de arquitectura desactualizada que no coincide con lo que realmente está desplegado.
• Falta de documentación en markdown consistente y revisable para cada grupo de recursos.

Cuándo azure-resource-visualizer es (y no es) una buena opción

Buena opción cuando:

• Quieres visualización de datos y reporting sobre infraestructura de Azure existente.
• Necesitas diagramas Mermaid integrados en markdown, repos o portales internos de documentación.
• Estás trabajando con Azure Resource Graph o az para consultar metadatos de recursos.

No es ideal cuando:

• Necesitas una herramienta para aprovisionar o cambiar recursos de Azure (esta skill se centra en análisis y visualización, no en despliegue).
• Buscas análisis de costes, monitorización de rendimiento o escaneo de seguridad: eso queda fuera de su alcance.
• No tienes acceso a metadatos de la suscripción de Azure o no puedes ejecutar consultas az/Azure Resource Graph.

Cómo usarla

Requisitos previos

Antes de usar azure-resource-visualizer, asegúrate de tener:

• Una suscripción de Azure activa con uno o más grupos de recursos.
• Acceso y permisos para consultar recursos en esas suscripciones.
• La Azure CLI (az) instalada e iniciada sesión, si tu configuración se basa en descubrimiento vía CLI.
• La extensión de CLI Resource Graph si piensas usar consultas de Azure Resource Graph:
  • az extension add --name resource-graph

Estos requisitos permiten que la skill (o el agente que la usa) liste grupos de recursos e inspeccione los recursos y sus relaciones.

Instalación de la skill azure-resource-visualizer

Para añadir azure-resource-visualizer desde el repositorio microsoft/azure-skills, utiliza la skills CLI:

npx skills add https://github.com/microsoft/azure-skills --skill azure-resource-visualizer

Esto descarga la definición de la skill y los recursos relacionados (ejemplos, plantillas y referencias) en tu configuración local de skills para que tu agente o flujo de trabajo pueda invocarla.

Entender los archivos incluidos

Tras la instalación, revisa estos archivos y carpetas clave en skills/azure-resource-visualizer:

• SKILL.md: definición principal de la skill, sus responsabilidades y orientación de flujo de trabajo.
• assets/example-diagram.md: un diagrama Mermaid de ejemplo completo que muestra cómo se representan los recursos y capas típicos de Azure.
• assets/template-architecture.md: una plantilla en markdown para un informe de arquitectura completo, que incluye inventario de recursos y secciones de marcador de posición para diagramas.
• references/azure-resource-graph.md: guía y ejemplos de KQL para usar Azure Resource Graph y descubrir recursos a escala.

Estos archivos muestran cómo se ve un buen resultado y cómo estructurar tu propia documentación de arquitectura.

Flujo de trabajo típico: del grupo de recursos al diagrama

Paso 1: Seleccionar o descubrir un grupo de recursos

Si el usuario no ha especificado un nombre de grupo de recursos, el flujo de la skill está diseñado para:

1. Utilizar las herramientas disponibles (habitualmente az o Azure Resource Graph) para listar grupos de recursos.
2. Presentar una lista numerada con nombres y ubicaciones.
3. Preguntar al usuario qué grupo de recursos se debe analizar.

Si ya se conoce un grupo de recursos, la skill puede omitir el descubrimiento y pasar directamente al análisis.

Paso 2: Descubrir recursos y relaciones

Una vez seleccionado el grupo de recursos, azure-resource-visualizer se centra en:

• Listar todos los recursos del grupo (tipo, nombre, ubicación y configuración relevante como SKUs).
• Identificar cómo se conectan los recursos: por ejemplo, qué app services usan qué subredes, qué function apps se comunican con qué bases de datos o cómo las identidades acceden a Key Vault.

Esto puede hacerse con herramientas como:

• Comandos az filtrados por --resource-group.
• az graph query con patrones KQL similares a los de references/azure-resource-graph.md.

Paso 3: Generar un diagrama de arquitectura en Mermaid

La skill transforma luego sus hallazgos en un diagrama Mermaid. El ejemplo en assets/example-diagram.md ilustra el estilo general:

• Agrupación por capas usando bloques subgraph, como:
  • Network Layer (VNets, subnets, NSGs)
  • Compute Layer (App Service plans, App Services, Functions)
  • Data Layer (databases, storage)
  • Security & Identity (Key Vault, managed identities)
• Etiquetas detalladas en los nodos que muestran detalles clave de configuración como rangos de direcciones, SKUs o versiones de runtime.
• Aristas descriptivas que etiquetan las relaciones, como "HTTPS requests", "SQL connection" o "Blob/Queue access".

El diagrama generado usa sintaxis estándar de Mermaid, por lo que funciona en markdown de GitHub, generadores de documentación y muchas herramientas de previsualización de diagramas.

Paso 4: Construir el informe de arquitectura en markdown

Utiliza assets/template-architecture.md como punto de partida para crear un informe estructurado para cada grupo de recursos:

• Rellena el encabezado con suscripción, región, número de recursos y fecha de generación.
• Escribe una breve descripción general de la solución, su propósito y sus componentes críticos.
• Completa la tabla de Inventario de recursos con nombres, tipos, SKUs, ubicaciones y notas.
• Pega el diagrama Mermaid generado en la sección Architecture Diagram.
• Añade descripciones de Network Architecture, Data Flow, Identity & Access y Dependencies basadas en las relaciones descubiertas.
• Recoge Notas y recomendaciones para futuras mejoras o riesgos.

Esto crea un patrón de reporting repetible que puede utilizarse en varios equipos o suscripciones.

Escenarios de uso habituales

• Onboarding de un nuevo miembro del equipo: ejecuta azure-resource-visualizer sobre los grupos de recursos de producción principales y comparte el markdown generado para que las personas nuevas entiendan rápidamente el diseño del sistema.
• Revisión previa a cambios: diagrama un grupo de recursos antes de realizar cambios de infraestructura para ver las dependencias y el posible radio de impacto.
• Actualización de la documentación de arquitectura: vuelve a ejecutar periódicamente la skill, actualiza diagramas e inventarios y mantén la documentación alineada con el entorno en producción.

Preguntas frecuentes (FAQ)

¿azure-resource-visualizer despliega o modifica recursos de Azure?

No. azure-resource-visualizer se centra en análisis, visualización y documentación. Examina tus recursos existentes en Azure usando herramientas de consulta como az y Azure Resource Graph, y luego genera diagramas Mermaid y markdown. No crea, actualiza ni elimina recursos.

¿De qué herramientas depende azure-resource-visualizer?

La skill está diseñada para trabajar junto con las herramientas existentes de Azure, no para sustituirlas. En un uso típico, se apoya en:

• Azure CLI (az) para listar grupos de recursos y recursos.
• Opcionalmente, Azure Resource Graph (az graph query) para consultas rápidas entre suscripciones, como se ilustra en references/azure-resource-graph.md.

Tu configuración concreta puede variar según cómo esté montado tu agente o flujo de trabajo, pero deberías contar con az instalado y autenticado.

¿azure-resource-visualizer puede trabajar entre varias suscripciones?

Sí, siempre que tu entorno y tus consultas estén configurados para descubrimiento entre suscripciones. Usando Azure Resource Graph, puedes consultar recursos en varias suscripciones y luego acotar el análisis a un grupo de recursos concreto o a un conjunto de grupos. Las responsabilidades de la skill se centran en los grupos de recursos que elijas, independientemente de la suscripción.

¿Qué tipo de diagramas genera azure-resource-visualizer?

azure-resource-visualizer genera diagramas de arquitectura basados en Mermaid. Estos diagramas:

• Usan secciones subgraph por capas (Network, Compute, Data, Security & Identity).
• Incluyen nodos etiquetados con propiedades clave (como espacios de direcciones de VNet, SKUs, runtimes).
• Muestran aristas direccionales con texto que describe cómo interactúan los componentes.

La salida es código Mermaid estándar que puedes incrustar directamente en archivos markdown, READMEs de GitHub o sitios de documentación que soporten Mermaid.

¿Puedo personalizar la documentación generada?

Sí. El archivo assets/template-architecture.md está pensado explícitamente como plantilla. Puedes:

• Adaptar las secciones (añadir o eliminar tablas, encabezados o secciones de notas).
• Estandarizar lenguaje y formatos para tu organización.
• Usar la plantilla como base para generación automatizada por parte de tu agente o scripts.

El objetivo de la skill es proporcionar una estructura consistente; cómo la adaptes a tus procesos depende de ti.

¿azure-resource-visualizer es adecuado para entornos de prueba muy pequeños?

Puede usarse con grupos de recursos de cualquier tamaño, pero aporta más valor cuando hay suficientes recursos y relaciones como para que la diagramación manual sea tediosa. Para una única VM de prueba o una demo mínima, puede que el esfuerzo adicional no compense. Para aplicaciones multinivel, servicios compartidos y configuraciones de red complejas, se vuelve mucho más útil.

¿Con qué frecuencia debo ejecutar azure-resource-visualizer?

Ejecuta la skill siempre que necesites una vista fiable de tu entorno:

• Después de cambios importantes de infraestructura.
• Antes de revisiones de arquitectura o auditorías.
• De forma periódica (por ejemplo, mensual o trimestral) para mantener la documentación sincronizada.

Como la skill es de solo lectura y usa descubrimiento basado en consultas, es seguro ejecutarla tantas veces como sea necesario.

¿Dónde puedo ver ejemplos concretos del resultado?

Dentro del directorio de la skill:

• assets/example-diagram.md contiene un ejemplo completo de diagrama de arquitectura en Mermaid, con capas y relaciones anotadas.
• assets/template-architecture.md muestra cómo estructurar un informe de arquitectura completo alrededor de ese diagrama.

Revisar estos archivos es la forma más rápida de entender qué puede producir azure-resource-visualizer para tus propios grupos de recursos de Azure.