Step-by-Step Walkthrough

This walkthrough takes you from an empty subscription to a fully deployed SMB Ready Foundation environment. Choose the Bicep or Terraform tab for your preferred IaC track.

Prerequisites

Before starting, ensure you have:

• An Azure subscription with Owner role
• Azure CLI 2.60+
• Azure Developer CLI (azd) 1.9+
• PowerShell 7.4+ (Bicep hooks) or Bash (Terraform hooks)
• The repository cloned locally

Deployment Steps

1. Set up the management group

   The smb-rf management group is created once per tenant. It hosts the 30 management group-scoped policies.

   az account management-group create --name smb-rf \
     --display-name "SMB Ready Foundation"
   az account management-group subscription add --name smb-rf \
     --subscription $(az account show --query id -o tsv)

   Tip

   If you get a permissions error, run scripts/Setup-ManagementGroupPermissions.ps1 as Global Admin first.

2. Navigate to the project

   Bicep

   cd infra/bicep/smb-ready-foundation

   Terraform

   cd infra/terraform/smb-ready-foundation

3. Create an azd environment

   azd env new my-customer-prod

4. Configure parameters

   Set the deployment scenario and required parameters:

   # Choose scenario: baseline | firewall | vpn | full
   azd env set SCENARIO baseline
   
   # Required
   azd env set OWNER "partner@contoso.com"
   
   # Defaults (override if needed)
   azd env set AZURE_LOCATION swedencentral
   azd env set ENVIRONMENT prod
   azd env set HUB_VNET_ADDRESS_SPACE "10.0.0.0/23"
   azd env set SPOKE_VNET_ADDRESS_SPACE "10.0.2.0/23"

   For vpn or full scenarios, also set:

   azd env set ON_PREMISES_ADDRESS_SPACE "192.168.0.0/16"

5. Deploy

   Bicep

   azd up

   The pre-provision hook (hooks/pre-provision.ps1) automatically:

   • Deploys the management group template (deploy-mg.bicep)
   • Creates MG-scoped policy assignments
   • Validates CIDR ranges for conflicts
   • Cleans up stale resources from prior failed runs

   Then azd provision deploys main.bicep at subscription scope.

   Terraform

   azd up

   The pre-provision hook (hooks/pre-provision.sh) automatically:

   • Bootstraps the Terraform backend (storage account + container)
   • Writes terraform.auto.tfvars.json
   • Validates CIDRs and required parameters
   • Runs terraform init -reconfigure

   Then azd provision runs terraform apply — a single root that composes MG + subscription scopes.

   Note

   Deployment times vary by scenario: baseline ~5 min, firewall ~20 min, vpn ~30 min, full ~50 min.

6. Verify the deployment

   # Check resource groups (expect 6)
   az group list \
     --query "[?starts_with(name,'rg-')].{Name:name, State:properties.provisioningState}" \
     -o table
   
   # Check MG policy count (expect 33)
   az policy assignment list \
     --scope "/providers/Microsoft.Management/managementGroups/smb-rf" \
     --query "length(@)"
   
   # Check budget
   az consumption budget list \
     --query "[?name=='budget-smb-monthly'].{Name:name, Amount:amount}" -o table

7. Review outputs

   Bicep

   The post-provision hook prints a summary including:

   • Resource group names and states
   • Hub/spoke VNet addresses
   • Key Vault URI
   • Log Analytics workspace ID
   • Scenario-specific resources (Firewall IP, VPN Gateway status)
   Terraform

   terraform output

   Key outputs: hub_vnet_id, spoke_vnet_id, key_vault_uri, log_analytics_workspace_id, firewall_private_ip (if deployed).

Scenario Quick Commands

Scenario	Command
Baseline (~$48/mo)	azd env set SCENARIO baseline && azd up
Firewall (~$336/mo)	azd env set SCENARIO firewall && azd up
VPN (~$187/mo)	azd env set SCENARIO vpn && azd env set ON_PREMISES_ADDRESS_SPACE "192.168.0.0/16" && azd up
Full (~$476/mo)	azd env set SCENARIO full && azd env set ON_PREMISES_ADDRESS_SPACE "192.168.0.0/16" && azd up

What Gets Deployed

Baseline scenario — hub-spoke topology with NAT Gateway

See Deployment Scenarios for the full resource matrix per scenario.

Troubleshooting

Problem	Solution
AnotherOperationInProgress	Wait 5–10 minutes and retry azd up
Management group permission denied	Run Setup-ManagementGroupPermissions.ps1 as Global Admin
VPN Gateway times out	VPN GW takes 25–40 min; retry usually succeeds
Firewall InternalServerError	Known race condition — serialized via dependsOn in v0.10.0+