Why does this example define subnets as separate resources?

[larryclaman]

The network portion of the example bicep uses an anti-pattern of defining subnets as separate resources from the vnet. Specifically the current bicep example is:

resource virtualNetwork 'Microsoft.Network/virtualNetworks@2021-05-01' = {
  name: virtualNetworkName
  location: location
  properties: {
    addressSpace: {
      addressPrefixes: [
        addressPrefix
      ]
    }
  }
}

resource subnet 'Microsoft.Network/virtualNetworks/subnets@2021-05-01' = {
  parent: virtualNetwork
  name: subnetName
  properties: {
    addressPrefix: subnetAddressPrefix
    privateEndpointNetworkPolicies: 'Enabled'
    privateLinkServiceNetworkPolicies: 'Enabled'
  }
}

But Microsoft's own documentation says this is a bad idea per https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/scenarios-virtual-networks#configure-subnets-by-using-the-subnets-property :

Virtual networks contain subnets, which are logical groups of IP addresses within the virtual network. There are two ways to define subnets in Bicep: by using the subnets property on the virtual network resource, and by creating a child resource with type Microsoft.Network/virtualNetworks/subnets.

Warning Avoid defining subnets as child resources. This approach can result in downtime for your resources during subsequent deployments, or failed deployments. It's best to define your subnets within the virtual network definition

Although both approaches enable you to define and create your subnets, there is an important difference. When you define subnets by using child resources, the first time your Bicep file is deployed, the virtual network is deployed. Then, after the virtual network deployment is complete, each subnet is deployed. This sequencing occurs because Azure Resource Manager deploys each individual resource separately.

When you redeploy the same Bicep file, the same deployment sequence occurs. However, the virtual network is deployed without any subnets configured on it because the subnets property is effectively empty. Then, after the virtual network is reconfigured, the subnet resources are redeployed, which re-establishes each subnet. In some situations, this behavior causes the resources within your virtual network to lose connectivity during your deployment. In other situations, Azure prevents you from modifying the virtual network and your deployment fails.

It seems pretty clear that the example should be refactored to align with Microsoft's recommended guidance.

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 6b1512d0-5f5c-8edc-f08b-0b25005d33e9
• Version Independent ID: 1da98315-50f2-617f-1904-f96443632bd0
• Content: Quickstart: Use a Bicep file to create an Ubuntu Linux VM - Azure Virtual Machines
• Content Source: articles/virtual-machines/linux/quick-create-bicep.md
• Service: virtual-machines
• GitHub Login: @carmonmills
• Microsoft Alias: carmonm

[AjayBathini-MSFT]

@larryclaman Thanks for your feedback! We will investigate and update as appropriate.

[AjayBathini-MSFT]

@larryclaman Thanks for bringing this to our attention. I'm going to assign this to the document author so they can take a look at it accordingly.

[AjayBathini-MSFT]

@carmonmills Can you please check and add your comments on this doc update request as applicable.

[cynthn]

@schaffererin is this something you can help with?

[cynthn]

reassign @johndowns

[cynthn]

re-assign @johndowns

[johndowns]

I wrote the best practice in the Bicep doc, but will have to leave it to the author of the Ubuntu quickstart to update the example to follow that best practice. It looks like this person is @schaffererin.

re-assign @schaffererin

[akashdubey-ms]

Thanks for your contribution to our documentation

We sincerely apologize for the delayed response. Unfortunately, we have been unable to review this issue in a timely manner. However, we are making overall enhancements to our content. We are closing this issue for now as there has been no activity for a while. If you feel that the problem persists, please respond to this issue with additional information. ? Please continue to provide feedback about the documentation. We appreciate your contributions to our community.

please-close

[SvenAelterman]

This PR in the Quickstarts repo will fix the issue: https://github.com/Azure/azure-quickstart-templates/pull/13765