gettopology 0.1.0a2

CLI tool for generating Azure VNet topology diagrams with enhanced features

GetTopology

⚠️ Alpha Release - This is an alpha version. Features may change and bugs may exist.

CLI tool for generating Azure VNet topology diagrams with enhanced features.

Installation

pip install gettopology

For the latest alpha version:

pip install gettopology==0.1.0a1

Requirements

• Python 3.10 or higher
• Azure subscription with appropriate permissions
• Azure CLI installed and configured (or Service Principal credentials)

Usage

After installation, use the gettopology command:

# Get topology for all VNets in all accessible subscriptions
gettopology

# Get topology for specific subscriptions [optional]
gettopology -s "subscription-id-1,subscription-id-2"

# Get topology from subscriptions listed in a file [optional]
gettopology -f subscriptions.txt

# Get topology for specific VNets across all subscriptions [optional]
gettopology -vnet "vnet-name-1,vnet-name-2"

# Combine filters: specific subscriptions and VNets [optional]
gettopology -s "sub-id-1,sub-id-2" -vnet "vnet-1,vnet-2"

# Specify output directory for diagrams [optional]
gettopology -s "sub-id" -o ./diagrams

# Set log level
gettopology --log-level DEBUG 

# Skip role verification (role checking is enabled by default)
gettopology --skip-roles

Command Line Arguments

• -s, --subscriptions: Comma-separated subscription IDs (optional)
• -f, --subscriptions-file: Path to file containing subscription IDs, one per line (optional)
• -vnet, --virtual-network: Comma-separated list of VNet names to filter (optional)
• -o, --output: Output directory for generated diagrams (default: current directory)
• --log-level: Logging level - DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
• --skip-roles: Skip role verification. By default, the tool verifies that the authenticated user/service principal has at least 'Reader' role on subscriptions before proceeding (optional)
• --version: Display version information

Authentication

The tool supports multiple authentication methods, tried in this order:

1. Azure CLI (first): Uses az login credentials - tried first if available
2. Service Principal (second): Provide via CLI arguments, environment variables, or .env file
3. Managed Identity (third): Automatically used when running in Azure (e.g., Azure VM, App Service, Functions)

What is Managed Identity?
Managed Identity is Azure's way of providing Azure resources (like VMs, App Services, etc.) with an automatically managed identity. When the tool runs inside Azure, it can authenticate using the resource's managed identity without needing explicit credentials. This is the third fallback method if Azure CLI and Service Principal authentication are not available.

For Service Principal authentication:

gettopology --client-id "your-client-id" \
            --client-secret "your-secret" \
            --tenant-id "your-tenant-id"

Or use environment variables:

export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-secret"
export AZURE_TENANT_ID="your-tenant-id"
gettopology

Or create a .env file in your project directory:

# .env file
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-secret
AZURE_TENANT_ID=your-tenant-id

Priority order for Service Principal credentials:

1. CLI arguments (--client-id, --client-secret, --tenant-id)
2. Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
3. .env file (in current directory or project root)

Output

The tool generates Draw.io (.drawio) format diagrams that can be opened in:

• Draw.io (web)
• diagrams.net (desktop)
• Visual Studio Code (with Draw.io extension)

Diagrams include:

• Hub and spoke VNets with visual distinction
• Peering connections with color-coded lines
• Subnet details within VNet boxes
• External VNets (cross-subscription/tenant peerings)
• Separate pages for hubless spokes and orphan VNets

Development

This project uses several code quality tools:

• Ruff: Fast Python linter and formatter
• mypy: Static type checker
• Bandit: Security vulnerability scanner
• pytest: Testing framework

To install development dependencies:

# Using uv (installs from [dependency-groups])
uv sync --group dev

# Or install in editable mode with dev dependencies
uv pip install -e ".[dev]"

Run code quality checks:

# Linting
uv run ruff check src/

# Type checking
uv run mypy src/

# Security scanning
uv run bandit -r src/ -c pyproject.toml

# Tests will be added on later version
uv run pytest tests/

License

This project is licensed under the MIT License - see the LICENSE file for details.