Azure Network Calculator

Customization

Before executing, check for user customizations at: ~/.claude/skills/PAI/USER/SKILLCUSTOMIZATIONS/azure-network-calculator-skill/

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.

MANDATORY: Voice Notification (REQUIRED BEFORE ANY ACTION)

You MUST send this notification BEFORE doing anything else when this skill is invoked.

1. Send voice notification:

   curl -s -X POST http://localhost:8888/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running the WORKFLOWNAME workflow in the azure-network-calculator-skill skill to ACTION"}' \
     > /dev/null 2>&1 &

2. Output text notification:

   Running the **WorkflowName** workflow in the **azure-network-calculator-skill** skill to ACTION...

This is not optional. Execute this curl command immediately upon skill invocation.

azure-network-calculator-skill

Automates CIDR calculation, subnet allocation, and Terraform code generation for Hypera's Azure hub-spoke infrastructure.

Workflow Routing

If the user's intent is ambiguous, ask which workflow to run.

Quick Reference

CIDR Hierarchy

/13  (subscription)  = 524,288 addresses = 128 x /20 VNets
/20  (VNet)          =   4,096 addresses =  16 x /24 subnets
/24  (subnet)        =     256 addresses =     251 usable (Azure reserves 5)
/22  (large subnet)  =   1,024 addresses =   1,019 usable
/27  (gateway)       =      32 addresses =      27 usable
/26  (firewall)      =      64 addresses =      59 usable

VNet Index Formula

VNet[i] address = subscription_base + (i * 4096)    # 4096 = 2^(32-20)
VNet[i] CIDR    = calculated_address/20

Each /13 subscription holds exactly 128 /20 VNets (index 0-127).

Azure Reserved IPs (5 per subnet)

Naming Convention

snet-{purpose}-{rg}-{env}-{region}
vnet-{rg}-{env}-{region}
nsg-{purpose}-{rg}-{env}-{region}
natg-{rg}-{env}-{region}

Where {rg} is the resource group name (without rg-hypera- prefix), {env} is dev/hlg/prd, {region} is the shortcode (e.g., eus).

Context Files

---

Gotchas

• Azure reserves 5 IPs per subnet (network, gateway, DHCP, broadcast + 1 reserved): /29 has 3 usable, not 5; /28 has 11, not 13.
• NSG rule count cap: 1000 per NSG — ASGs reduce rule count but introduce coupling between resource groups.
• VNet peering doesn't support transitive routing — hub-spoke designs need Azure Firewall or NVA as an explicit hop; a hub-as-router assumption fails.
• IPv6 dual-stack on AKS: requires preview feature flag; subnet calculations must size both v4 AND v6 explicitly.
• Subnet delegation locks the subnet — once delegated to a service (e.g., AKS, App Service), it can't be undelegated without recreating.

CIDR Master Allocation

Source of truth for Hypera's Azure network address space. Update this file when VNets are deployed.

Subscription CIDR Allocation

Each subscription receives a /13 block (524,288 addresses, 128 x /20 VNets).

VNet Index Formula

A /13 contains exactly 128 /20 VNets.

Given subscription base B (e.g., 10.248.0.0 for infrastructure-dev):

VNet index i (0-127):
  octet2 = B.octet2 + floor((i * 16) / 256)
  octet3 = (i * 16) mod 256
  VNet[i] = B.octet1 . (B.octet2 + floor(i*16/256)) . ((i*16) mod 256) . 0 / 20

Shortcut: each /20 is 4,096 addresses = 16 x /24 blocks
  VNet[i] address = base_ip + (i * 4096)

Examples for infrastructure-dev (10.248.0.0/13):

Known VNet Allocations

Keep this table updated when new VNets are deployed.

AKS Overlay CIDR Pairs

AKS clusters using Azure CNI Overlay use non-VNet address space for pods and services. Each pair uses a /16 from the 172.20-29.0.0 range.

