# 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

```bash
pip install gettopology
```

For the latest alpha version:
```bash
pip install gettopology==0.1.0a1
```

Or install pre-release versions:
```bash
pip install --pre gettopology
```

## 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:

```bash
# Get topology for all VNets in all accessible subscriptions
gettopology

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

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

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

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

# Specify output directory for diagrams
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:
```bash
gettopology --client-id "your-client-id" \
            --client-secret "your-secret" \
            --tenant-id "your-tenant-id"
```

Or use environment variables:
```bash
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:
```bash
# .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](https://app.diagrams.net/) (web)
- [diagrams.net](https://www.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

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

