Skip to main content

Azure Verified Modules

Azure Verified Modules are pre-built, tested, and maintained infrastructure-as-code modules provided by Microsoft.
These modules help streamline the deployment of Azure resources by offering standardized configurations that adhere to best practices.
DTX uses where possible Azure Verified Modules to ensure reliability and consistency in infrastructure deployments.
Below is a description on how to setup one of the Azure Verified Modules in DTX.
This can be used as a reference for other Azure Verified Modules as well.

Naming​

The naming of the files are based on the Categories in Azure, when browsing to the Azure portal and selecting Create a resource, the categories are listed there. Click on See more in All services, the categories are listed as well, when searching for the resource you want to deploy with CTRL-F look at the Category where it's listed.
If it's listed under Management and governance, the files should be placed under M01-management-and-governance.
When a resources is listed under multiple categories, choose the category that fits best for your deployment.

The Mxx numbers are chosen randomly to ensure that there is enough room for future additions.

New category or resource​

Create a readme.md file that includes prefixes for all resources within that category.
Look at existing readme files for examples of how to format this.

New resource​

When adding a new resource, check the existing numbers in the module folder (or readme.md) and choose a number that is not taken.
This will be the post number YY in the filenames.

In the root folder of the module (ex: M01-management-and-governance), create a folder with the name of the resource provider, e.g. microsoft.resources\resourcegroups.
Make all files and folder lower case (except the M).

Create a readme Markdown file with the name <categoryprefix XX><postnumber YY>-<resourcename>-readme.md, e.g. 0101-resourcegroup-readme.md.

An example of such a readme file is shown below, you can also look at existing readme files for more examples.

# Recovery Services Vault

Create a recovery services vault.

## Namespace