Rule: Even = Pod CIDR, Odd = Service CIDR. Allocate sequentially.

/24 Blocks Within a /20

Each /20 VNet contains exactly 16 /24 blocks:

VNet base X.Y.Z.0/20:
  Block 0:  X.Y.(Z+0).0/24
  Block 1:  X.Y.(Z+1).0/24
  ...
  Block 15: X.Y.(Z+15).0/24

Each /24 provides 256 addresses (251 usable after Azure reserves 5).

Subnet Templates

Four workload archetypes covering ~90% of Hypera deployments. For custom layouts, use these as starting points and adjust.

Template 1: Hub Network

For centralized connectivity, firewall, bastion, and shared services.

Total /24 blocks consumed: ~7 of 16 (gateway+fw+bastion share block 0, shared=block 1, AKS=blocks 2-5) Next available: block 6 (+6.0)

Offset calculation example (VNet base 10.136.16.0/20):

• GatewaySubnet: 10.136.16.0/27
• AzureFirewallSubnet: 10.136.16.64/26
• AzureBastionSubnet: 10.136.16.128/26
• snet-shared-services: 10.136.17.0/24
• snet-aks-nodes: 10.136.18.0/22

Template 2: 3-Tier App (Dev)

Standard development environment with application, data, and integration tiers.

Total /24 blocks consumed: 5 of 16 Next available: block 5 (+5.0)

Offset calculation example (VNet base 10.144.16.0/20):

• snet-app-tier: 10.144.16.0/24
• snet-data-tier: 10.144.17.0/24
• snet-integration: 10.144.18.0/24
• snet-private-endpoints: 10.144.19.0/24
• snet-aks-nodes: 10.144.20.0/24

Template 3: 3-Tier App (Prd)

Production environment — same structure as dev but with /22 AKS subnet for scale.

Total /24 blocks consumed: 8 of 16 (4 x /24 + 1 x /22 = 4 + 4) Next available: block 8 (+8.0)

Offset calculation example (VNet base 10.136.32.0/20):

• snet-app-tier: 10.136.32.0/24
• snet-data-tier: 10.136.33.0/24
• snet-integration: 10.136.34.0/24
• snet-private-endpoints: 10.136.35.0/24
• snet-aks-nodes: 10.136.36.0/22

Template 4: Packer/DevOps

Infrastructure tooling — image builds, CI/CD agents, automation. Matches rg-hypera-packer-image pattern.

Total /24 blocks consumed: ~4 of 16 (blocks 12, 14, 15 used; 0-11 and 13 free) Next available: block 0 (+0.0)

Note: This template leaves blocks 0-11 and 13 intentionally free for workload subnets and private endpoints. Additional subnets can be added:

• snet-workload-01: block 1 (+1.0, /24)
• snet-private-endpoints: block 2 (+2.0, /24)

Offset calculation example (VNet base 10.248.0.0/20):

• snet-private: 10.248.12.0/24
• snet-public: 10.248.14.0/24
• snet-gateway: 10.248.15.0/27
• AzureBastionSubnet: 10.248.15.32/27

Applying Templates

To apply a template to a VNet base address:

1. Take the VNet base (e.g., 10.160.0.0/20) 2. Parse octets: A.B.C.0 where C is the third octet 3. For each subnet, add the offset to the third and fourth octets:

• +N.M means: third_octet = C + N, fourth_octet = M

4. Apply the mask

Service endpoints by template:

Terraform Snippets

HCL templates matching the existing rg-hypera-packer-image repo patterns. Uses AVM (Azure Verified Modules).

VNet + Subnets Module Block

Uses Azure/avm-res-network-virtualnetwork/azurerm. Match the version to the project's current pin.

module "virtualnetwork" {
  source  = "Azure/avm-res-network-virtualnetwork/azurerm"
  version = "~> 0.8.0"

