Task 08 — Logical Network Creation
DOCUMENT CATEGORY: Implementation Guide
SCOPE: Phase 06 — Post-Deployment | Azure Local
PURPOSE: Create all logical networks defined ininfrastructure.yml. Each entry is MASTER REFERENCE: Azure Local Logical Networks provisioned as an Azure resource on the cluster's Hyper-V vSwitch, providing the network layer for Arc VM deployment — with Static IP pools or Dynamic (DHCP) allocation, VLAN isolation, and optional static routes, exactly as configured.
Status: Active
Objective: Create every logical network entry in networking.logical_networks[] on the
Azure Local cluster. The Orchestrated script reads the YAML config and deploys each network
as-configured — Static or Dynamic, with or without routes. The Standalone script has
hardcoded values for one-off use or when running outside the toolkit.
Logical networks bind to a Hyper-V vSwitch (already on the cluster from deployment) and
map to a physical VLAN. Switch VLAN configuration and the network intents (networking.intents[]) were completed
during Phase 05. This task creates the Azure resource representations.
Prerequisites:
- Azure Local cluster deployed and Arc-enabled (Phase 05 complete)
- CSV volumes created and healthy (Task 05 complete)
az stack-hci-vmCLI extension installed:az extension add --name stack-hci-vm- Azure identity authenticated:
az loginorConnect-AzAccount powershell-yamlmodule installed:Install-Module powershell-yaml -Scope CurrentUsernetworking.logical_networksblock populated ininfrastructure.yml
Values from infrastructure.yml
The script reads these keys from infrastructure.yml (schema 5). Each key, with its type, default and example, is in the variables reference.
azure.tenant_id, azure.subscription_id, azure.resource_group, azure.location, azure.custom_location, tags, cluster.name, sdn.enabled
networking.network_security_groups[]: name
networking.logical_networks[]: name, enabled, ip_allocation_method, vlan_id, address_prefix, gateway, dns_servers, ip_pool.start,
ip_pool.end, nsg_name, vm_switch_name
Create Logical Networks
- Azure Portal
- Orchestrated Script
- Azure CLI
When to use: Creating a single logical network, visually confirming VLAN and IP pool details, or when CLI access is unavailable.
Prerequisites: Contributor rights on the cluster resource group in the Azure Portal.
Steps (repeat for each logical network):
-
Navigate to your Azure Local cluster resource: Azure Portal → Azure Local →
iic-clus01 -
In the left navigation, select Resources → Logical networks
-
Click + Create
-
On the Basics tab, fill in:
- Subscription:
00000000-0000-0000-0000-000000000000 - Resource group:
rg-iic01-azl-eus-01 - Logical network name: e.g.
ln-iic01-management-100 - Custom location:
cl-iic01 - Virtual switch name:
ConvergedSwitch(hci)
If you're unsure of the vSwitch name, run the following on any cluster node:
Invoke-Command -ComputerName iic-01-n01 -ScriptBlock { Get-VMSwitch | Select-Object Name, SwitchType }
-
Click Next: Network configuration
-
On the Network configuration tab:
- VLAN ID: enter the VLAN number (e.g.
100) - Click + Add subnet
- Subnet name:
default - IP allocation method:
StaticorDynamic
For Static networks:
- Address prefix: e.g.
10.100.0.0/24 - Default gateway: e.g.
10.100.0.1 - DNS servers: e.g.
10.100.0.10,10.100.0.11 - Click + Add IP pool:
- Pool name: e.g.
pool-mgmt-vms - Start IP: e.g.
10.100.0.50 - End IP: e.g.
10.100.0.200
For Dynamic (DHCP) networks:
-
Address prefix, IP pools, and gateway are not required
-
Supply DNS servers under DHCP options
-
Click Add
-
Under Network Security Group, select the NSG created in Task 07:
ln-iic01-management-100→nsg-iic-managementln-iic01-production-200→nsg-iic-productionln-iic01-avd-300→nsg-iic-avd
-
Click Review + create → Create
-
Repeat for each additional logical network in
networking.logical_networks[].
Standard IIC logical networks — example portal values:
| Network name | VLAN | Subnet | Gateway | IP pool range | Alloc | NSG |
|---|---|---|---|---|---|---|
ln-iic01-management-100 | 100 | 10.100.0.0/24 | 10.100.0.1 | 10.100.0.50–200 | Static | nsg-iic-management |
ln-iic01-production-200 | 200 | 10.200.0.0/24 | 10.200.0.1 | 10.200.0.50–250 | Static | nsg-iic-production |
ln-iic01-avd-300 | 300 | (DHCP) | (DHCP) | (DHCP) | Dynamic | nsg-iic-avd |
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-06-post-deployment/task-08-logical-network-creation/powershell/New-LogicalNetwork.ps1 | Creates the Azure Local logical networks that networking.logical_networks of infrastructure.yml lists. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./New-LogicalNetwork.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-06-post-deployment/task-08-logical-network-creation/azurecli/New-LogicalNetwork.azcli.ps1 | Creates the Azure Local logical networks that networking.logical_networks of infrastructure.yml lists, with the Azure CLI only. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>. Needs the Azure CLI extension stack-hci-vm (az extension add --name stack-hci-vm); the script does not install it.
This script never reaches a node, so it cannot read the external virtual switch of the cluster the way the PowerShell script does: every enabled network must name its switch in networking.logical_networks[].vm_switch_name, or the script stops with exit code 2 before it sends anything. Read the name with Get-VMSwitch -SwitchType External on a node. A network with nsg_name needs the group of Task 07 first (the group is tied to the network when the network is created). An existing logical network is left alone: its gateway, IP pools, address space, VLAN ID and virtual switch cannot change after creation.
Run
./New-LogicalNetwork.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-LogicalNetwork.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Validation
After all logical networks are created, confirm they are in a Succeeded provisioning state and are visible on the cluster's Logical networks blade.
az stack-hci-vm network lnet list `
--subscription 00000000-0000-0000-0000-000000000000 `
--resource-group rg-iic01-azl-eus-01 `
--output table
az stack-hci-vm network lnet show `
--subscription 00000000-0000-0000-0000-000000000000 `
--resource-group rg-iic01-azl-eus-01 `
--name ln-iic01-management-100 `
--query "{Name:name, State:provisioningState, VLAN:properties.networkType}" `
--output table
Expected results:
| Name | State | VLAN |
|---|---|---|
ln-iic01-management-100 | Succeeded | 100 |
ln-iic01-production-200 | Succeeded | 200 |
ln-iic01-avd-300 | Succeeded | 300 |
If a logical network enters Failed state or stays in Updating for more than 5 minutes:
- Check the cluster Arc resource bridge (
az arcappliance show) is in a healthy state - Confirm the vSwitch name matches exactly (case-sensitive):
Get-VMSwitchon a cluster node - Verify the VLAN ID does not conflict with an existing logical network on the cluster
- Delete the failed resource and re-run:
az stack-hci-vm network lnet delete --name <lnet-name> --resource-group <rg> --yes
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
Logical network creation fails with InvalidParameter | vSwitch name mismatch (case-sensitive) or invalid VLAN ID | Verify vSwitch name exactly: Get-VMSwitch on a cluster node; ensure VLAN ID is within valid range (1-4094) |
Logical network stuck in Updating state | Arc resource bridge processing delay or unhealthy | Check bridge status: az arcappliance show; if unhealthy, restart the bridge appliance VM on the cluster |
| VLAN traffic not flowing on the logical network | Physical switch trunk port missing the VLAN | Verify switch configuration allows the VLAN on all uplink ports; check Get-VMSwitch for correct teaming config |
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation
| ← Previous | Task 07 — Configure NSGs |
| ↑ Phase Index | Phase 06 — Post-Deployment Index |
| → Next | Task 09 — Post-Deployment Verification |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |