Azure Bicep optional module names explained

Naming every module in Azure Bicep used to be mandatory. With the release of the optional module names setting an explicit module deployment name is now optional. With Azure Bicep version 0.34.1 you can let Bicep automatically handle module deployment names for you.

In this blog, you will learn how the optional module name feature works.

What is a module name?

A module name is associated with a deployment in Azure. Every Bicep deployment requires a deployment name. When using modules, the deployment name is defined using the name property, which is mandatory. Each deployment name must be unique at runtime. If a deployment name is not unique, the deployment will fail.

To set the deployment name for a module, specify the name property as shown below:

	module modKeyVault 'br/public:avm/res/key-vault/vault:0.11.3' = {
	name: 'deploy-avm-key-vault'
	params: {
	// Key Vault parameters here
	}
	}

view raw keyvault-module-with-name.bicep hosted with ❤ by GitHub

The name is shown as the deployment name in the Azure Portal. You can find this under Resource group → Settings → Deployments, depending on your target scope:

Deployment name of deploy-avm-key-vault module

If you don’t use modules but define resources directly, you’ll need to provide the deployment name in the deployment command, for example, using Azure CLI:

az deployment group create --name <deployment name>  --template-file <bicep-template> --resource-group <resource-group-name>

If the --name parameter is not provided, the name of the template file is used instead. In the example above, this would be main. This deployment command will also create a deployment record named main, as shown in the screenshot above.

Optional module name

With the optional module names feature, you can let Bicep handle module names automatically. Module names are assigned during the compilation of the Bicep template. To enable this, simply omit the name property from your module definition:

	module modKeyVault 'br/public:avm/res/key-vault/vault:0.11.3' = {
	params: {
	// Key Vault parameters here
	}
	}

view raw keyvault-module-without-name.bicep hosted with ❤ by GitHub

What deployment name is assigned?

During compilation (bicep build), Bicep detects when no deployment name has been provided for a module. In this case, it automatically assigns a deployment name using the following format:

<symbolic-module-name>-uniqueString(<symbolic-module-name>, deployment().name)

In the case of the Bicep snippet (modKeyVault) above, it translates to:

modKeyVault-7esx7nz6thfca

This scales very well when using multiple modules because it generates a unique hash based on the symbolic module name and the deployment name.

Output

Below is a Bicep snippet of a module without the deployment name property (name) and its transpiled ARM version (generated after running bicep build). This is the template that Azure receives and deploys:

The name in the Bicep template is not set, but is added after compilation in the ARM template

In the ARM template, you can see that the name property has been added. The value in the name property is used as the deployment name for the module.

Output when using nested module

When using nested modules, the deployment name of the parent module is combined with the symbolic name of the nested module. This ensures uniqueness, even if the same symbolic name is used in multiple nested modules. An example how it’s formatted:

<symbolic-module-name>-uniqueString(<symbolic-module-name>, '<deployment-name-of-the-parent-module')

Below are two Bicep snippets. The first snippet contains a module definition using the symbolic name modKeyVault and a nested module named modModuleWithKeyVault. The second snippet shows the nested module content, which also includes a module definition named modKeyVault.

main.bicep

	module modKeyVault 'br/public:avm/res/key-vault/vault:0.11.3' = {
	params: {
	name: 'my-random-kv-name-1'
	}
	}

	module modModuleWithKeyVault 'keyvault.bicep' = {}

	output outDeploymentName string = deployment().name

view raw main.bicep hosted with ❤ by GitHub

keyvault.bicep

	module modKeyVault 'br/public:avm/res/key-vault/vault:0.11.3' = {
	params: {
	name: 'my-random-kv-name-2'
	}
	}

	output outNestedDeploymentName string = deployment().name

view raw keyvault.bicep hosted with ❤ by GitHub

To illustrate the deployment names, I’ve added two outputs to each template: outDeploymentName and outNestedDeploymentName. Each output returns the value of deployment().name. Here are the resulting values:

Below, the deployment name is equal to the name of the Bicep template. In this case, the Bicep template is named main.bicep:

Below is the deployment name of the nested module. The name assigned using the following format: modModuleWithKeyVault-uniqueString('modModuleWithKeyVault', 'main')

Below are the deployment names of the modules: modKeyVault and the nested module modKeyVault (within the nested Bicep template). These names assigned use the following values:

The modKeyVault in the main Bicep template:
modKeyVault-uniqueString('modKeyVault', 'main')
The modKeyVault in the nested template keyvault.bicep:
modKeyVault-uniqueString('modKeyVault', 'modModuleWithKeyVault-u6aurft5mzxcs')

Unique deployment names of both modKeyVault modules

Conclusion

Using optional module names in Azure Bicep simplifies the process of ensuring unique deployment names. It eliminates the need for manual naming, reduces potential errors, and makes your Bicep templates cleaner and easier to maintain.