  name                = local.vnet_name
  resource_group_name = azurerm_resource_group.RESOURCE_GROUP.name
  location            = azurerm_resource_group.RESOURCE_GROUP.location
  address_space       = var.vnet_address_space
  tags                = local.common_tags

  subnets = {
    "SUBNET_KEY" = {
      name                                          = "SUBNET_NAME"
      address_prefixes                              = var.SUBNET_VAR
      private_link_service_network_policies_enabled = true
      private_endpoint_network_policies_enabled     = true
      service_endpoints = [
        # Add as needed: Microsoft.Sql, Microsoft.Storage, etc.
      ]
      # Optional: NAT Gateway association
      nat_gateway = {
        id = module.avm_nat_gateway.resource_id
      }
      # Optional: NSG association
      network_security_group = {
        id = azurerm_network_security_group.NSG_NAME.id
      }
    }
  }
}

Special Azure Subnet Names

These subnets MUST use exact names — do not apply naming conventions:

• GatewaySubnet — VPN/ExpressRoute gateway
• AzureFirewallSubnet — Azure Firewall
• AzureBastionSubnet — Azure Bastion

Variable Declarations

Pattern from variables.tf:

variable "vnet_address_space" {
  description = "VNet address space CIDR"
  type        = list(string)
}

variable "vnet_subnet_PURPOSE" {
  description = "Subnet CIDR for PURPOSE"
  type        = list(string)
}

Naming Locals

Pattern from name.tf:

locals {
  # VNet
  vnet_name = "vnet-${var.resource_group_name}-${var.environment}-${var.azure_region_shortcode}"

  # Subnets (custom names follow snet- convention)
  subnet_PURPOSE_name = "snet-PURPOSE-${var.resource_group_name}-${var.environment}-${var.azure_region_shortcode}"

  # Azure-mandated names (no convention applied)
  subnet_bastion_name = "AzureBastionSubnet"
  subnet_gateway_name = "GatewaySubnet"  # or snet-gateway-... for non-VPN gateways

  # NSG
  nsg_PURPOSE_name = "nsg-PURPOSE-${var.resource_group_name}-${var.environment}-${var.azure_region_shortcode}"

  # NAT Gateway
  nat_gateway_name     = "natg-${var.resource_group_name}-${var.environment}-${var.azure_region_shortcode}"
  nat_gateway_pip_name = "natg-pip-${var.resource_group_name}-${var.environment}-${var.azure_region_shortcode}"
}

NSG Association

Pattern from nsg.tf:

resource "azurerm_network_security_group" "PURPOSE-nsg" {
  name                = local.nsg_PURPOSE_name
  location            = azurerm_resource_group.RESOURCE_GROUP.location
  resource_group_name = azurerm_resource_group.RESOURCE_GROUP.name
  tags                = local.common_tags

  # Inbound: Bastion SSH/RDP
  security_rule {
    name                       = "Allow_Bastion_Inbound"
    priority                   = 100
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "*"
    destination_port_ranges    = ["22", "3389"]
    source_address_prefix      = "BASTION_SUBNET_CIDR"
    destination_address_prefix = "*"
  }

  # Outbound: HTTPS, HTTP, DNS
  security_rule {
    name                       = "Allow_HTTPS_Outbound"
    priority                   = 100
    direction                  = "Outbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "*"
    destination_port_range     = "443"
    source_address_prefix      = "*"
    destination_address_prefix = "Internet"
  }

  security_rule {
    name                       = "Allow_HTTP_Outbound"
    priority                   = 110
    direction                  = "Outbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "*"
    destination_port_range     = "80"
    source_address_prefix      = "*"
    destination_address_prefix = "Internet"
  }

  security_rule {
    name                       = "Allow_DNS_Outbound"
    priority                   = 120
    direction                  = "Outbound"
    access                     = "Allow"
    protocol                   = "*"
    source_port_range          = "*"
    destination_port_range     = "53"
    source_address_prefix      = "*"
    destination_address_prefix = "Internet"
  }
}

NAT Gateway

