azure-resource-visualizer

개요

azure-resource-visualizer란?

azure-resource-visualizer는 Azure 리소스 그룹을 분석해 사람이 읽기 쉬운 아키텍처 문서로 변환하는, Azure에 특화된 시각화 스킬입니다. 리소스와 해당 설정, 그리고 리소스 간 관계를 검사한 뒤, 클라우드 토폴로지를 설명하는 상세한 Mermaid 다이어그램과 마크다운 파일을 만들어 냅니다.

가상 네트워크, 서브넷, App Service, 데이터베이스, 보안 구성 요소 등이 어떻게 서로 연결되어 있는지 수작업으로 다이어그램을 그리는 대신, azure-resource-visualizer가 자동으로 리소스를 탐색하고 다이어그램을 생성해 최신 상태의 환경 구성을 빠르게 파악할 수 있습니다.

주요 기능

• 리소스 그룹 검색 – 리소스 그룹이 지정되지 않은 경우 Azure 리소스 그룹을 나열하고 선택을 돕습니다.
• 심층 리소스 분석 – 리소스 그룹 내부의 리소스, 설정, 상호 의존성을 분석합니다.
• 관계 매핑 – 컴퓨팅, 네트워크, 데이터, 보안 리소스 간 연결 관계를 식별하고 문서화합니다.
• Mermaid 다이어그램 생성 – 마크다운, 문서 사이트, 위키 등에 바로 사용할 수 있는 구문이 올바른 Mermaid 다이어그램을 생성합니다.
• 아키텍처 문서화 – 인벤토리, 상위 수준 요약, 다이어그램 삽입 등을 포함할 수 있는 마크다운 페이지를 생성합니다.

이런 분께 적합합니다

다음과 같은 경우 azure-resource-visualizer를 사용하는 것이 좋습니다.

• 검토용·설계 문서를 위해 빠르게 시각적인 아키텍처 다이어그램이 필요한 클라우드 아키텍트
• 리소스 그룹 내 서비스들이 어떻게 연결되어 있는지 파악하려는 개발자 또는 DevOps 엔지니어
• 구독 및 팀 전반에서 문서 형식을 표준화하려는 플랫폼/인프라 엔지니어
• 네트워크 흐름과 의존 관계를 명확히 파악해야 하는 보안·운영 엔지니어

이미 Azure 리소스가 배포된 상태에서 인사이트, 문서화, 온보딩용 자료가 필요할 때 특히 유용하며, 아직 설계 단계에서 종이 위에만 구상하고 있는 경우에는 적합하지 않습니다.

해결해 주는 문제들

• 다이어그램 도구에서 Azure 다이어그램을 수 시간에 걸쳐 수동으로 그려야 하는 문제
• 대형 리소스 그룹 내 리소스 간 관계를 이해하기 어려운 문제
• 실제 배포 상태와 일치하지 않는 오래된 아키텍처 문서 문제
• 리소스 그룹별로 일관되고 검토 가능한 마크다운 문서가 부족한 문제

azure-resource-visualizer를 쓰면 좋은 경우, 좋지 않은 경우

적합한 경우:

• 기존 Azure 인프라에 대해 데이터 시각화 및 리포팅이 필요할 때
• 마크다운, 레포지토리, 내부 문서 포털에 Mermaid 다이어그램을 통합하고 싶을 때
• 리소스 메타데이터 조회를 위해 Azure Resource Graph나 az를 사용하고 있을 때

적합하지 않은 경우:

• Azure 리소스를 프로비저닝하거나 변경하는 도구가 필요한 경우 (이 스킬은 배포가 아닌 분석과 시각화에 초점이 맞춰져 있습니다.)
• 비용 분석, 성능 모니터링, 보안 스캐닝이 필요할 때 – 이들은 범위 밖입니다.
• Azure 구독 메타데이터에 접근할 수 없거나 az/Azure Resource Graph 쿼리를 실행할 수 없는 경우

사용 방법

사전 준비 사항

azure-resource-visualizer를 사용하기 전에 다음을 준비하세요.

• 하나 이상의 리소스 그룹이 있는 활성 Azure 구독
• 해당 구독에서 리소스를 조회할 수 있는 권한
• CLI 기반 검색을 사용하는 환경이라면 설치 및 로그인된 Azure CLI (az)
• Azure Resource Graph 쿼리를 사용할 계획이라면 Resource Graph CLI 확장 기능:
  • az extension add --name resource-graph

위 준비가 되어 있어야 스킬(또는 이를 사용하는 에이전트)이 리소스 그룹을 나열하고, 리소스 및 관계를 조사할 수 있습니다.

azure-resource-visualizer 스킬 설치

microsoft/azure-skills 레포지토리에서 azure-resource-visualizer를 추가하려면 skills CLI를 사용합니다.

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

이 명령은 스킬 정의와 연관된 에셋(예제, 템플릿, 참고 자료)을 로컬 스킬 환경으로 가져와, 에이전트나 워크플로가 해당 스킬을 호출할 수 있게 합니다.