[microsoft.recoveryservices/vaults](https://learn.microsoft.com/en-us/azure/templates/microsoft.recoveryservices/vaults?pivots=deployment-language-bicep)

## Naming convention

All names are in lowercase, and start with the azure [abbreviation](/azure/modules/M99-reference/az-naming-defaults-99-abbreviations.md).

`<abbreviation>-<app or service name>-<business unit>-<environment>-<postNumber>`

## Naming limitations

| Scope          | Length | Limitations                                               |
| -------------- | ------ | --------------------------------------------------------- |
| Resource group | 2-50   | Alphanumerics and hyphens. <br />Start with letter.<br /> |

### Examples

- rsv-id-prd-westeurope-001
- rsv-corp-prd-westeurope-001
- rsv-corp-migrate-prd-westeurope-999

## Parameters

Descriptions on how to use different parameters.

### Subnet example

```bicep title='Simple subnet example'
param subnets = [
  {
    name: 'snet-online-westeurope-001'
    ipAddressRange: cidrSubnet(addressPrefixes,24,0)
    privateEndpointNetworkPolicies: 'Disabled'
    existingRouteTableId: ''
    existingNatGatewayId: ''
    additionalSecurityRules: []
    serviceEndpoints: []
    delegations: []
  }
]
```

## Versioning

Templates and modules can have different versions, below is a list of versions and changes.

### Template

Template from Azure Verified Modules (AVM) is used.

### Module

Location: azure\modules\M01-management-and-governance\microsoft.recoveryservices\M0110-recoveryservicesvault-deploy.bicep

| Version | Date       | Comments        | Publisher  |
| ------- | ---------- | --------------- | ---------- |
| 1.0.0   | 2023-03-01 | Initial release | Pietje Puk |

### References

See [Versioning](/azure/modules/M99-reference/az-naming-defaults-99-versioning.md) for more information.

Create a bicep deploy file with the name <categoryprefix XX><postnumber YY>-<resourcename>-deploy.bicep, e.g. 0101-resourcegroup-deploy.bicep.
On the chapter Starting with an Azure Verified Module below, there is an example of how to setup the bicep deploy file from scratch.

The defaults settings in the bicep deploy file should look like this:

targetScope = 'subscription'

metadata version = 'x.x.x'

@sys.description('The location of the resource group and resources')
param location string = 'westeurope'
@sys.description('The tags to be assigned to the resource group and resources')
param tags object = {}
@sys.description('The name of the resource group to be created')
param resourceGroupName string
// Additional parameters here


// Current date time don't change leave at bottom of parameters
@sys.description('Current date time in UTC, do not change!')
param currentDateTime string = utcNow()
// Needed parameters
@sys.description('The lock to be assigned to the resource group')
param resourceGroupLock object = {}
@sys.description('The role assignments to be assigned to the resource group')
param roleAssignments array = []

//
// Variables
//
var varTags = tags
var varLocation = location
var varResourceGroupName = resourceGroupName
var varRoleAssignments = roleAssignments
var varLock = resourceGroupLock
// Additional variables here


//
// Creating resource group
//
module modResourceNameResourceGroup 'br/public:avm/res/resources/resource-group:0.4.1' = {
  name: 'rg-${varResourceGroupName}-${currentDateTime}'
  params: {
    // Required parameters
    name: varResourceGroupName
    // Non-required parameters
    location: varLocation
    lock: varLock
    roleAssignments: varRoleAssignments
    tags: varTags
  }
}

//
// Resource deployment
//

//  Make sure the resource deployment depends on the resource group creation

The folder structure in the end should look like this; example for the Redis Cache module:

├───M22-databases
│   │   readme.md
│   │
│   └───microsoft.cache
│       └───redis
│               2201-cacheredis-readme.md
│               M2201-cacheredis-deploy.bicep
│               M2201-cacheredis-deploy.bicepparam

The .bicepparm file is optional, but recommended to have a default parameter file for easier deployments, it will be created in the next step(s).

Starting with an Azure Verified Module​

  • Navigate to the Azure Verified Modules repository

  • Browse or search for the desired module, under Module Indexes > Bicep > Resource Modules.

    • Note or copy the version number of the module you want to use.

  • Open the module's readme file to understand its parameters and usage by clicking on the link.

    • Browse to Usage Examples and choose the Using large parameter set example.
    • Open the via Bicep Module example to see how to use the module in Bicep.

  • Open the <categoryprefix XX><postnumber YY>-<resourcename>-deploy.bicep file you created earlier.

    • Copy the Bicep code from the via Bicep Module example into your deploy file under the // Resource deployment section.

  • Change the module path to use the Azure Verified Module registry.

    • Example: Change br/public:avm/res/resources/resource-group:0.4.1 to the version you noted earlier.
    • Add the name and scope to the module:
    name: 'fa-${varFabricName}-${currentDateTime}'
    scope: resourceGroup(varResourceGroupName)
    • Make sure all required parameters are provided with a parameter or variable, make sure not to use hardcoded values.
    • Add any optional parameters as needed, if not needed, you can leave them out.

  • Save the file.

  • Right click the deploy file in Visual Studio Code and select Create Bicep Parameter File.

    • This will create a <categoryprefix XX><postnumber YY>-<resourcename>-deploy.bicepparam file with all parameters listed and can be used for deployments.
      • The currentDateTime parameter can be deleted from the parameter file as it has a default value.

Naming of the Resource Group module​

If you need to create more then one resource group in the same deployment, make sure to give each resource group module a unique name.
To be on top of this always use the following format for the resource group module name:

module modFabricResourceGroup 'br/public:avm/res/resources/resource-group:<version>'

Where Fabric is the resource or service you are deploying, e.g. DataFactory, StorageAccount, VirtualNetwork, etc.
Using unique names for each resource group module will help avoid deployment issues due to name conflicts.

Module deployment naming always starts with mod followed by the resource or service name.

Naming of the parameters​

When creating parameters in the bicep deploy file, always use a clear name with the resource or service name in it, do not use short names.
The parameter name should be prefixed with the resource or service name to avoid conflicts and improve readability.
So if you need the name a parameter for a storage account, name it storageAccountName instead of just name.

You can decide to start the parameter with an abbreviation of par followed by the resource or service name as well, e.g. parSaName for storage account name.
For consistency it's recommended to use either the full name or the abbreviation for all parameters in the file.
Currently we are using the full name convention.

Make sure to always add a description to the parameter using the @sys.description decorator.

@sys.description('The tags to be assigned to the resource group and resources')
param tags object = {}

Naming of the variables​

When creating variables in the bicep deploy file, always use the following abbreviation var and the a clear description of the variable do not use short names.

Setting parameter / variables in the deploy file​

Here are some tips and tricks on setting parameters and variables in the deploy file.

  • If you are using a Azure Landing Zone deployment the section diagnosticSettings can be removed from the module parameters as it's already handled in the landing zone.
  • For tags, always use the variable varTags that is created at the top of the deploy file, this will ensure that all tags are consistent across all resources.
  • For location, always use the variable varLocation that is created at the top of the deploy file, this will ensure that all resources are created in the same location.
  • For role assignments, always use the variable varRoleAssignments that is created at the top of the deploy file, this will ensure that all role assignments are consistent across all resources.
  • If you are not using a section under // Non-required parameters, you can remove that section from the deploy file or create a dummy entry with a variable that is empty or has the default value. Advantage of this is that when you need to add a non-required parameter later on, you can just change the variable value to point to a parameter you add instead of adding the whole section again.
  • Don't forget the comment at the end of the deploy file to make sure the resource deployment depends on the resource group creation.
module moduleFabricResourceGroup 'br/public:avm/res/resources/resource-group:<version>' = {
  // add dependsOn to make sure resource group is created first
  dependsOn: [
    modResourceNameResourceGroup
  ]
}

Version overview​

This document has the following versions:

VersionDateOverview of changes
1.02025-12Initial version.