Pattern from natg.tf using AVM module:

module "avm_nat_gateway" {
  source  = "Azure/avm-res-network-natgateway/azurerm"
  version = "0.2.1"

  name                    = local.nat_gateway_name
  location                = azurerm_resource_group.RESOURCE_GROUP.location
  resource_group_name     = azurerm_resource_group.RESOURCE_GROUP.name
  idle_timeout_in_minutes = 4
  sku_name                = "Standard"
  tags                    = local.common_tags
  enable_telemetry        = var.enable_avm_telemetry
  zones                   = null  # Non-zonal for dev; ["1","2","3"] for prd

  public_ip_prefix_length = 0  # Manage prefix externally

  public_ips = {
    "NATG_PIP_KEY" = {
      name = local.nat_gateway_pip_name
    }
  }

  public_ip_configuration = {
    allocation_method       = "Static"
    sku                     = "Standard"
    zones                   = []
    ddos_protection_mode    = "VirtualNetworkInherited"
    idle_timeout_in_minutes = 4
  }
}

AKS Network Profile (Azure CNI Overlay)

resource "azurerm_kubernetes_cluster" "aks" {
  # ... other config ...

  network_profile {
    network_plugin      = "azure"
    network_plugin_mode = "overlay"
    service_cidr        = "OVERLAY_SERVICE_CIDR"  # e.g., 172.25.0.0/16
    dns_service_ip      = "OVERLAY_SERVICE_BASE+10"  # e.g., 172.25.0.10
    pod_cidr            = "OVERLAY_POD_CIDR"  # e.g., 172.24.0.0/16
  }
}

tfvars Pattern

vnet_address_space = ["VNET_CIDR"]

vnet_subnet_PURPOSE = ["SUBNET_CIDR"]
# Repeat for each subnet

CalculateCapacity Workflow

Show remaining network capacity at subscription or VNet level.

Inputs

One of: 1. Subscription name — show /20 VNet capacity (e.g., infrastructure-dev) 2. VNet CIDR — show /24 subnet capacity within that VNet (e.g., 10.248.0.0/20) 3. No input — show summary across all subscriptions

Mode 1: Subscription Capacity

Steps

1. Read CidrMasterAllocation.md 2. Find the subscription's /13 base 3. Count known VNet allocations for that subscription 4. Calculate:

• Total /20 slots: 128
• Used: count of known allocations
• Free: 128 - used
• Next available index and CIDR

Output

## Subscription Capacity: {subscription}

| Metric | Value |
|--------|-------|
| Subscription CIDR | {base}/13 |
| Total /20 VNet slots | 128 |
| Used | {count} |
| Free | {128 - count} |
| Utilization | {percent}% |
| Next available index | {index} |
| Next available CIDR | {cidr}/20 |

### Known Allocations
| Index | CIDR | Resource Group | Purpose |
|-------|------|----------------|---------|
| ... | ... | ... | ... |

Mode 2: VNet Capacity

Steps

1. Parse the VNet CIDR to get base address 2. Identify which subscription it belongs to 3. Look up known subnet allocations within this VNet from CidrMasterAllocation.md and any additional sources 4. Map all 16 /24 blocks

Output

## VNet Capacity: {vnet_cidr}

| Metric | Value |
|--------|-------|
| VNet CIDR | {cidr}/20 |
| Subscription | {subscription} |
| Total /24 blocks | 16 |
| Used/Reserved | {count} |
| Free | {16 - count} |
| Next available | {next_cidr}/24 |

### /24 Block Map
| Block | CIDR | Status | Usage |
|-------|------|--------|-------|
| 0 | X.Y.Z.0/24 | Free/Active/Reserved | {description} |
| 1 | X.Y.(Z+1).0/24 | ... | ... |
| ... | ... | ... | ... |
| 15 | X.Y.(Z+15).0/24 | ... | ... |

Note: Blocks partially consumed by /22 or /27 subnets should be marked accordingly (e.g., "Part of snet-aks-nodes /22").