포함된 파일 이해하기

설치 후에는 skills/azure-resource-visualizer 아래의 핵심 파일과 폴더를 확인하세요.

• SKILL.md – 스킬의 핵심 정의, 역할, 워크플로 가이드가 담긴 파일
• assets/example-diagram.md – 일반적인 Azure 리소스와 계층이 어떻게 표현되는지 보여주는 완전한 Mermaid 다이어그램 예제
• assets/template-architecture.md – 리소스 인벤토리와 다이어그램 섹션 자리표시자를 포함한 전체 아키텍처 리포트용 마크다운 템플릿
• references/azure-resource-graph.md – Azure Resource Graph를 사용해 대규모 리소스를 검색하기 위한 가이드와 KQL 예제

이 파일들을 보면 "좋은" 출력물이 어떤 형태인지, 그리고 자체 아키텍처 문서를 어떻게 구성하면 좋을지 감을 잡을 수 있습니다.

일반적인 워크플로: 리소스 그룹에서 다이어그램까지

1단계: 리소스 그룹 선택 또는 검색

사용자가 리소스 그룹 이름을 지정하지 않은 경우, 스킬 워크플로는 다음 단계를 따르도록 설계되어 있습니다.

1. 일반적으로 az 또는 Azure Resource Graph와 같은 도구를 사용해 리소스 그룹 목록을 조회합니다.
2. 이름과 위치를 포함한 번호 매긴 목록으로 보여줍니다.
3. 어떤 리소스 그룹을 분석할지 사용자에게 묻습니다.

이미 리소스 그룹이 정해져 있다면 검색 단계를 건너뛰고 곧바로 분석으로 진행할 수 있습니다.

2단계: 리소스 및 관계 검색

리소스 그룹을 선택하면 azure-resource-visualizer는 다음에 집중합니다.

• 그룹 내 모든 리소스(타입, 이름, 위치, SKU 등 주요 설정)를 나열
• 리소스 간 연결 관계 파악 – 예를 들어, 어떤 App Service가 어떤 서브넷을 사용하는지, 어떤 Function App이 어떤 데이터베이스와 통신하는지, 어떤 ID가 Key Vault에 접근하는지 등

이 작업은 다음과 같은 도구를 사용해 수행할 수 있습니다.

• --resource-group로 필터링한 az 명령
• references/azure-resource-graph.md에 있는 것과 유사한 KQL 패턴을 활용한 az graph query

3단계: Mermaid 아키텍처 다이어그램 생성

그다음 스킬은 분석 결과를 Mermaid 다이어그램으로 변환합니다. 전체 스타일은 assets/example-diagram.md 예제에 잘 나타나 있습니다.

• subgraph 블록을 활용한 계층별 그룹화 예:
  • Network Layer (VNets, subnets, NSGs)
  • Compute Layer (App Service plans, App Services, Functions)
  • Data Layer (databases, storage)
  • Security & Identity (Key Vault, managed identities)
• 주소 범위, SKU, 런타임 버전 등 주요 설정 정보를 보여주는 상세 노드 라벨
• "HTTPS requests", "SQL connection", "Blob/Queue access"와 같이 관계를 설명하는 텍스트가 포함된 설명형 엣지

생성된 다이어그램은 표준 Mermaid 구문이므로 GitHub 마크다운, 문서 생성기, 다양한 다이어그램 미리보기 도구에서 그대로 사용할 수 있습니다.

4단계: 마크다운으로 아키텍처 리포트 작성

각 리소스 그룹에 대해 구조화된 리포트를 만들 때는 assets/template-architecture.md를 시작점으로 사용하세요.

• 구독, 지역, 리소스 수, 생성일시 등 헤더 정보를 채웁니다.
• 솔루션의 목적과 핵심 구성 요소를 설명하는 짧은 개요를 작성합니다.
• 리소스 이름, 타입, SKU, 위치, 메모 등을 포함한 Resource Inventory 표를 채웁니다.
• 생성된 Mermaid 다이어그램을 Architecture Diagram 섹션에 붙여 넣습니다.
• 발견한 관계를 기반으로 Network Architecture, Data Flow, Identity & Access, Dependencies 설명을 추가합니다.
• 향후 개선 사항이나 리스크를 정리한 Notes & Recommendations를 기록합니다.

이렇게 하면 여러 팀·구독에서 재사용 가능한 반복 가능한 리포팅 패턴을 만들 수 있습니다.

활용 예시

• 신규 팀원 온보딩 – 핵심 프로덕션 리소스 그룹에 대해 azure-resource-visualizer를 실행하고 생성된 마크다운을 공유해 신규 인력이 시스템 구성을 빠르게 이해하도록 돕습니다.
• 변경 전 검토(Pre-change review) – 인프라 변경 전 리소스 그룹을 다이어그램으로 시각화해 의존성 및 영향 범위를 파악합니다.
• 아키텍처 문서 최신화 – 정기적으로 스킬을 다시 실행해 다이어그램과 인벤토리를 업데이트하고, 문서가 실제 운영 환경과 항상 일치하도록 유지합니다.

