Child Module Publishing
Child resources are resources that exist only within the scope of another resource. For example, a virtual network subnet cannot exist without a virtual network. The subnet is a child resource of the virtual network.
In the context of AVM, particularly AVM Bicep resource modules, child modules are modules deploying child resources. They are implemented within the scope of their corresponding parent resource modules. For example, the module avm/res/network/virtual-network/subnet deploys a virtual network subnet and is a child module of its parent virtual network module avm/res/network/virtual-network.
By default, child modules are not published to the public bicep registry independently from their parents. They need to be explicitly enabled for publishing to be directly referenced from the registry.
This page covers step-by-step guidelines to publish a bicep child module.
Important
The child module publishing process is currently in a pilot/preview phase. This means it may not be as smooth as the general module publishing.
The core team is currently working on additional automation, with the goal of improving efficiency in addressing child module publishing requests.
Note
Child module publishing currently only applies to resource modules.
Supporting child module publishing for other module categories, such as pattern and utility modules, is not planned at this time.
Quick guide
Use this section for a fast overview on how to publish a child module.
For a step-by-step explanation with detailed instructions, refer to the following sections.
- Check prerequisites: Existing issue in AVM, assigned telemetry ID prefix, module registered in the MAR file.
- Implement the required changes in a branch. Microsoft FTEs must use the upstream repository; external contributors may work in a fork:
- Allowed list: Add the child module path to
allowed-child-modulesin the publishing allowed list if it is not already present. - Child module template: Ensure the child’s
metadata.jsoncontains its assigned telemetry prefix alongsidemain.bicep, then add theenableTelemetryparameter andavmTelemetrydeployment. - Parent module template: In the
main.biceptemplate of the child module direct parent, add aenableReferencedModulesTelemetryvariable with a value offalse, and pass it as theenableTelemetryvalue down to the child module deployment. - Version: Add the
version.jsonfile to the child module folder and set version to0.1. - Changelog: Add a new
CHANGELOG.mdfile to the child module folder and update the changelog of all its versioned parents with a new patch version, up to the top-level parent. - Generate module artifacts: Run
avm pre-commiton the top-level parent module. It processes that module and its descendants, updating their compiled templates and READMEs. Test your changes and raise a PR.
- Allowed list: Add the child module path to
Prerequisites
Before jumping into the implementation, make sure the following prerequisites are in place:
Bicep Child Module Proposal issue
Ensure there is an AVM issue open already, proposing the child module to be published. If not, please create one using the Bicep Child Module Proposal issue template.
Note
Please understand the difference between publishing an existing child module and extending a parent module with a not yet implemented child module functionality.
The Bicep Child Module Proposal issue primarily intends to cover the former, i.e. to publish a child module already existing in the BRM (Bicep Registry Modules) repository source code. However, the same issue allows also to request the development of the child module functionality, although the best way to address new functionality is to raise a feature request via the the AVM Module issue.
Telemetry ID prefix assigned
Follow the below steps to check the child module telemetry ID prefix.
Note
If the Bicep Child Module Proposal issue was just created, please allow a few days for the telemetry ID prefix to be assigned before reaching out.
Check telemetryIdPrefix in the child’s own metadata.json and keep it consistent with the child module source. Record only the assigned identifier through metadata review. Ownership is inherited from the root.
You can also look up the assigned prefix in the published index:
- Check the Bicep Resource Modules index, or the underlying module catalog JSON.
- Search for the child module name in the
ModuleNamefield. - Verify if the corresponding value exists in the
TelemetryIdPrefixfield. Note down the value as you will need it in the implementation phase. - If not found, please reach out to the core team, mentioning the
@Azure/azure-verified-modules-tooling-contributorsvia the Bicep Child Module Proposal issue.
If the identifier is missing or conflicts with the index, ask the core team to resolve it. Do not invent an identifier or copy the parent’s prefix.
Module registered in the MAR-file
Ensure that the child module is registered in the MAR file.
If not, please reach out to the core team, mentioning the @Azure/azure-verified-modules-tooling-contributors via the Bicep Child Module Proposal issue.
Metadata approval does not replace MAR registration or approval to publish the child module.
Note
The MAR-file can only be accessed by Microsoft FTEs. If you are missing access, please reach out to the parent module owner for help.
Implementation
The quickest way to get the child module published is to enable it yourself, contributing via a pull request to the BRM repository.
Note
Publishing a child module does not change the folder hierarchy of the parent and child modules. The child module remains in its existing location within the parent module’s folder structure. No files or folders need to be moved or reorganized.
Please follow the steps below:
Add the child module path to the
allowed-child-modulesarray in the publishing allowed list, keeping alphabetical order. Validation requires a child module with aversion.jsonfile to be listed.Update the child module
main.biceptemplate to support telemetry, as per SFR4, SFR3 and BCPFR4- Add the
enableTelemetryparameter with a default value oftrue. Place it as the lastparamdeclaration, immediately before the firstvardeclaration.@description('Optional. Enable/Disable usage telemetry for module.') param enableTelemetry bool = true - Add the
avmTelemetrydeployment, referencing the template below. Ensure the child’smetadata.jsonexists alongsidemain.bicepbefore compiling and contains its assignedtelemetryIdPrefix. Load only that property instead of hardcoding the prefix.var telemetryIdPrefix = loadJsonContent('metadata.json', 'telemetryIdPrefix') #disable-next-line no-deployments-resources resource avmTelemetry 'Microsoft.Resources/deployments@2025-04-01' = if (enableTelemetry) { name: '${telemetryIdPrefix}.${replace('-..--..-', '.', '-')}.${substring(uniqueString(deployment().name), 0, 4)}' properties: { mode: 'Incremental' template: { '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#' contentVersion: '1.0.0.0' resources: [] outputs: { telemetry: { type: 'String' value: 'For more information, see https://aka.ms/avm/TelemetryInfo' } } } } }
- Add the
Update the
main.biceptemplate of the child module direct parent, as per BCPFR7.- Add the
enableReferencedModulesTelemetryvariable with a default value offalse. Place it as the lastvardeclaration, immediately before the firstresourcedeclaration.var enableReferencedModulesTelemetry = false - Pass the
enableReferencedModulesTelemetryvariable as theenableTelemetryvalue down to the child module deployment.enableTelemetry: enableReferencedModulesTelemetry
- Add the
Add the
version.jsonfile to the child module folder and set version to0.1.{ "$schema": "https://aka.ms/bicep-registry-module-version-file-schema#", "version": "0.1" }Determine all affected module paths. This includes the child module(s) and all parent modules up to the top-level module.
Examples:
Child module to publish:
avm/res/virtual-network/subnetAffected modules:
avm/res/virtual-network/subnetavm/res/virtual-network
Child module to publish:
avm/res/storage/storage-account/blob-service/container/immutability-policyAffected modules:
avm/res/storage/storage-account/blob-service/container/immutability-policyavm/res/storage/storage-account/blob-service/containeravm/res/storage/storage-account/blob-serviceavm/res/storage/storage-account
Update Changelogs
- Add a new
CHANGELOG.mdfile to the child module folder, with the following sample content. Make sure to replace the<avm/res/path/to/child-module>placeholder with the name of the child module.# Changelog The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/<avm/res/path/to/child-module>/CHANGELOG.md). ## 0.1.0 ### Changes - Initial version ### Breaking Changes - None - Check the list of affected modules. Update the changelog of all the affected modules with a version.json. Add a new patch version for each. Refer below for an example content section:
## <CurrentMajor>.<CurrentMinor>.<CurrentPatch+1> ### Changes - Publishing child module `<avm/res/path/to/child-module>` ### Breaking Changes - None
- Add a new
Run
avm pre-commiton the top-level parent module to process the entire module family:$topLevelModulePath = 'avm/res/storage/storage-account' avm pre-commit -Ecosystem bicep -Path $topLevelModulePathRaise a PR and verify the shared checks. An authorized maintainer must apply an E2E label to run deployment tests. For an external fork PR, an authorized FTE must perform the release-branch handoff.
Note
Existing tests for the parent module do not need to be updated when publishing a child module. The changes required for child module publishing (telemetry support, version file, and changelogs) do not affect the module’s test cases.
Tip
Reference This pull request as an example for proposing a child module for publishing.