Mode 3: All Subscriptions Summary

Steps

1. Read all known allocations from CidrMasterAllocation.md 2. Summarize per subscription

Output

## Network Capacity Summary (All Subscriptions)

| Subscription | CIDR | VNets Used | VNets Free | Utilization | Next Available |
|---|---|---|---|---|---|
| hub-spoke | 10.128.0.0/13 | 0 | 128 | 0% | 10.128.0.0/20 |
| operacoes | 10.136.0.0/13 | 3 | 125 | 2.3% | 10.136.48.0/20 |
| ... | ... | ... | ... | ... | ... |

**Total:** {total_used} / {16 * 128} VNets used across all subscriptions

Calculating Arbitrary Subnets

If the user asks "calculate subnets for X.Y.Z.0/20", enumerate all 16 /24 blocks:

Block 0:  X.Y.(Z+0).0/24   — 256 addresses (251 usable)
Block 1:  X.Y.(Z+1).0/24   — 256 addresses (251 usable)
...
Block 15: X.Y.(Z+15).0/24  — 256 addresses (251 usable)

For non-/24 subdivisions, show the requested mask size and how many fit:

• /22 in /20 = 4 blocks
• /25 in /24 = 2 blocks
• /27 in /24 = 8 blocks
• /26 in /24 = 4 blocks

PlanNetwork Workflow

Design a complete VNet + subnet layout for a new resource group, with Terraform code generation.

Inputs

Gather these from the user (ask if not provided):

1. Subscription — which of the 16 subscriptions (e.g., solucoes-dev, infrastructure-dev) 2. Workload type — one of: hub, 3tier-dev, 3tier-prd, packer-devops, or custom 3. Resource group name — e.g., rg-hypera-painelclientes 4. Environment — dev, hlg, or prd 5. Region — defaults to eastus (shortcode eus) 6. VNet index — specific index or "next available" (default) 7. Include AKS? — if yes, allocate overlay CIDRs

Steps

Step 1: Load Master Allocation

Read CidrMasterAllocation.md:

• Find the subscription's /13 base address
• List known VNet allocations for that subscription
• Determine next available VNet index (if not specified)

Step 2: Calculate VNet CIDR

subscription_base = from master table (e.g., 10.160.0.0 for solucoes-dev)
vnet_index = next available or user-specified
vnet_base_offset = vnet_index * 4096

# Convert offset to octets:
octet2_add = floor(vnet_index * 16 / 256)
octet3 = (vnet_index * 16) mod 256

vnet_cidr = subscription_base.octet1 . (subscription_base.octet2 + octet2_add) . octet3 . 0 / 20

Verify: The calculated VNet falls within the subscription's /13 range.

Step 3: Load Subnet Template

Read SubnetTemplates.md and load the selected archetype.

Step 4: Calculate Subnet CIDRs

For each subnet in the template: 1. Parse the VNet base: A.B.C.0 2. Apply offset: A.B.(C + offset_octet3).(offset_octet4) / mask 3. Calculate usable hosts: 2^(32-mask) - 5

Step 5: Apply Naming Convention

For each subnet:

snet-{purpose}-{rg_short}-{env}-{region_short}

Where rg_short strips the rg-hypera- prefix from the resource group name.

Azure-mandated names (GatewaySubnet, AzureFirewallSubnet, AzureBastionSubnet) override this convention.

Step 6: Allocate AKS Overlay CIDRs (if applicable)

Read the AKS Overlay CIDR table in CidrMasterAllocation.md:

• Find next available pair
• Assign: even = Pod CIDR, odd = Service CIDR
• DNS Service IP = Service CIDR base + 10

Step 7: Generate Terraform Code

Read TerraformSnippets.md and produce:

• networking.tf — VNet module block with all subnets
• variables.tf additions — variable declarations for each CIDR
• name.tf additions — naming locals
• terraform.tfvars additions — concrete CIDR values
• nsg.tf additions (if template includes NSG)
• natg.tf additions (if template includes NAT Gateway)