FAQ

azure-resource-visualizer가 Azure 리소스를 배포하거나 수정하나요?

그렇지 않습니다. azure-resource-visualizer는 분석, 시각화, 문서화에 초점을 맞춘 스킬입니다. az나 Azure Resource Graph 같은 쿼리 도구를 사용해 기존 Azure 리소스를 검사하고, 그 결과를 Mermaid 다이어그램과 마크다운으로 출력할 뿐입니다. 리소스를 생성, 변경, 삭제하지 않습니다.

azure-resource-visualizer는 어떤 도구에 의존하나요?

이 스킬은 기존 Azure 도구를 대체하는 것이 아니라, 그와 함께 사용하도록 설계되었습니다. 일반적인 사용 시 다음에 의존합니다.

• 리소스 그룹 및 리소스를 나열하기 위한 Azure CLI (az)
• 선택적으로, references/azure-resource-graph.md에 나와 있는 것처럼 빠른 크로스 구독 쿼리를 위한 Azure Resource Graph (az graph query)

에이전트나 워크플로를 어떻게 구성했는지에 따라 세부 설정은 달라질 수 있지만, 기본적으로 az가 설치되어 있고 인증되어 있어야 합니다.

azure-resource-visualizer는 여러 구독에 걸쳐서도 사용할 수 있나요?

가능합니다. 환경과 쿼리가 크로스 구독 검색을 지원하도록 구성되어 있다면, Azure Resource Graph를 사용해 여러 구독의 리소스를 조회한 뒤, 분석 대상을 특정 리소스 그룹 또는 그룹 집합으로 제한할 수 있습니다. 스킬의 역할은 선택한 리소스 그룹에 초점을 맞추며, 해당 그룹이 어느 구독에 속해 있는지는 중요하지 않습니다.

azure-resource-visualizer는 어떤 종류의 다이어그램을 생성하나요?

azure-resource-visualizer는 Mermaid 기반 아키텍처 다이어그램을 생성합니다. 이 다이어그램은 다음과 같은 특징을 가집니다.

• Network, Compute, Data, Security & Identity 등 계층별 subgraph 섹션 사용
• VNet 주소 공간, SKU, 런타임 등 주요 속성이 표시된 라벨 노드 포함
• 컴포넌트 간 상호 작용을 설명하는 텍스트가 포함된 방향성 엣지 표시

출력은 일반 Mermaid 코드이므로 마크다운 파일, GitHub README, Mermaid를 지원하는 문서 사이트 등에 그대로 삽입할 수 있습니다.

생성된 문서를 커스터마이징할 수 있나요?

가능합니다. assets/template-architecture.md 파일은 처음부터 템플릿 용도로 작성되었습니다. 다음과 같이 활용할 수 있습니다.

• 섹션을 조정(표, 헤딩, 메모 섹션 추가/삭제)하여 조직에 맞게 구성
• 조직 표준에 맞는 용어와 형식으로 통일
• 에이전트나 스크립트를 통해 자동 생성할 때 기본 템플릿으로 사용

이 스킬의 목표는 일관된 구조를 제공하는 것이며, 이후 프로세스에 맞게 어떻게 변형할지는 전적으로 사용자에게 달려 있습니다.

azure-resource-visualizer는 아주 작은 테스트 환경에도 유용한가요?

리소스 그룹 크기와 상관없이 사용할 수 있지만, 리소스와 관계가 많아 수동으로 다이어그램을 그리기 번거로울수록 가치가 커집니다. 단일 테스트 VM이나 최소한의 데모 환경이라면 도입 비용이 크지 않을 수 있습니다. 반대로 다중 계층 애플리케이션, 공유 서비스, 복잡한 네트워크 구성을 가진 환경에서는 매우 유용합니다.

azure-resource-visualizer는 얼마나 자주 실행하는 것이 좋나요?

환경에 대한 신뢰할 수 있는 뷰가 필요할 때마다 실행하는 것이 좋습니다.

• 눈에 띄는 인프라 변경 이후
• 아키텍처 리뷰나 감사(Audit) 이전
• 문서를 실제 환경과 동기화하기 위한 정기 일정(예: 매월 또는 분기별)

이 스킬은 읽기 전용이며 쿼리 기반 검색을 사용하므로, 필요한 만큼 자주 재실행해도 안전합니다.

구체적인 출력 예시는 어디에서 볼 수 있나요?

스킬 디렉터리 내에서 확인할 수 있습니다.

• assets/example-diagram.md에는 계층 구조와 주석이 포함된 Mermaid 아키텍처 다이어그램의 완성 예제가 들어 있습니다.
• assets/template-architecture.md는 해당 다이어그램을 중심으로 전체 아키텍처 리포트를 어떻게 구성할 수 있는지 보여 줍니다.

이 두 파일을 살펴보는 것이, azure-resource-visualizer가 여러분의 Azure 리소스 그룹에 대해 어떤 결과물을 만들어 줄 수 있는지 가장 빠르게 이해하는 방법입니다.