Step 8: Output

Present a structured summary:

## Network Plan: {resource_group} ({subscription})

### VNet
| Property | Value |
|----------|-------|
| Name | vnet-{name}-{env}-{region} |
| CIDR | X.Y.Z.0/20 |
| Range | X.Y.Z.0 - X.Y.(Z+15).255 |
| Index | {index} of 128 |

### Subnets
| Name | CIDR | Usable Hosts | Purpose |
|------|------|--------------|---------|
| ... | ... | ... | ... |

### AKS Overlay (if applicable)
| Component | CIDR |
|-----------|------|
| Pod CIDR | 172.XX.0.0/16 |
| Service CIDR | 172.XX.0.0/16 |
| DNS Service IP | 172.XX.0.10 |

### Capacity After Allocation
| Metric | Value |
|--------|-------|
| VNets used / total | X / 128 |
| /24 blocks used in this VNet | X / 16 |
| Next available /24 in VNet | X.Y.Z.0/24 |

### Terraform Code
[generated HCL]

Validation Checklist

Before presenting output, verify:

• [ ] VNet CIDR falls within subscription's /13 range
• [ ] No overlap with known VNet allocations
• [ ] All subnet CIDRs fall within the VNet's /20 range
• [ ] No subnet CIDRs overlap each other
• [ ] /22 subnets are aligned to /22 boundaries (third octet divisible by 4 relative to VNet base)
• [ ] Azure-mandated subnet names are used where required
• [ ] AKS overlay CIDRs don't conflict with existing allocations

ValidateCidr Workflow

Check whether a CIDR range is valid, within a known subscription, and free from overlaps.

Inputs

1. CIDR to validate — e.g., 10.248.0.0/20 or 10.144.17.0/24

Steps

Step 1: Parse the CIDR

Extract:

• Network address
• Prefix length (mask)
• Range start (network address)
• Range end (broadcast address)
• Total addresses: 2^(32 - mask)

Step 2: Identify Subscription

Read CidrMasterAllocation.md.

For each subscription, check if the input CIDR falls entirely within the subscription's /13 range:

• Input start >= subscription start AND input end <= subscription end

If no subscription matches: FAIL — "CIDR is outside all known subscription ranges."

Step 3: Check VNet-Level Overlap

For the matched subscription, check against all known VNet allocations:

Two CIDRs overlap if:

range_a_start <= range_b_end AND range_b_start <= range_a_end

For each known VNet in the subscription:

• If overlap detected: FAIL — "Overlaps with {VNet name} ({VNet CIDR})"

Step 4: Check Subnet-Level Overlap

If the input is a subnet-sized CIDR (/24 or smaller), also check against known subnet allocations within the containing VNet.

Step 5: Validate Alignment

• If /20: verify third octet is a multiple of 16 (relative to subscription base)
• If /22: verify third octet is a multiple of 4 (relative to VNet base)
• If /24: verify fourth octet is 0
• If /27: verify fourth octet is 0, 32, 64, 96, 128, 160, 192, or 224
• If /26: verify fourth octet is 0, 64, 128, or 192

If misaligned: WARN — "CIDR is not naturally aligned for its mask."

Step 6: Output

## CIDR Validation: {input_cidr}

| Check | Result | Details |
|-------|--------|---------|
| Valid CIDR | PASS/FAIL | {parsed details} |
| Within subscription | PASS/FAIL | {subscription name} ({subscription CIDR}) |
| No VNet overlap | PASS/FAIL | {overlap details if any} |
| No subnet overlap | PASS/FAIL/N/A | {overlap details if any} |
| Alignment | PASS/WARN | {alignment details} |

**Overall: PASS / FAIL**

If FAIL, suggest the nearest valid alternative:

• Next available VNet index (for /20)
• Next available /24 block within the VNet (for /24)