Azure Verified Modules

Important

We are aware of an issue impacting the Terraform AVM module avm-res-network-virtualnetwork that started at approximately midnight (UTC) on Thursday 3 July 2025.

We are pleased to confirm that the issue has been resolved and the module is now available again 👍

For more information and any assistance required please refer to this GitHub issue

Introduction

Value Proposition

Azure Verified Modules (AVM) is an initiative to consolidate and set the standards for what a good Infrastructure-as-Code module looks like.

Modules will then align to these standards, across languages (Bicep, Terraform etc.) and will then be classified as AVMs and available from their respective language specific registries.

AVM is a common code base, a toolkit for our Customers, our Partners, and Microsoft. It’s an official, Microsoft driven initiative, with a devolved ownership approach to develop modules, leveraging internal & external communities.

Azure Verified Modules enable and accelerate consistent solution development and delivery of cloud-native or migrated applications and their supporting infrastructure by codifying Microsoft guidance (WAF), with best practice configurations.

Modules

Azure Verified Modules provides two types of modules: Resource and Pattern modules.

AVM modules are used to deploy Azure resources and their extensions, as well as reusable architectural patterns consistently.

Modules are composable building blocks that encapsulate groups of resources dedicated to one task.

Flexible, generalized, multi-purpose
Integrates child resources
Integrates extension resources

AVM improves code quality and provides a unified customer experience.

Important

AVM is owned, developed & supported by Microsoft, you may raise a GitHub issue on this repository or the module’s repository directly to get support or log feature requests.

You can also log a support ticket and if the issue is not related to the Azure platform, you will be redirected to submit a GitHub issue for the module owner(s) or the AVM team.

See Module Support for more information.

Next Steps

Review Overview
Review the Module Classification Definitions
Review the Specifications
Review the FAQ
Learn how to contribute to AVM

Overview

Summary

This section provides an overview of the Azure Verified Modules (AVM) program.

Introduction

Introduction

What is Azure Verified Modules?

Azure Verified Modules (AVM), as “One Microsoft”, we want to provide and define the single definition of what a good IaC module is;

How they should be constructed and built
- Enforcing consistency and testing where possible
How they are to be consumed
What they deliver for consumers in terms of resources deployed and configured
And where appropriate aligned across IaC languages (e.g. Bicep, Terraform, etc.).

Mission Statement

Our mission is to deliver a comprehensive Azure Verified Modules library in multiple IaC languages, following the principles of the well-architected framework, serving as the trusted Microsoft source of truth. Supported by Microsoft, AVM will accelerate deployment time for Azure resources and architectural patterns, empowering every person and organization on the planet on their IaC journey.

Definition of “Verified” Summary

The modules are supported by Microsoft, across it’s many internal organizations, as described in Module Support
Modules are aligned to clear specifications that enforces consistency between all AVM modules. See the ‘Specifications & Definitions’ section in the menu
Modules will continue to stay up-to-date with product/service roadmaps owned by the module owners and contributors
Modules will align to WAF high priority recommendations. See ‘What does AVM mean by “WAF Aligned”?’
Modules will provide clear documentation alongside examples to promote self-service consumption
Modules will be tested to ensure they comply with the specifications for AVM and their examples deploy as intended

Why Azure Verified Modules?

This effort to create Azure Verified Modules, with a strategy and definition, is required based on the sheer number of existing attempts from all areas across Microsoft to try and address this same area for our customers and partners. Across Microsoft there are many initiatives, projects and repositories that host and provide IaC modules in several languages, for example Bicep and Terraform. Each of these come with differing code styling and standards, consumption methods and approaches, testing frameworks, target personas, contribution guidelines, module definitions and most importantly support statements from their owners and maintainers.

However, none of these existing attempts have ever made it all the way through to becoming a brand and the go to place for IaC modules from Microsoft that consumers can trust (mainly around longevity and support), build upon and contribute back to.

Performing this effort now to create a shared single aligned strategy and definition for IaC modules from Microsoft, as One Microsoft, will allow us to accelerate existing and future projects, such as Application Landing Zone Accelerators (LZAs), as well as providing the building blocks via a library of modules, in the language of the consumers choice, that is consistent, trusted and supported by Microsoft. This all leads to consumers being able to accelerate faster, no matter what stage of their IaC journey they are on.

We also know, from our customers, that well defined support statements from Microsoft are required for initiatives like this to succeed at scale, especially in larger enterprise customers. We have seen over the past FY that this topic alone is important and is one that has led to confusion and frustration to customers who are consuming modules developed by individuals that in the end are not “officially” Microsoft supported and this unfortunately normally occurs at a critical point in time for the project being worked on, which amplifies frustrations.

How will we create, support and enforce Azure Verified Modules?

Azure Verified Modules will achieve this, and its mission statement, by implementing and enforcing the following; driven by the AVM Core Team:

Publishing AVM modules to their respective public registries for consumption
- For Bicep this will be the Bicep Public Module Registry
- For Terraform this will be the HashiCorp Terraform Registry
Creating, publishing and maintaining the Azure Verified Modules specifications (this site)
- Including IaC language specific specifications (today Bicep and Terraform)
Creating easy to follow AVM module contribution and publishing guidance for each IaC language (today Bicep and Terraform)
Enforcing tests for each AVM module is compliant with the AVM specifications, where possible, via Unit and Integration tests
Enforcing End-to-End Deployment tests of each AVM module
Providing, and backing, a long-term support statement, regardless of the AVM module’s ownership status
- Backed by the AVM Core Team, Microsoft CSS and Azure PGs

Module Indexes

Summary

The following table shows the number of all available, orphaned and planned AVM Bicep and Terraform Modules.

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Bicep	Resource	164	15	179
	Pattern	36	33	69
	Utility	1	1	2
Terraform	Resource	92	49	141
	Pattern	23	17	40
	Utility	4	1	5

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Want to contribute to AVM modules?

#	Labels	Link and description
1.	Type: New Module Proposal 💡 Needs: Module Owner 📣	To become the owner of a new module, see all new modules looking for owners or check out the “Looking for owners” swimlane here.
2.	Status: Module Orphaned 🟡	To become the owner of an orphaned module, see all orphaned modules or check out the “Orphaned” swimlane here.
3.	Needs: Module Contributor 📣	To become a co-owner or contribute to a module, see all modules looking for contributors.

For more details on “What are the different ways to contribute to AVM?”, see here.

Bicep Modules

Summary

The following table shows the number of all available, orphaned and planned Bicep Modules.

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Bicep	Resource	164	15	179
	Pattern	36	33	69
	Utility	1	1	2

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Want to contribute to AVM Bicep modules?

#	Labels	Link and description
1.	Type: New Module Proposal 💡 Needs: Module Owner 📣 Language: Bicep 💪	To become the owner of a new Bicep module, see all new Bicep modules looking for owners or check out the “Looking for owners” swimlane here.
2.	Status: Module Orphaned 🟡 Language: Bicep 💪	To become the owner of an orphaned Bicep module, see all orphaned Bicep modules or check out the “Orphaned” swimlane here.
3.	Needs: Module Contributor 📣 Language: Bicep 💪	To become a co-owner or contribute to a Bicep module, see all Bicep modules looking for contributors.

For more details on “What are the different ways to contribute to AVM?”, see here.

Status Badges

This section gives you an overview of the latest workflow status of each AVM module in the Public Bicep Registry repository.

Note

While some pipelines can momentarily show as red, a new module version cannot be published without a successful test run. A failing test may indicate a recent change to the platform that is causing a break in the module or any intermittent errors, such as a periodic test deployment attempting to create a resource with a name already taken in another Azure region.

#	Module	Status
1	ptn/aca-lza hosting-environment
2	ptn/ai-ml ai-foundry
3	ptn/ai-platform baseline
4	ptn/alz empty
5	ptn/app-service-lza hosting-environment
6	ptn/app container-job-toolkit
7	ptn/authorization pim-role-assignment
8	ptn/authorization policy-assignment
9	ptn/authorization policy-exemption
10	ptn/authorization resource-role-assignment
11	ptn/authorization role-assignment
12	ptn/authorization role-definition
13	ptn/azd acr-container-app
14	ptn/azd aks
15	ptn/azd aks-automatic-cluster
16	ptn/azd apim-api
17	ptn/azd container-app-upsert
18	ptn/azd container-apps-stack
19	ptn/azd insights-dashboard
20	ptn/azd ml-ai-environment
21	ptn/azd ml-hub-dependencies
22	ptn/azd ml-project
23	ptn/azd monitoring
24	ptn/data private-analytical-workspace
25	ptn/deployment-script import-image-to-acr
26	ptn/dev-ops cicd-agents-and-runners
27	ptn/finops-toolkit finops-hub
28	ptn/lz sub-vending
29	ptn/mgmt-groups subscription-placement
30	ptn/network hub-networking
31	ptn/network private-link-private-dns-zones
32	ptn/policy-insights remediation
33	ptn/sa content-processing
34	ptn/sa conversation-knowledge-mining
35	ptn/sa modernize-your-code
36	ptn/sa multi-agent-custom-automation-engine
37	ptn/security security-center
38	ptn/subscription service-health-alerts
39	ptn/virtual-machine-images azure-image-builder
40	res/aad domain-service
41	res/alerts-management action-rule
42	res/analysis-services server
43	res/api-management service
44	res/app-configuration configuration-store
45	res/app container-app
46	res/app job
47	res/app managed-environment
48	res/app session-pool
49	res/authorization role-assignment
50	res/automation automation-account
51	res/azure-stack-hci cluster
52	res/azure-stack-hci logical-network
53	res/azure-stack-hci marketplace-gallery-image
54	res/azure-stack-hci network-interface
55	res/azure-stack-hci virtual-hard-disk
56	res/batch batch-account
57	res/cache redis
58	res/cache redis-enterprise
59	res/cdn profile
60	res/cognitive-services account
61	res/communication communication-service
62	res/communication email-service
63	res/compute availability-set
64	res/compute disk
65	res/compute disk-encryption-set
66	res/compute gallery
67	res/compute image
68	res/compute proximity-placement-group
69	res/compute ssh-public-key
70	res/compute virtual-machine
71	res/compute virtual-machine-scale-set
72	res/consumption budget
73	res/container-instance container-group
74	res/container-registry registry
75	res/container-service managed-cluster
76	res/data-factory factory
77	res/data-protection backup-vault
78	res/databricks access-connector
79	res/databricks workspace
80	res/db-for-my-sql flexible-server
81	res/db-for-postgre-sql flexible-server
82	res/desktop-virtualization application-group
83	res/desktop-virtualization host-pool
84	res/desktop-virtualization scaling-plan
85	res/desktop-virtualization workspace
86	res/dev-center devcenter
87	res/dev-center network-connection
88	res/dev-center project
89	res/dev-ops-infrastructure pool
90	res/dev-test-lab lab
91	res/digital-twins digital-twins-instance
92	res/document-db database-account
93	res/document-db mongo-cluster
94	res/elastic-san elastic-san
95	res/event-grid domain
96	res/event-grid namespace
97	res/event-grid system-topic
98	res/event-grid topic
99	res/event-hub namespace
100	res/fabric capacity
101	res/health-bot health-bot
102	res/healthcare-apis workspace
103	res/hybrid-compute gateway
104	res/hybrid-compute license
105	res/hybrid-compute machine
106	res/hybrid-container-service provisioned-cluster-instance
107	res/insights action-group
108	res/insights activity-log-alert
109	res/insights component
110	res/insights data-collection-endpoint
111	res/insights data-collection-rule
112	res/insights diagnostic-setting
113	res/insights metric-alert
114	res/insights private-link-scope
115	res/insights scheduled-query-rule
116	res/insights webtest
117	res/key-vault vault
118	res/kubernetes-configuration extension
119	res/kubernetes-configuration flux-configuration
120	res/kubernetes connected-cluster
121	res/kusto cluster
122	res/load-test-service load-test
123	res/logic workflow
124	res/machine-learning-services registry
125	res/machine-learning-services workspace
126	res/maintenance configuration-assignment
127	res/maintenance maintenance-configuration
128	res/managed-identity user-assigned-identity
129	res/managed-services registration-definition
130	res/management management-group
131	res/maps account
132	res/net-app net-app-account
133	res/network application-gateway
134	res/network application-gateway-web-application-firewall-policy
135	res/network application-security-group
136	res/network azure-firewall
137	res/network bastion-host
138	res/network connection
139	res/network ddos-protection-plan
140	res/network dns-forwarding-ruleset
141	res/network dns-resolver
142	res/network dns-zone
143	res/network express-route-circuit
144	res/network express-route-gateway
145	res/network express-route-port
146	res/network firewall-policy
147	res/network front-door
148	res/network front-door-web-application-firewall-policy
149	res/network ip-group
150	res/network load-balancer
151	res/network local-network-gateway
152	res/network nat-gateway
153	res/network network-interface
154	res/network network-manager
155	res/network network-security-group
156	res/network network-security-perimeter
157	res/network network-watcher
158	res/network p2s-vpn-gateway
159	res/network private-dns-zone
160	res/network private-endpoint
161	res/network private-link-service
162	res/network public-ip-address
163	res/network public-ip-prefix
164	res/network route-table
165	res/network service-endpoint-policy
166	res/network trafficmanagerprofile
167	res/network virtual-hub
168	res/network virtual-network
169	res/network virtual-network-gateway
170	res/network virtual-wan
171	res/network vpn-gateway
172	res/network vpn-server-configuration
173	res/network vpn-site
174	res/operational-insights workspace
175	res/operations-management solution
176	res/portal dashboard
177	res/power-bi-dedicated capacity
178	res/purview account
179	res/recovery-services vault
180	res/relay namespace
181	res/resource-graph query
182	res/resources deployment-script
183	res/resources resource-group
184	res/search search-service
185	res/security-insights data-connector
186	res/security-insights setting
187	res/service-bus namespace
188	res/service-fabric cluster
189	res/service-networking traffic-controller
190	res/signal-r-service signal-r
191	res/signal-r-service web-pub-sub
192	res/sql instance-pool
193	res/sql managed-instance
194	res/sql server
195	res/storage storage-account
196	res/synapse private-link-hub
197	res/synapse workspace
198	res/virtual-machine-images image-template
199	res/web connection
200	res/web hosting-environment
201	res/web serverfarm
202	res/web site
203	res/web static-site
204	utl/types avm-common-types

Bicep Resource Modules

Module catalog

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Bicep	Resource	164	15	179

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Info

This page contains various views of the module index (catalog) for Bicep Resource Modules. To see these views, click on the expandable sections with the “➕” sign below.

To see the full, unfiltered, unformatted module index on GitHub, click here.
To download the source CSV file, click here.

Note

Modules listed below that aren’t shown with the status of Module Available 🟢, are currently in development and are not yet available for use. For proposed modules, see the Proposed modules section below.

Published modules - 🟢 & 🟡

➕ Published Modules - Module names, status and owners

No.	Module Name	Display Name	Owner(s)
01	avm/res/aad/domain-service	Azure Active Directory Domain Service AAD, Entra ID, Microsoft Entra Domain Services, AAD DS, Azure AD DS	ReneHezser Rene Hezser CRYP70N1X Paul Chirila
02	avm/res/alerts-management/action-rule	Action Rules	judyer28 Justin Dyer
03	avm/res/analysis-services/server	Analysis Services Server
04	avm/res/api-management/service api api-version-set api/diagnostics api/policy authorization-server backend cache diagnostics identity-provider logger named-value policy portalsetting private-endpoint-connection product product/api product/group subscription workspace	API Management Service	tony-box Tony Box
05	avm/res/app-configuration/configuration-store	App Configuration Store	Jfolberth John Folberth
06	avm/res/app/container-app	Container App	oZakari Zach Trocinski
07	avm/res/app/job	App Job	ReneHezser Rene Hezser
08	avm/res/app/managed-environment	App Managed Environment	hundredacres Matt Schmitt
09	avm/res/app/session-pool	App Session Pool	jlinn-microsoft Joe Linn
10	avm/res/authorization/role-assignment mg-scope rg-scope sub-scope	Authorization - Role Assignment	arnoldna Nate Arnold
11	avm/res/automation/automation-account	Automation Account	gpacetti Giuseppe Pacetti
12	avm/res/azure-stack-hci/cluster	Azure Stack HCI Cluster	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
13	avm/res/azure-stack-hci/logical-network	Azure Stack HCI Logical Network	xhy8759 Hangyu Xu duzitong Zidong Lu
14	avm/res/azure-stack-hci/marketplace-gallery-image	Azure Stack HCI Marketplace Gallery Image	xhy8759 Hangyu Xu duzitong Zidong Lu
15	avm/res/azure-stack-hci/network-interface	Azure Stack HCI Network Interface	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
16	avm/res/azure-stack-hci/virtual-hard-disk	Azure Stack HCI Hard Disk	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
17	avm/res/batch/batch-account	Batch Account	didayal-msft Divyadeep Dayal
18	avm/res/cache/redis	Redis Cache	hundredacres Matt Schmitt
19	avm/res/cache/redis-enterprise	Redis Enterprise Cache	JeffreyCA Jeffrey Chen
20	avm/res/cdn/profile	CDN Profile	gbeaud Guillaume Beaud
21	avm/res/cognitive-services/account	Azure AI Services (Cognitive Services)	ilhaan Ilhaan Rasheed jceval Javier Cevallos
22	avm/res/communication/communication-service	Communication Service	donk-msft Don Koning
23	avm/res/communication/email-service	Email Communication Service	donk-msft Don Koning
24	avm/res/compute/availability-set	Availability Set AS	ahmadabdalla Ahmad Abdalla
25	avm/res/compute/disk	Compute Disk	segraef Sebastian Graef
26	avm/res/compute/disk-encryption-set	Disk Encryption Set	segraef Sebastian Graef
27	avm/res/compute/gallery	Azure Compute Gallery	ReneHezser Rene Hezser
28	avm/res/compute/image	Image	tony-box Tony Box
29	avm/res/compute/proximity-placement-group	Proximity Placement Group	jeetgarg Jeet Garg
30	avm/res/compute/ssh-public-key	Public SSH Key	ChrisSidebotham Chris Sidebotham
31	avm/res/compute/virtual-machine	Virtual Machine VM	josunefon Jordi Sune Fontanals
32	avm/res/compute/virtual-machine-scale-set	Virtual Machine Scale Set VMSS	josunefon Jordi Sune Fontanals
33	avm/res/consumption/budget	Consumption Budget	segraef Sebastian Graef
34	avm/res/container-instance/container-group	Container Instance ACI	JPEasier Julian Peißker
35	avm/res/container-registry/registry	Azure Container Registry (ACR)	JPEasier Julian Peißker
36	avm/res/container-service/managed-cluster	Azure Kubernetes Service (AKS) Managed Cluster	JPEasier Julian Peißker ilhaan Ilhaan Rasheed
37	avm/res/data-factory/factory	Data Factory	clintgrove Clint Grove
38	avm/res/data-protection/backup-vault	Data Protection Backup Vault	hundredacres Matt Schmitt
39	avm/res/databricks/access-connector	Azure Databricks Access Connector	clintgrove Clint Grove
40	avm/res/databricks/workspace	Azure Databricks Workspace	clintgrove Clint Grove
41	avm/res/db-for-my-sql/flexible-server	DB for MySQL Flexible Server	hundredacres Matt Schmitt
42	avm/res/db-for-postgre-sql/flexible-server	DB for Postgre SQL Flexible Server	arnoldna Nate Arnold
43	avm/res/desktop-virtualization/application-group	Azure Virtual Desktop (AVD) Application Group
44	avm/res/desktop-virtualization/host-pool	Azure Virtual Desktop (AVD) Host Pool
45	avm/res/desktop-virtualization/scaling-plan	Azure Virtual Desktop (AVD) Scaling Plan
46	avm/res/desktop-virtualization/workspace	Azure Virtual Desktop (AVD) Workspace
47	avm/res/dev-center/devcenter	Dev Center	ahmadabdalla Ahmad Abdalla
48	avm/res/dev-center/network-connection	Dev Center Network Connection	ahmadabdalla Ahmad Abdalla
49	avm/res/dev-center/project	Dev Center Project	ahmadabdalla Ahmad Abdalla
50	avm/res/dev-ops-infrastructure/pool	DevOps Infrastructure Pool	elizatargithub7 Eliza Tarasila surajguptha Suraj Guptha
51	avm/res/dev-test-lab/lab	DevTest Lab	ahmadabdalla Ahmad Abdalla
52	avm/res/digital-twins/digital-twins-instance	Digital Twins Instance	ryanmstephens Ryan Stephens
53	avm/res/document-db/database-account sql-role	Cosmos DB Database Account	seesharprun Sidney Andrews
54	avm/res/document-db/mongo-cluster	Cosmos DB for MongoDB (vCore)	sinedied Yohan Lasorsa
55	avm/res/elastic-san/elastic-san	Elastic SAN SAN, ESAN, Elastic SAN, Azure Elastic Storage Area Network, iSCSI, internet Small Computer Systems Interface	jbinko Jiri Binko
56	avm/res/event-grid/domain	Event Grid Domain	fabmas Fabio Masciotra
57	avm/res/event-grid/namespace	Event Grid Namespace	fabmas Fabio Masciotra
58	avm/res/event-grid/system-topic	Event Grid System Topic	fabmas Fabio Masciotra
59	avm/res/event-grid/topic	Event Grid Topic	fabmas Fabio Masciotra
60	avm/res/event-hub/namespace event-hub	Event Hub Namespace
61	avm/res/fabric/capacity	Fabric	hundredacres Matt Schmitt
62	avm/res/health-bot/health-bot	Azure Health Bot
63	avm/res/healthcare-apis/workspace	Healthcare API Workspace
64	avm/res/hybrid-compute/gateway	Hybrid Compute Gateway	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
65	avm/res/hybrid-compute/license	Hybrid Compute License	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
66	avm/res/hybrid-compute/machine	Hybrid Compute Machine	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
67	avm/res/hybrid-container-service/provisioned-cluster-instance	Hybrid Container Service - Provisioned Cluster Instance	xhy8759 Hangyu Xu duzitong Zidong Lu
68	avm/res/insights/action-group	Action Group	rahalan Rainer Halanek
69	avm/res/insights/activity-log-alert	Activity Log Alert	donk-msft Don Koning
70	avm/res/insights/component	Application Insight	krbar Kris Baranek
71	avm/res/insights/data-collection-endpoint	Data Collection Endpoint	krbar Kris Baranek
72	avm/res/insights/data-collection-rule	Data Collection Rule DCR	krbar Kris Baranek
73	avm/res/insights/diagnostic-setting	Diagnostic Setting	krbar Kris Baranek
74	avm/res/insights/metric-alert	Metric Alert	kijunkang Ki Jun Kang
75	avm/res/insights/private-link-scope	Azure Monitor Private Link Scope	ahmadabdalla Ahmad Abdalla
76	avm/res/insights/scheduled-query-rule	Scheduled Query Rule
77	avm/res/insights/webtest	Web Test	Jfolberth John Folberth
78	avm/res/key-vault/vault access-policy key secret	Key Vault KV	fblix Felix Borst
79	avm/res/kubernetes-configuration/extension	Kubernetes Configuration Extension	JPEasier Julian Peißker
80	avm/res/kubernetes-configuration/flux-configuration	Kubernetes Configuration Flux Configuration	JPEasier Julian Peißker
81	avm/res/kubernetes/connected-cluster	Kubernetes Connected Cluster	xhy8759 Hangyu Xu duzitong Zidong Lu
82	avm/res/kusto/cluster	Azure Data Explorer (Kusto) cluster	oZakari Zach Trocinski
83	avm/res/load-test-service/load-test	Load Testing Service	sebassem Seif Bassem
84	avm/res/logic/workflow	Logic Apps Workflow	lsnoddy Luke Snoddy
85	avm/res/machine-learning-services/registry	Machine Learning Services Registry	josunefon Jordi Sune Fontanals
86	avm/res/machine-learning-services/workspace	Machine Learning Services Workspace ML Workspace	cecheta Chinedum Echeta ross-p-smith Ross Smith
87	avm/res/maintenance/configuration-assignment	Maintenance Configuration Assignment	eriqua Erika Gressi
88	avm/res/maintenance/maintenance-configuration	Maintenance Configuration	arievanderwende Arie van der Wende
89	avm/res/managed-identity/user-assigned-identity	User Assigned Identity MSI	gpacetti Giuseppe Pacetti
90	avm/res/managed-services/registration-definition	Registration Definition (Lighthouse)
91	avm/res/management/management-group	Management Group MG	fblix Felix Borst
92	avm/res/maps/account	Azure Maps Account	jhueppauff Julian Huppauff
93	avm/res/net-app/net-app-account	Azure NetApp File	fbinotto Felipe Binotto
94	avm/res/network/application-gateway	Application Gateway App GW	ilhaan Ilhaan Rasheed
95	avm/res/network/application-gateway-web-application-firewall-policy	Application Gateway Web Application Firewall (WAF) Policy	ilhaan Ilhaan Rasheed
96	avm/res/network/application-security-group	Application Security Group (ASG) ASG	segraef Sebastian Graef
97	avm/res/network/azure-firewall	Azure Firewall Azure FW	hundredacres Matt Schmitt
98	avm/res/network/bastion-host	Bastion Host	krbar Kris Baranek
99	avm/res/network/connection	Virtual Network Gateway Connection	fabmas Fabio Masciotra
100	avm/res/network/ddos-protection-plan	DDoS Protection Plan	segraef Sebastian Graef
101	avm/res/network/dns-forwarding-ruleset	DNS Forwarding Ruleset	ChrisSidebotham Chris Sidebotham
102	avm/res/network/dns-resolver	DNS Resolver	ChrisSidebotham Chris Sidebotham
103	avm/res/network/dns-zone	Public DNS Zone	ChrisSidebotham Chris Sidebotham
104	avm/res/network/express-route-circuit	ExpressRoute Circuit ER Circuit	arnoldna Nate Arnold
105	avm/res/network/express-route-gateway	Express Route Gateway ER GW	arnoldna Nate Arnold
106	avm/res/network/express-route-port	ExpressRoute Port ER Port	arnoldna Nate Arnold
107	avm/res/network/firewall-policy	Firewall Policy	PaulJohnston88 Paul Johnston
108	avm/res/network/front-door	Azure Front Door	hundredacres Matt Schmitt
109	avm/res/network/front-door-web-application-firewall-policy	Front Door Web Application Firewall (WAF) Policy	PaulJohnston88 Paul Johnston
110	avm/res/network/ip-group	IP Group	ahmadabdalla Ahmad Abdalla
111	avm/res/network/load-balancer	Load Balancer LB, NLB	arnoldna Nate Arnold
112	avm/res/network/local-network-gateway	Local Network Gateway	fabmas Fabio Masciotra
113	avm/res/network/nat-gateway	NAT Gateway NAT GW	fabmas Fabio Masciotra
114	avm/res/network/network-interface	Network Interface NIC	rahalan Rainer Halanek
115	avm/res/network/network-manager	Network Manager	ahmadabdalla Ahmad Abdalla
116	avm/res/network/network-security-group	Network Security Group NSG	ahmadabdalla Ahmad Abdalla
117	avm/res/network/network-security-perimeter	Network Security Perimeter	peterbud Peter Budai
118	avm/res/network/network-watcher	Network Watcher	segraef Sebastian Graef
119	avm/res/network/p2s-vpn-gateway	P2S VPN Gateway	ericscheffler Eric Scheffler
120	avm/res/network/private-dns-zone a aaaa cname mx ptr soa srv txt virtual-network-link	Private DNS Zone	ChrisSidebotham Chris Sidebotham
121	avm/res/network/private-endpoint	Private Endpoint	segraef Sebastian Graef
122	avm/res/network/private-link-service	Private Link Service	ahmadabdalla Ahmad Abdalla
123	avm/res/network/public-ip-address	Public IP Address PIP	ChrisSidebotham Chris Sidebotham krbar Kris Baranek
124	avm/res/network/public-ip-prefix	Public IP Prefix PIP Prefix	krbar Kris Baranek
125	avm/res/network/route-table	Route Table UDR	segraef Sebastian Graef
126	avm/res/network/service-endpoint-policy	Service Endpoint Policy	jeetgarg Jeet Garg
127	avm/res/network/trafficmanagerprofile	Traffic Manager Profile	lsnoddy Luke Snoddy
128	avm/res/network/virtual-hub route-map	Virtual Hub	arnoldna Nate Arnold
129	avm/res/network/virtual-network subnet	Virtual Network VNET	mjrich19 MJ Richardson
130	avm/res/network/virtual-network-gateway	Virtual Network Gateway VNET GW	fabmas Fabio Masciotra
131	avm/res/network/virtual-wan	Virtual WAN vWAN	arnoldna Nate Arnold
132	avm/res/network/vpn-gateway	VPN Gateway VPN GW	fabmas Fabio Masciotra
133	avm/res/network/vpn-server-configuration	VPN Server Configuration	ericscheffler Eric Scheffler
134	avm/res/network/vpn-site	VPN Site	fabmas Fabio Masciotra
135	avm/res/operational-insights/workspace	Log Analytics Workspace	krbar Kris Baranek
136	avm/res/operations-management/solution	Operations Management Solution	krbar Kris Baranek
137	avm/res/portal/dashboard	Portal Dashboard	krbar Kris Baranek
138	avm/res/power-bi-dedicated/capacity	Power BI Dedicated Capacity	ChrisSidebotham Chris Sidebotham
139	avm/res/purview/account	Purview Account	hundredacres Matt Schmitt
140	avm/res/recovery-services/vault	Recovery Services Vault	alexanderojala Alexander Ojala
141	avm/res/relay/namespace	Relay Namespace
142	avm/res/resource-graph/query	Resource Graph Query	sebassem Seif Bassem
143	avm/res/resources/deployment-script	Deployment Script	sebassem Seif Bassem
144	avm/res/resources/resource-group	Resource Group RG	segraef Sebastian Graef
145	avm/res/search/search-service	Search Service	krbar Kris Baranek
146	avm/res/security-insights/data-connector	Security Insights - Data Connector	hundredacres Matt Schmitt
147	avm/res/security-insights/setting	Security Insights - Setting	hundredacres Matt Schmitt
148	avm/res/service-bus/namespace	Service Bus Namespace	ChrisSidebotham Chris Sidebotham
149	avm/res/service-fabric/cluster	Service Fabric Cluster	lsnoddy Luke Snoddy
150	avm/res/service-networking/traffic-controller	Application Gateway for Containers (Traffic Controller)	krbar Kris Baranek
151	avm/res/signal-r-service/signal-r	SignalR Service SignalR
152	avm/res/signal-r-service/web-pub-sub	SignalR Web PubSub Service
153	avm/res/sql/instance-pool	SQL Instance Pool	gpacetti Giuseppe Pacetti
154	avm/res/sql/managed-instance	SQL Managed Instance SQL MI	maldineh Maher Aldineh
155	avm/res/sql/server	Azure SQL Server	peterbud Peter Budai
156	avm/res/storage/storage-account blob-service/container blob-service/container/immutability-policy file-service/share local-user management-policy queue-service/queue table-service/table	Storage Account	ktremain Karl Tremain fblix Felix Borst
157	avm/res/synapse/private-link-hub	Azure Synapse Analytics Private Link Hub	TomazMlakar Tomaz Mlakar
158	avm/res/synapse/workspace	Azure Synapse Analytics Workspace	TomazMlakar Tomaz Mlakar
159	avm/res/virtual-machine-images/image-template	Virtual Machine Image Template	ahmadabdalla Ahmad Abdalla
160	avm/res/web/connection	API Connection
161	avm/res/web/hosting-environment	App Service Environment ASE	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal
162	avm/res/web/serverfarm	App Service Plan	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal
163	avm/res/web/site config slot	Web/Function App App Service, Web Site, Logic App, Function App	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal
164	avm/res/web/static-site	Static Web App	ChrisSidebotham Chris Sidebotham

Proposed modules - ⚪

➕ Proposed Modules - Module names, status and owners

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/res/avs/private-cloud	AVS Private Cloud		vivalada Victor Saad Bueno Valadares
02	avm/res/azure-stack-hci/virtual-machine-instance	Azure Stack HCI Virtual Machine Instance		xhy8759 Hangyu Xu DanteMustCode Biao Jiang
03	avm/res/chaos/experiment	Chaos Experiment Azure Chaos Studio, Chaos Engineering		jbinko Jiri Binko
04	avm/res/dashboard/grafana	Azure Managed Grafana		vlahane Vishal Lahane
05	avm/res/data-protection/resource-guard	Data Protection Resource Guard
06	avm/res/hybrid-compute/private-link-scope	Hybrid Compute Private Link Scope		xhy8759 Hangyu Xu DanteMustCode Biao Jiang
07	avm/res/hybrid-compute/setting	Hybrid Compute Setting		xhy8759 Hangyu Xu DanteMustCode Biao Jiang
08	avm/res/insights/autoscale-setting	Insights - Auto Scale Setting		FallenHoot Zach Olinske
09	avm/res/iot-operations/instance	IoT Operations Instance		agreaves-ms Allen Greaves
10	avm/res/logic/integration-account	Logic Apps Integration Account		lsnoddy Luke Snoddy
11	avm/res/operational-insights/cluster	Log Analytics Dedicated Cluster		hundredacres Matt Schmitt
12	avm/res/scom/managed-instance	SCOM MI System Center Operations Manager - Managed Instance
13	avm/res/security-insights/onboarding-state	Security Insights - Onboarding State		hundredacres Matt Schmitt
14	avm/res/sql-virtual-machine/sql-virtual-machine	SQL Virtual Machine SQL VM		peterbud Peter Budai
15	avm/res/stream-analytics/streaming-job	Stram Analytics Job
16	❌ None listed	❌ None listed	❌ None listed	❌ None listed

Deprecated modules - 🔴

➕ Deprecated Modules - Module names, status and owners

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	❌ None listed	❌ None listed	❌ None listed	❌ None listed

All modules - 📇

➕ All Modules - Module names, status and owners

No.	Module Name	Display Name	Owner(s)
01	avm/res/aad/domain-service	Azure Active Directory Domain Service AAD, Entra ID, Microsoft Entra Domain Services, AAD DS, Azure AD DS	ReneHezser Rene Hezser CRYP70N1X Paul Chirila
02	avm/res/alerts-management/action-rule	Action Rules	judyer28 Justin Dyer
03	avm/res/analysis-services/server	Analysis Services Server
04	avm/res/api-management/service api api-version-set api/diagnostics api/policy authorization-server backend cache diagnostics identity-provider logger named-value policy portalsetting private-endpoint-connection product product/api product/group subscription workspace	API Management Service	tony-box Tony Box
05	avm/res/app-configuration/configuration-store	App Configuration Store	Jfolberth John Folberth
06	avm/res/app/container-app	Container App	oZakari Zach Trocinski
07	avm/res/app/job	App Job	ReneHezser Rene Hezser
08	avm/res/app/managed-environment	App Managed Environment	hundredacres Matt Schmitt
09	avm/res/app/session-pool	App Session Pool	jlinn-microsoft Joe Linn
10	avm/res/authorization/role-assignment mg-scope rg-scope sub-scope	Authorization - Role Assignment	arnoldna Nate Arnold
11	avm/res/automation/automation-account	Automation Account	gpacetti Giuseppe Pacetti
12	avm/res/avs/private-cloud	AVS Private Cloud	vivalada Victor Saad Bueno Valadares
13	avm/res/azure-stack-hci/cluster	Azure Stack HCI Cluster	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
14	avm/res/azure-stack-hci/logical-network	Azure Stack HCI Logical Network	xhy8759 Hangyu Xu duzitong Zidong Lu
15	avm/res/azure-stack-hci/marketplace-gallery-image	Azure Stack HCI Marketplace Gallery Image	xhy8759 Hangyu Xu duzitong Zidong Lu
16	avm/res/azure-stack-hci/network-interface	Azure Stack HCI Network Interface	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
17	avm/res/azure-stack-hci/virtual-hard-disk	Azure Stack HCI Hard Disk	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
18	avm/res/azure-stack-hci/virtual-machine-instance	Azure Stack HCI Virtual Machine Instance	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
19	avm/res/batch/batch-account	Batch Account	didayal-msft Divyadeep Dayal
20	avm/res/cache/redis	Redis Cache	hundredacres Matt Schmitt
21	avm/res/cache/redis-enterprise	Redis Enterprise Cache	JeffreyCA Jeffrey Chen
22	avm/res/cdn/profile	CDN Profile	gbeaud Guillaume Beaud
23	avm/res/chaos/experiment	Chaos Experiment Azure Chaos Studio, Chaos Engineering	jbinko Jiri Binko
24	avm/res/cognitive-services/account	Azure AI Services (Cognitive Services)	ilhaan Ilhaan Rasheed jceval Javier Cevallos
25	avm/res/communication/communication-service	Communication Service	donk-msft Don Koning
26	avm/res/communication/email-service	Email Communication Service	donk-msft Don Koning
27	avm/res/compute/availability-set	Availability Set AS	ahmadabdalla Ahmad Abdalla
28	avm/res/compute/disk	Compute Disk	segraef Sebastian Graef
29	avm/res/compute/disk-encryption-set	Disk Encryption Set	segraef Sebastian Graef
30	avm/res/compute/gallery	Azure Compute Gallery	ReneHezser Rene Hezser
31	avm/res/compute/image	Image	tony-box Tony Box
32	avm/res/compute/proximity-placement-group	Proximity Placement Group	jeetgarg Jeet Garg
33	avm/res/compute/ssh-public-key	Public SSH Key	ChrisSidebotham Chris Sidebotham
34	avm/res/compute/virtual-machine	Virtual Machine VM	josunefon Jordi Sune Fontanals
35	avm/res/compute/virtual-machine-scale-set	Virtual Machine Scale Set VMSS	josunefon Jordi Sune Fontanals
36	avm/res/consumption/budget	Consumption Budget	segraef Sebastian Graef
37	avm/res/container-instance/container-group	Container Instance ACI	JPEasier Julian Peißker
38	avm/res/container-registry/registry	Azure Container Registry (ACR)	JPEasier Julian Peißker
39	avm/res/container-service/managed-cluster	Azure Kubernetes Service (AKS) Managed Cluster	JPEasier Julian Peißker ilhaan Ilhaan Rasheed
40	avm/res/dashboard/grafana	Azure Managed Grafana	vlahane Vishal Lahane
41	avm/res/data-factory/factory	Data Factory	clintgrove Clint Grove
42	avm/res/data-protection/backup-vault	Data Protection Backup Vault	hundredacres Matt Schmitt
43	avm/res/data-protection/resource-guard	Data Protection Resource Guard
44	avm/res/databricks/access-connector	Azure Databricks Access Connector	clintgrove Clint Grove
45	avm/res/databricks/workspace	Azure Databricks Workspace	clintgrove Clint Grove
46	avm/res/db-for-my-sql/flexible-server	DB for MySQL Flexible Server	hundredacres Matt Schmitt
47	avm/res/db-for-postgre-sql/flexible-server	DB for Postgre SQL Flexible Server	arnoldna Nate Arnold
48	avm/res/desktop-virtualization/application-group	Azure Virtual Desktop (AVD) Application Group
49	avm/res/desktop-virtualization/host-pool	Azure Virtual Desktop (AVD) Host Pool
50	avm/res/desktop-virtualization/scaling-plan	Azure Virtual Desktop (AVD) Scaling Plan
51	avm/res/desktop-virtualization/workspace	Azure Virtual Desktop (AVD) Workspace
52	avm/res/dev-center/devcenter	Dev Center	ahmadabdalla Ahmad Abdalla
53	avm/res/dev-center/network-connection	Dev Center Network Connection	ahmadabdalla Ahmad Abdalla
54	avm/res/dev-center/project	Dev Center Project	ahmadabdalla Ahmad Abdalla
55	avm/res/dev-ops-infrastructure/pool	DevOps Infrastructure Pool	elizatargithub7 Eliza Tarasila surajguptha Suraj Guptha
56	avm/res/dev-test-lab/lab	DevTest Lab	ahmadabdalla Ahmad Abdalla
57	avm/res/digital-twins/digital-twins-instance	Digital Twins Instance	ryanmstephens Ryan Stephens
58	avm/res/document-db/database-account sql-role	Cosmos DB Database Account	seesharprun Sidney Andrews
59	avm/res/document-db/mongo-cluster	Cosmos DB for MongoDB (vCore)	sinedied Yohan Lasorsa
60	avm/res/elastic-san/elastic-san	Elastic SAN SAN, ESAN, Elastic SAN, Azure Elastic Storage Area Network, iSCSI, internet Small Computer Systems Interface	jbinko Jiri Binko
61	avm/res/event-grid/domain	Event Grid Domain	fabmas Fabio Masciotra
62	avm/res/event-grid/namespace	Event Grid Namespace	fabmas Fabio Masciotra
63	avm/res/event-grid/system-topic	Event Grid System Topic	fabmas Fabio Masciotra
64	avm/res/event-grid/topic	Event Grid Topic	fabmas Fabio Masciotra
65	avm/res/event-hub/namespace event-hub	Event Hub Namespace
66	avm/res/fabric/capacity	Fabric	hundredacres Matt Schmitt
67	avm/res/health-bot/health-bot	Azure Health Bot
68	avm/res/healthcare-apis/workspace	Healthcare API Workspace
69	avm/res/hybrid-compute/gateway	Hybrid Compute Gateway	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
70	avm/res/hybrid-compute/license	Hybrid Compute License	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
71	avm/res/hybrid-compute/machine	Hybrid Compute Machine	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
72	avm/res/hybrid-compute/private-link-scope	Hybrid Compute Private Link Scope	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
73	avm/res/hybrid-compute/setting	Hybrid Compute Setting	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
74	avm/res/hybrid-container-service/provisioned-cluster-instance	Hybrid Container Service - Provisioned Cluster Instance	xhy8759 Hangyu Xu duzitong Zidong Lu
75	avm/res/insights/action-group	Action Group	rahalan Rainer Halanek
76	avm/res/insights/activity-log-alert	Activity Log Alert	donk-msft Don Koning
77	avm/res/insights/autoscale-setting	Insights - Auto Scale Setting	FallenHoot Zach Olinske
78	avm/res/insights/component	Application Insight	krbar Kris Baranek
79	avm/res/insights/data-collection-endpoint	Data Collection Endpoint	krbar Kris Baranek
80	avm/res/insights/data-collection-rule	Data Collection Rule DCR	krbar Kris Baranek
81	avm/res/insights/diagnostic-setting	Diagnostic Setting	krbar Kris Baranek
82	avm/res/insights/metric-alert	Metric Alert	kijunkang Ki Jun Kang
83	avm/res/insights/private-link-scope	Azure Monitor Private Link Scope	ahmadabdalla Ahmad Abdalla
84	avm/res/insights/scheduled-query-rule	Scheduled Query Rule
85	avm/res/insights/webtest	Web Test	Jfolberth John Folberth
86	avm/res/iot-operations/instance	IoT Operations Instance	agreaves-ms Allen Greaves
87	avm/res/key-vault/vault access-policy key secret	Key Vault KV	fblix Felix Borst
88	avm/res/kubernetes-configuration/extension	Kubernetes Configuration Extension	JPEasier Julian Peißker
89	avm/res/kubernetes-configuration/flux-configuration	Kubernetes Configuration Flux Configuration	JPEasier Julian Peißker
90	avm/res/kubernetes/connected-cluster	Kubernetes Connected Cluster	xhy8759 Hangyu Xu duzitong Zidong Lu
91	avm/res/kusto/cluster	Azure Data Explorer (Kusto) cluster	oZakari Zach Trocinski
92	avm/res/load-test-service/load-test	Load Testing Service	sebassem Seif Bassem
93	avm/res/logic/integration-account	Logic Apps Integration Account	lsnoddy Luke Snoddy
94	avm/res/logic/workflow	Logic Apps Workflow	lsnoddy Luke Snoddy
95	avm/res/machine-learning-services/registry	Machine Learning Services Registry	josunefon Jordi Sune Fontanals
96	avm/res/machine-learning-services/workspace	Machine Learning Services Workspace ML Workspace	cecheta Chinedum Echeta ross-p-smith Ross Smith
97	avm/res/maintenance/configuration-assignment	Maintenance Configuration Assignment	eriqua Erika Gressi
98	avm/res/maintenance/maintenance-configuration	Maintenance Configuration	arievanderwende Arie van der Wende
99	avm/res/managed-identity/user-assigned-identity	User Assigned Identity MSI	gpacetti Giuseppe Pacetti
100	avm/res/managed-services/registration-definition	Registration Definition (Lighthouse)
101	avm/res/management/management-group	Management Group MG	fblix Felix Borst
102	avm/res/maps/account	Azure Maps Account	jhueppauff Julian Huppauff
103	avm/res/net-app/net-app-account	Azure NetApp File	fbinotto Felipe Binotto
104	avm/res/network/application-gateway	Application Gateway App GW	ilhaan Ilhaan Rasheed
105	avm/res/network/application-gateway-web-application-firewall-policy	Application Gateway Web Application Firewall (WAF) Policy	ilhaan Ilhaan Rasheed
106	avm/res/network/application-security-group	Application Security Group (ASG) ASG	segraef Sebastian Graef
107	avm/res/network/azure-firewall	Azure Firewall Azure FW	hundredacres Matt Schmitt
108	avm/res/network/bastion-host	Bastion Host	krbar Kris Baranek
109	avm/res/network/connection	Virtual Network Gateway Connection	fabmas Fabio Masciotra
110	avm/res/network/ddos-protection-plan	DDoS Protection Plan	segraef Sebastian Graef
111	avm/res/network/dns-forwarding-ruleset	DNS Forwarding Ruleset	ChrisSidebotham Chris Sidebotham
112	avm/res/network/dns-resolver	DNS Resolver	ChrisSidebotham Chris Sidebotham
113	avm/res/network/dns-zone	Public DNS Zone	ChrisSidebotham Chris Sidebotham
114	avm/res/network/express-route-circuit	ExpressRoute Circuit ER Circuit	arnoldna Nate Arnold
115	avm/res/network/express-route-gateway	Express Route Gateway ER GW	arnoldna Nate Arnold
116	avm/res/network/express-route-port	ExpressRoute Port ER Port	arnoldna Nate Arnold
117	avm/res/network/firewall-policy	Firewall Policy	PaulJohnston88 Paul Johnston
118	avm/res/network/front-door	Azure Front Door	hundredacres Matt Schmitt
119	avm/res/network/front-door-web-application-firewall-policy	Front Door Web Application Firewall (WAF) Policy	PaulJohnston88 Paul Johnston
120	avm/res/network/ip-group	IP Group	ahmadabdalla Ahmad Abdalla
121	avm/res/network/load-balancer	Load Balancer LB, NLB	arnoldna Nate Arnold
122	avm/res/network/local-network-gateway	Local Network Gateway	fabmas Fabio Masciotra
123	avm/res/network/nat-gateway	NAT Gateway NAT GW	fabmas Fabio Masciotra
124	avm/res/network/network-interface	Network Interface NIC	rahalan Rainer Halanek
125	avm/res/network/network-manager	Network Manager	ahmadabdalla Ahmad Abdalla
126	avm/res/network/network-security-group	Network Security Group NSG	ahmadabdalla Ahmad Abdalla
127	avm/res/network/network-security-perimeter	Network Security Perimeter	peterbud Peter Budai
128	avm/res/network/network-watcher	Network Watcher	segraef Sebastian Graef
129	avm/res/network/p2s-vpn-gateway	P2S VPN Gateway	ericscheffler Eric Scheffler
130	avm/res/network/private-dns-zone a aaaa cname mx ptr soa srv txt virtual-network-link	Private DNS Zone	ChrisSidebotham Chris Sidebotham
131	avm/res/network/private-endpoint	Private Endpoint	segraef Sebastian Graef
132	avm/res/network/private-link-service	Private Link Service	ahmadabdalla Ahmad Abdalla
133	avm/res/network/public-ip-address	Public IP Address PIP	ChrisSidebotham Chris Sidebotham krbar Kris Baranek
134	avm/res/network/public-ip-prefix	Public IP Prefix PIP Prefix	krbar Kris Baranek
135	avm/res/network/route-table	Route Table UDR	segraef Sebastian Graef
136	avm/res/network/service-endpoint-policy	Service Endpoint Policy	jeetgarg Jeet Garg
137	avm/res/network/trafficmanagerprofile	Traffic Manager Profile	lsnoddy Luke Snoddy
138	avm/res/network/virtual-hub route-map	Virtual Hub	arnoldna Nate Arnold
139	avm/res/network/virtual-network subnet	Virtual Network VNET	mjrich19 MJ Richardson
140	avm/res/network/virtual-network-gateway	Virtual Network Gateway VNET GW	fabmas Fabio Masciotra
141	avm/res/network/virtual-wan	Virtual WAN vWAN	arnoldna Nate Arnold
142	avm/res/network/vpn-gateway	VPN Gateway VPN GW	fabmas Fabio Masciotra
143	avm/res/network/vpn-server-configuration	VPN Server Configuration	ericscheffler Eric Scheffler
144	avm/res/network/vpn-site	VPN Site	fabmas Fabio Masciotra
145	avm/res/operational-insights/cluster	Log Analytics Dedicated Cluster	hundredacres Matt Schmitt
146	avm/res/operational-insights/workspace	Log Analytics Workspace	krbar Kris Baranek
147	avm/res/operations-management/solution	Operations Management Solution	krbar Kris Baranek
148	avm/res/portal/dashboard	Portal Dashboard	krbar Kris Baranek
149	avm/res/power-bi-dedicated/capacity	Power BI Dedicated Capacity	ChrisSidebotham Chris Sidebotham
150	avm/res/purview/account	Purview Account	hundredacres Matt Schmitt
151	avm/res/recovery-services/vault	Recovery Services Vault	alexanderojala Alexander Ojala
152	avm/res/relay/namespace	Relay Namespace
153	avm/res/resource-graph/query	Resource Graph Query	sebassem Seif Bassem
154	avm/res/resources/deployment-script	Deployment Script	sebassem Seif Bassem
155	avm/res/resources/resource-group	Resource Group RG	segraef Sebastian Graef
156	avm/res/scom/managed-instance	SCOM MI System Center Operations Manager - Managed Instance
157	avm/res/search/search-service	Search Service	krbar Kris Baranek
158	avm/res/security-insights/data-connector	Security Insights - Data Connector	hundredacres Matt Schmitt
159	avm/res/security-insights/onboarding-state	Security Insights - Onboarding State	hundredacres Matt Schmitt
160	avm/res/security-insights/setting	Security Insights - Setting	hundredacres Matt Schmitt
161	avm/res/service-bus/namespace	Service Bus Namespace	ChrisSidebotham Chris Sidebotham
162	avm/res/service-fabric/cluster	Service Fabric Cluster	lsnoddy Luke Snoddy
163	avm/res/service-networking/traffic-controller	Application Gateway for Containers (Traffic Controller)	krbar Kris Baranek
164	avm/res/signal-r-service/signal-r	SignalR Service SignalR
165	avm/res/signal-r-service/web-pub-sub	SignalR Web PubSub Service
166	avm/res/sql-virtual-machine/sql-virtual-machine	SQL Virtual Machine SQL VM	peterbud Peter Budai
167	avm/res/sql/instance-pool	SQL Instance Pool	gpacetti Giuseppe Pacetti
168	avm/res/sql/managed-instance	SQL Managed Instance SQL MI	maldineh Maher Aldineh
169	avm/res/sql/server	Azure SQL Server	peterbud Peter Budai
170	avm/res/storage/storage-account blob-service/container blob-service/container/immutability-policy file-service/share local-user management-policy queue-service/queue table-service/table	Storage Account	ktremain Karl Tremain fblix Felix Borst
171	avm/res/stream-analytics/streaming-job	Stram Analytics Job
172	avm/res/synapse/private-link-hub	Azure Synapse Analytics Private Link Hub	TomazMlakar Tomaz Mlakar
173	avm/res/synapse/workspace	Azure Synapse Analytics Workspace	TomazMlakar Tomaz Mlakar
174	avm/res/virtual-machine-images/image-template	Virtual Machine Image Template	ahmadabdalla Ahmad Abdalla
175	avm/res/web/connection	API Connection
176	avm/res/web/hosting-environment	App Service Environment ASE	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal
177	avm/res/web/serverfarm	App Service Plan	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal
178	avm/res/web/site config slot	Web/Function App App Service, Web Site, Logic App, Function App	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal
179	avm/res/web/static-site	Static Web App	ChrisSidebotham Chris Sidebotham

Module Publication History - 📅

➕ Module Publication History - Module names, status and owners

Modules published in July 2025

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/res/azure-stack-hci/marketplace-gallery-image	Azure Stack HCI Marketplace Gallery Image		xhy8759 Hangyu Xu duzitong Zidong Lu

Modules published in June 2025

No.	Module Name	Display Name	Owner(s)
01	avm/res/authorization/role-assignment/mg-scope	Authorization - Role Assignment - Management Group Scope (Child of avm/res/authorization/role-assignment)	(Inherited): arnoldna Nate Arnold
02	avm/res/authorization/role-assignment/rg-scope	Authorization - Role Assignment - Resource Group Scope (Child of avm/res/authorization/role-assignment)	(Inherited): arnoldna Nate Arnold
03	avm/res/authorization/role-assignment/sub-scope	Authorization - Role Assignment - Subscription Scope (Child of avm/res/authorization/role-assignment)	(Inherited): arnoldna Nate Arnold
04	avm/res/dev-center/devcenter	Dev Center	ahmadabdalla Ahmad Abdalla
05	avm/res/dev-center/project	Dev Center Project	ahmadabdalla Ahmad Abdalla
06	avm/res/machine-learning-services/registry	Machine Learning Services Registry	josunefon Jordi Sune Fontanals
07	avm/res/storage/storage-account/blob-service/container	Storage Account - Blob Container (Child of avm/res/storage/storage-account)	(Inherited): ktremain Karl Tremain fblix Felix Borst

Modules published in May 2025

No.	Module Name	Display Name	Owner(s)
01	avm/res/dev-center/network-connection	Dev Center Network Connection	ahmadabdalla Ahmad Abdalla
02	avm/res/security-insights/data-connector	Security Insights - Data Connector	hundredacres Matt Schmitt
03	avm/res/security-insights/setting	Security Insights - Setting	hundredacres Matt Schmitt

Modules published in March 2025

No.	Module Name	Display Name	Owner(s)
01	avm/res/azure-stack-hci/network-interface	Azure Stack HCI Network Interface	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
02	avm/res/azure-stack-hci/virtual-hard-disk	Azure Stack HCI Hard Disk	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
03	avm/res/hybrid-container-service/provisioned-cluster-instance	Hybrid Container Service - Provisioned Cluster Instance	xhy8759 Hangyu Xu duzitong Zidong Lu
04	avm/res/kubernetes/connected-cluster	Kubernetes Connected Cluster	xhy8759 Hangyu Xu duzitong Zidong Lu
05	avm/res/maintenance/configuration-assignment	Maintenance Configuration Assignment	eriqua Erika Gressi
06	avm/res/maps/account	Azure Maps Account	jhueppauff Julian Huppauff
07	avm/res/network/network-security-perimeter	Network Security Perimeter	peterbud Peter Budai
08	avm/res/network/virtual-network/subnet	Virtual Network - Subnet (Child of avm/res/network/virtual-network)	(Inherited): mjrich19 MJ Richardson

Modules published in February 2025

No.	Module Name	Display Name	Owner(s)
01	avm/res/app/session-pool	App Session Pool	jlinn-microsoft Joe Linn
02	avm/res/azure-stack-hci/cluster	Azure Stack HCI Cluster	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
03	avm/res/azure-stack-hci/logical-network	Azure Stack HCI Logical Network	xhy8759 Hangyu Xu duzitong Zidong Lu
04	avm/res/cache/redis-enterprise	Redis Enterprise Cache	JeffreyCA Jeffrey Chen
05	avm/res/hybrid-compute/gateway	Hybrid Compute Gateway	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
06	avm/res/hybrid-compute/license	Hybrid Compute License	xhy8759 Hangyu Xu DanteMustCode Biao Jiang

Modules published in January 2025

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/res/network/express-route-port	ExpressRoute Port ER Port		arnoldna Nate Arnold

Modules published in December 2024

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/res/elastic-san/elastic-san	Elastic SAN SAN, ESAN, Elastic SAN, Azure Elastic Storage Area Network, iSCSI, internet Small Computer Systems Interface		jbinko Jiri Binko
02	avm/res/network/p2s-vpn-gateway	P2S VPN Gateway		ericscheffler Eric Scheffler

Modules published in October 2024

No.	Module Name	Display Name	Owner(s)
01	avm/res/fabric/capacity	Fabric	hundredacres Matt Schmitt
02	avm/res/network/vpn-server-configuration	VPN Server Configuration	ericscheffler Eric Scheffler
03	avm/res/service-networking/traffic-controller	Application Gateway for Containers (Traffic Controller)	krbar Kris Baranek

Modules published in September 2024

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/res/dev-ops-infrastructure/pool	DevOps Infrastructure Pool		elizatargithub7 Eliza Tarasila surajguptha Suraj Guptha

Modules published in June 2024

No.	Module Name	Display Name	Owner(s)
01	avm/res/alerts-management/action-rule	Action Rules	judyer28 Justin Dyer
02	avm/res/hybrid-compute/machine	Hybrid Compute Machine	xhy8759 Hangyu Xu DanteMustCode Biao Jiang
03	avm/res/kusto/cluster	Azure Data Explorer (Kusto) cluster	oZakari Zach Trocinski
04	avm/res/portal/dashboard	Portal Dashboard	krbar Kris Baranek

Modules published in May 2024

No.	Module Name	Display Name	Owner(s)
01	avm/res/app/job	App Job	ReneHezser Rene Hezser
02	avm/res/communication/communication-service	Communication Service	donk-msft Don Koning
03	avm/res/communication/email-service	Email Communication Service	donk-msft Don Koning

Modules published in April 2024

No.	Module Name	Display Name	Owner(s)
01	avm/res/aad/domain-service	Azure Active Directory Domain Service AAD, Entra ID, Microsoft Entra Domain Services, AAD DS, Azure AD DS	ReneHezser Rene Hezser CRYP70N1X Paul Chirila
02	avm/res/healthcare-apis/workspace	Healthcare API Workspace
03	avm/res/load-test-service/load-test	Load Testing Service	sebassem Seif Bassem
04	avm/res/managed-services/registration-definition	Registration Definition (Lighthouse)
05	avm/res/network/application-gateway	Application Gateway App GW	ilhaan Ilhaan Rasheed
06	avm/res/network/application-gateway-web-application-firewall-policy	Application Gateway Web Application Firewall (WAF) Policy	ilhaan Ilhaan Rasheed
07	avm/res/network/network-watcher	Network Watcher	segraef Sebastian Graef
08	avm/res/service-fabric/cluster	Service Fabric Cluster	lsnoddy Luke Snoddy
09	avm/res/sql/instance-pool	SQL Instance Pool	gpacetti Giuseppe Pacetti
10	avm/res/sql/managed-instance	SQL Managed Instance SQL MI	maldineh Maher Aldineh

Modules published in March 2024

No.	Module Name	Display Name	Owner(s)
01	avm/res/app-configuration/configuration-store	App Configuration Store	Jfolberth John Folberth
02	avm/res/cdn/profile	CDN Profile	gbeaud Guillaume Beaud
03	avm/res/compute/virtual-machine-scale-set	Virtual Machine Scale Set VMSS	josunefon Jordi Sune Fontanals
04	avm/res/container-instance/container-group	Container Instance ACI	JPEasier Julian Peißker
05	avm/res/digital-twins/digital-twins-instance	Digital Twins Instance	ryanmstephens Ryan Stephens
06	avm/res/event-grid/namespace	Event Grid Namespace	fabmas Fabio Masciotra
07	avm/res/event-hub/namespace	Event Hub Namespace
08	avm/res/network/azure-firewall	Azure Firewall Azure FW	hundredacres Matt Schmitt
09	avm/res/network/service-endpoint-policy	Service Endpoint Policy	jeetgarg Jeet Garg
10	avm/res/recovery-services/vault	Recovery Services Vault	alexanderojala Alexander Ojala
11	avm/res/relay/namespace	Relay Namespace
12	avm/res/signal-r-service/signal-r	SignalR Service SignalR
13	avm/res/signal-r-service/web-pub-sub	SignalR Web PubSub Service
14	avm/res/web/connection	API Connection
15	avm/res/web/hosting-environment	App Service Environment ASE	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal

Modules published in February 2024

No.	Module Name	Display Name	Owner(s)
01	avm/res/compute/availability-set	Availability Set AS	ahmadabdalla Ahmad Abdalla
02	avm/res/desktop-virtualization/application-group	Azure Virtual Desktop (AVD) Application Group
03	avm/res/desktop-virtualization/host-pool	Azure Virtual Desktop (AVD) Host Pool
04	avm/res/desktop-virtualization/scaling-plan	Azure Virtual Desktop (AVD) Scaling Plan
05	avm/res/desktop-virtualization/workspace	Azure Virtual Desktop (AVD) Workspace
06	avm/res/dev-test-lab/lab	DevTest Lab	ahmadabdalla Ahmad Abdalla
07	avm/res/insights/private-link-scope	Azure Monitor Private Link Scope	ahmadabdalla Ahmad Abdalla
08	avm/res/machine-learning-services/workspace	Machine Learning Services Workspace ML Workspace	cecheta Chinedum Echeta ross-p-smith Ross Smith
09	avm/res/management/management-group	Management Group MG	fblix Felix Borst
10	avm/res/network/ip-group	IP Group	ahmadabdalla Ahmad Abdalla
11	avm/res/network/network-manager	Network Manager	ahmadabdalla Ahmad Abdalla
12	avm/res/network/private-link-service	Private Link Service	ahmadabdalla Ahmad Abdalla
13	avm/res/network/virtual-hub	Virtual Hub	arnoldna Nate Arnold
14	avm/res/network/virtual-wan	Virtual WAN vWAN	arnoldna Nate Arnold
15	avm/res/purview/account	Purview Account	hundredacres Matt Schmitt
16	avm/res/synapse/private-link-hub	Azure Synapse Analytics Private Link Hub	TomazMlakar Tomaz Mlakar
17	avm/res/synapse/workspace	Azure Synapse Analytics Workspace	TomazMlakar Tomaz Mlakar
18	avm/res/virtual-machine-images/image-template	Virtual Machine Image Template	ahmadabdalla Ahmad Abdalla

Modules published in January 2024

No.	Module Name	Display Name	Owner(s)
01	avm/res/analysis-services/server	Analysis Services Server
02	avm/res/app/container-app	Container App	oZakari Zach Trocinski
03	avm/res/cache/redis	Redis Cache	hundredacres Matt Schmitt
04	avm/res/compute/disk	Compute Disk	segraef Sebastian Graef
05	avm/res/compute/disk-encryption-set	Disk Encryption Set	segraef Sebastian Graef
06	avm/res/compute/image	Image	tony-box Tony Box
07	avm/res/compute/proximity-placement-group	Proximity Placement Group	jeetgarg Jeet Garg
08	avm/res/compute/virtual-machine	Virtual Machine VM	josunefon Jordi Sune Fontanals
09	avm/res/consumption/budget	Consumption Budget	segraef Sebastian Graef
10	avm/res/container-registry/registry	Azure Container Registry (ACR)	JPEasier Julian Peißker
11	avm/res/container-service/managed-cluster	Azure Kubernetes Service (AKS) Managed Cluster	JPEasier Julian Peißker ilhaan Ilhaan Rasheed
12	avm/res/data-protection/backup-vault	Data Protection Backup Vault	hundredacres Matt Schmitt
13	avm/res/databricks/access-connector	Azure Databricks Access Connector	clintgrove Clint Grove
14	avm/res/databricks/workspace	Azure Databricks Workspace	clintgrove Clint Grove
15	avm/res/db-for-my-sql/flexible-server	DB for MySQL Flexible Server	hundredacres Matt Schmitt
16	avm/res/health-bot/health-bot	Azure Health Bot
17	avm/res/net-app/net-app-account	Azure NetApp File	fbinotto Felipe Binotto
18	avm/res/network/ddos-protection-plan	DDoS Protection Plan	segraef Sebastian Graef
19	avm/res/network/firewall-policy	Firewall Policy	PaulJohnston88 Paul Johnston
20	avm/res/network/front-door	Azure Front Door	hundredacres Matt Schmitt
21	avm/res/network/front-door-web-application-firewall-policy	Front Door Web Application Firewall (WAF) Policy	PaulJohnston88 Paul Johnston
22	avm/res/network/local-network-gateway	Local Network Gateway	fabmas Fabio Masciotra
23	avm/res/network/nat-gateway	NAT Gateway NAT GW	fabmas Fabio Masciotra
24	avm/res/network/virtual-network-gateway	Virtual Network Gateway VNET GW	fabmas Fabio Masciotra
25	avm/res/network/vpn-gateway	VPN Gateway VPN GW	fabmas Fabio Masciotra
26	avm/res/storage/storage-account	Storage Account	ktremain Karl Tremain fblix Felix Borst
27	avm/res/web/site	Web/Function App App Service, Web Site, Logic App, Function App	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal
28	avm/res/web/static-site	Static Web App	ChrisSidebotham Chris Sidebotham

Modules published in December 2023

No.	Module Name	Display Name	Owner(s)
01	avm/res/api-management/service	API Management Service	tony-box Tony Box
02	avm/res/app/managed-environment	App Managed Environment	hundredacres Matt Schmitt
03	avm/res/automation/automation-account	Automation Account	gpacetti Giuseppe Pacetti
04	avm/res/compute/gallery	Azure Compute Gallery	ReneHezser Rene Hezser
05	avm/res/data-factory/factory	Data Factory	clintgrove Clint Grove
06	avm/res/document-db/database-account	Cosmos DB Database Account	seesharprun Sidney Andrews
07	avm/res/insights/activity-log-alert	Activity Log Alert	donk-msft Don Koning
08	avm/res/insights/data-collection-endpoint	Data Collection Endpoint	krbar Kris Baranek
09	avm/res/insights/data-collection-rule	Data Collection Rule DCR	krbar Kris Baranek
10	avm/res/insights/metric-alert	Metric Alert	kijunkang Ki Jun Kang
11	avm/res/insights/scheduled-query-rule	Scheduled Query Rule
12	avm/res/insights/webtest	Web Test	Jfolberth John Folberth
13	avm/res/maintenance/maintenance-configuration	Maintenance Configuration	arievanderwende Arie van der Wende
14	avm/res/managed-identity/user-assigned-identity	User Assigned Identity MSI	gpacetti Giuseppe Pacetti
15	avm/res/network/application-security-group	Application Security Group (ASG) ASG	segraef Sebastian Graef
16	avm/res/network/bastion-host	Bastion Host	krbar Kris Baranek
17	avm/res/network/connection	Virtual Network Gateway Connection	fabmas Fabio Masciotra
18	avm/res/network/network-security-group	Network Security Group NSG	ahmadabdalla Ahmad Abdalla
19	avm/res/network/public-ip-prefix	Public IP Prefix PIP Prefix	krbar Kris Baranek
20	avm/res/network/trafficmanagerprofile	Traffic Manager Profile	lsnoddy Luke Snoddy
21	avm/res/network/vpn-site	VPN Site	fabmas Fabio Masciotra
22	avm/res/resources/resource-group	Resource Group RG	segraef Sebastian Graef
23	avm/res/service-bus/namespace	Service Bus Namespace	ChrisSidebotham Chris Sidebotham
24	avm/res/web/serverfarm	App Service Plan	tsc-buddy Buddy Davies pankajagrawal16 Pankaj Agrawal

Modules published in November 2023

No.	Module Name	Display Name	Owner(s)
01	avm/res/batch/batch-account	Batch Account	didayal-msft Divyadeep Dayal
02	avm/res/db-for-postgre-sql/flexible-server	DB for Postgre SQL Flexible Server	arnoldna Nate Arnold
03	avm/res/event-grid/domain	Event Grid Domain	fabmas Fabio Masciotra
04	avm/res/event-grid/system-topic	Event Grid System Topic	fabmas Fabio Masciotra
05	avm/res/event-grid/topic	Event Grid Topic	fabmas Fabio Masciotra
06	avm/res/insights/component	Application Insight	krbar Kris Baranek
07	avm/res/insights/diagnostic-setting	Diagnostic Setting	krbar Kris Baranek
08	avm/res/logic/workflow	Logic Apps Workflow	lsnoddy Luke Snoddy
09	avm/res/network/express-route-circuit	ExpressRoute Circuit ER Circuit	arnoldna Nate Arnold
10	avm/res/network/express-route-gateway	Express Route Gateway ER GW	arnoldna Nate Arnold
11	avm/res/network/load-balancer	Load Balancer LB, NLB	arnoldna Nate Arnold
12	avm/res/network/route-table	Route Table UDR	segraef Sebastian Graef
13	avm/res/network/virtual-network	Virtual Network VNET	mjrich19 MJ Richardson
14	avm/res/operational-insights/workspace	Log Analytics Workspace	krbar Kris Baranek
15	avm/res/operations-management/solution	Operations Management Solution	krbar Kris Baranek
16	avm/res/power-bi-dedicated/capacity	Power BI Dedicated Capacity	ChrisSidebotham Chris Sidebotham
17	avm/res/resource-graph/query	Resource Graph Query	sebassem Seif Bassem
18	avm/res/resources/deployment-script	Deployment Script	sebassem Seif Bassem
19	avm/res/search/search-service	Search Service	krbar Kris Baranek
20	avm/res/sql/server	Azure SQL Server	peterbud Peter Budai

Modules published in October 2023

No.	Module Name	Display Name	Owner(s)
01	avm/res/cognitive-services/account	Azure AI Services (Cognitive Services)	ilhaan Ilhaan Rasheed jceval Javier Cevallos
02	avm/res/compute/ssh-public-key	Public SSH Key	ChrisSidebotham Chris Sidebotham
03	avm/res/document-db/mongo-cluster	Cosmos DB for MongoDB (vCore)	sinedied Yohan Lasorsa
04	avm/res/insights/action-group	Action Group	rahalan Rainer Halanek
05	avm/res/key-vault/vault	Key Vault KV	fblix Felix Borst
06	avm/res/kubernetes-configuration/extension	Kubernetes Configuration Extension	JPEasier Julian Peißker
07	avm/res/kubernetes-configuration/flux-configuration	Kubernetes Configuration Flux Configuration	JPEasier Julian Peißker
08	avm/res/network/dns-forwarding-ruleset	DNS Forwarding Ruleset	ChrisSidebotham Chris Sidebotham
09	avm/res/network/dns-resolver	DNS Resolver	ChrisSidebotham Chris Sidebotham
10	avm/res/network/dns-zone	Public DNS Zone	ChrisSidebotham Chris Sidebotham
11	avm/res/network/network-interface	Network Interface NIC	rahalan Rainer Halanek
12	avm/res/network/private-dns-zone	Private DNS Zone	ChrisSidebotham Chris Sidebotham
13	avm/res/network/private-endpoint	Private Endpoint	segraef Sebastian Graef
14	avm/res/network/public-ip-address	Public IP Address PIP	ChrisSidebotham Chris Sidebotham krbar Kris Baranek

For Module Owners & Contributors

Note

This section is mainly intended for module owners and contributors as it contains information important for module development, such as telemetry ID prefix, and GitHub Teams for Owners & Contributors.

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

➕ All Modules - Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

No.	Module Name	Telemetry ID prefix	GitHub Teams for Module Owners and Contributors
01	avm/res/aad/domain-service	`46d3xbcp.res.aad-domainservice`	`@Azure/avm-res-aad-domainservice-module-owners-bicep` `@Azure/avm-res-aad-domainservice-module-contributors-bicep`
02	avm/res/alerts-management/action-rule	`46d3xbcp.res.alertsmanagement-actionrule`	`@Azure/avm-res-alertsmanagement-actionrule-module-owners-bicep` `@Azure/avm-res-alertsmanagement-actionrule-module-contributors-bicep`
03	avm/res/analysis-services/server	`46d3xbcp.res.analysisservices-server`	`@Azure/avm-res-analysisservices-server-module-owners-bicep` `@Azure/avm-res-analysisservices-server-module-contributors-bicep`
04	avm/res/api-management/service	`46d3xbcp.res.apimanagement-service`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
05	avm/res/api-management/service/api	`46d3xbcp.res.apimgmt-api`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
06	avm/res/api-management/service/api-version-set	`46d3xbcp.res.apimgmt-apiversionset`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
07	avm/res/api-management/service/api/diagnostics	`46d3xbcp.res.apimgm-apidiagnostics`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
08	avm/res/api-management/service/api/policy	`46d3xbcp.res.apimgmt-apipolicy`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
09	avm/res/api-management/service/authorization-server	`46d3xbcp.res.apimgmt-authzserver`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
10	avm/res/api-management/service/backend	`46d3xbcp.res.apimgmt-backend`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
11	avm/res/api-management/service/cache	`46d3xbcp.res.apimgmt-cache`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
12	avm/res/api-management/service/diagnostics	`46d3xbcp.res.apimgmt-diagnostics`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
13	avm/res/api-management/service/identity-provider	`46d3xbcp.res.apimgmt-identityprovider`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
14	avm/res/api-management/service/logger	`46d3xbcp.res.apimgmt-logger`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
15	avm/res/api-management/service/named-value	`46d3xbcp.res.apimgmt-namedvalue`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
16	avm/res/api-management/service/policy	`46d3xbcp.res.apimgmt-policy`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
17	avm/res/api-management/service/portalsetting	`46d3xbcp.res.apimgmt-portalsetting`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
18	avm/res/api-management/service/private-endpoint-connection	`46d3xbcp.res.apimgmt-privendpointconn`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
19	avm/res/api-management/service/product	`46d3xbcp.res.apimgmt-product`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
20	avm/res/api-management/service/product/api	`46d3xbcp.res.apimgmt-productapi`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
21	avm/res/api-management/service/product/group	`46d3xbcp.res.apimgmt-productgroup`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
22	avm/res/api-management/service/subscription	`46d3xbcp.res.apimgmt-subscription`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
23	avm/res/api-management/service/workspace	`46d3xbcp.res.apimgmt-workspace`	`@Azure/avm-res-apimanagement-service-module-owners-bicep` `@Azure/avm-res-apimanagement-service-module-contributors-bicep`
24	avm/res/app-configuration/configuration-store	`46d3xbcp.res.appconfiguration-configurationstore`	`@Azure/avm-res-appconfiguration-configurationstore-module-owners-bicep` `@Azure/avm-res-appconfiguration-configurationstore-module-contributors-bicep`
25	avm/res/app/container-app	`46d3xbcp.res.app-containerapp`	`@Azure/avm-res-app-containerapp-module-owners-bicep` `@Azure/avm-res-app-containerapp-module-contributors-bicep`
26	avm/res/app/job	`46d3xbcp.res.app-job`	`@Azure/avm-res-app-job-module-owners-bicep` `@Azure/avm-res-app-job-module-contributors-bicep`
27	avm/res/app/managed-environment	`46d3xbcp.res.app-managedenvironment`	`@Azure/avm-res-app-managedenvironment-module-owners-bicep` `@Azure/avm-res-app-managedenvironment-module-contributors-bicep`
28	avm/res/app/session-pool	`46d3xbcp.res.app-sessionpool`	`@Azure/avm-res-app-sessionpool-module-owners-bicep` `@Azure/avm-res-app-sessionpool-module-contributors-bicep`
29	avm/res/authorization/role-assignment	`46d3xbcp.res.authz-roleassignment`	`@Azure/avm-res-authorization-roleassignment-module-owners-bicep` `@Azure/avm-res-authorization-roleassignment-module-contributors-bicep`
30	avm/res/authorization/role-assignment/mg-scope	`46d3xbcp.res.authz-roleassignment_mgscope`	`@Azure/avm-res-authorization-roleassignment-module-owners-bicep` `@Azure/avm-res-authorization-roleassignment-module-contributors-bicep`
31	avm/res/authorization/role-assignment/rg-scope	`46d3xbcp.res.authz-roleassignment_rgscope`	`@Azure/avm-res-authorization-roleassignment-module-owners-bicep` `@Azure/avm-res-authorization-roleassignment-module-contributors-bicep`
32	avm/res/authorization/role-assignment/sub-scope	`46d3xbcp.res.authz-roleassignment_subscope`	`@Azure/avm-res-authorization-roleassignment-module-owners-bicep` `@Azure/avm-res-authorization-roleassignment-module-contributors-bicep`
33	avm/res/automation/automation-account	`46d3xbcp.res.automation-automationaccount`	`@Azure/avm-res-automation-automationaccount-module-owners-bicep` `@Azure/avm-res-automation-automationaccount-module-contributors-bicep`
34	avm/res/avs/private-cloud	`46d3xbcp.res.avs-privatecloud`	`@Azure/avm-res-avs-privatecloud-module-owners-bicep` `@Azure/avm-res-avs-privatecloud-module-contributors-bicep`
35	avm/res/azure-stack-hci/cluster	`46d3xbcp.res.azurestackhci-cluster`	`@Azure/avm-res-azurestackhci-cluster-module-owners-bicep` `@Azure/avm-res-azurestackhci-cluster-module-contributors-bicep`
36	avm/res/azure-stack-hci/logical-network	`46d3xbcp.res.azurestackhci-logicalnetwork`	`@Azure/avm-res-azurestackhci-logicalnetwork-module-owners-bicep` `@Azure/avm-res-azurestackhci-logicalnetwork-module-contributors-bicep`
37	avm/res/azure-stack-hci/marketplace-gallery-image	`46d3xbcp.res.azurestackhci-markplgalleryimg`	`@Azure/avm-res-azurestackhci-marketplacegalleryimage-module-owners-bicep` `@Azure/avm-res-azurestackhci-marketplacegalleryimage-module-contributors-bicep`
38	avm/res/azure-stack-hci/network-interface	`46d3xbcp.res.azurestackhci-networkinterface`	`@Azure/avm-res-azurestackhci-networkinterface-module-owners-bicep` `@Azure/avm-res-azurestackhci-networkinterface-module-contributors-bicep`
39	avm/res/azure-stack-hci/virtual-hard-disk	`46d3xbcp.res.azurestackhci-virtualharddisk`	`@Azure/avm-res-azurestackhci-virtualharddisk-module-owners-bicep` `@Azure/avm-res-azurestackhci-virtualharddisk-module-contributors-bicep`
40	avm/res/azure-stack-hci/virtual-machine-instance	`46d3xbcp.res.azurestackhci-virtualmachineinstance`	`@Azure/avm-res-azurestackhci-virtualmachineinstance-module-owners-bicep` `@Azure/avm-res-azurestackhci-virtualmachineinstance-module-contributors-bicep`
41	avm/res/batch/batch-account	`46d3xbcp.res.batch-batchaccount`	`@Azure/avm-res-batch-batchaccount-module-owners-bicep` `@Azure/avm-res-batch-batchaccount-module-contributors-bicep`
42	avm/res/cache/redis	`46d3xbcp.res.cache-redis`	`@Azure/avm-res-cache-redis-module-owners-bicep` `@Azure/avm-res-cache-redis-module-contributors-bicep`
43	avm/res/cache/redis-enterprise	`46d3xbcp.res.cache-redisenterprise`	`@Azure/avm-res-cache-redisenterprise-module-owners-bicep` `@Azure/avm-res-cache-redisenterprise-module-contributors-bicep`
44	avm/res/cdn/profile	`46d3xbcp.res.cdn-profile`	`@Azure/avm-res-cdn-profile-module-owners-bicep` `@Azure/avm-res-cdn-profile-module-contributors-bicep`
45	avm/res/chaos/experiment	`46d3xbcp.res.chaos-experiment`	`@Azure/avm-res-chaos-experiment-module-owners-bicep` `@Azure/avm-res-chaos-experiment-module-contributors-bicep`
46	avm/res/cognitive-services/account	`46d3xbcp.res.cognitiveservices-account`	`@Azure/avm-res-cognitiveservices-account-module-owners-bicep` `@Azure/avm-res-cognitiveservices-account-module-contributors-bicep`
47	avm/res/communication/communication-service	`46d3xbcp.res.communication-communicationservice`	`@Azure/avm-res-communication-communicationservice-module-owners-bicep` `@Azure/avm-res-communication-communicationservice-module-contributors-bicep`
48	avm/res/communication/email-service	`46d3xbcp.res.communication-emailservice`	`@Azure/avm-res-communication-emailservice-module-owners-bicep` `@Azure/avm-res-communication-emailservice-module-contributors-bicep`
49	avm/res/compute/availability-set	`46d3xbcp.res.compute-availabilityset`	`@Azure/avm-res-compute-availabilityset-module-owners-bicep` `@Azure/avm-res-compute-availabilityset-module-contributors-bicep`
50	avm/res/compute/disk	`46d3xbcp.res.compute-disk`	`@Azure/avm-res-compute-disk-module-owners-bicep` `@Azure/avm-res-compute-disk-module-contributors-bicep`
51	avm/res/compute/disk-encryption-set	`46d3xbcp.res.compute-diskencryptionset`	`@Azure/avm-res-compute-diskencryptionset-module-owners-bicep` `@Azure/avm-res-compute-diskencryptionset-module-contributors-bicep`
52	avm/res/compute/gallery	`46d3xbcp.res.compute-gallery`	`@Azure/avm-res-compute-gallery-module-owners-bicep` `@Azure/avm-res-compute-gallery-module-contributors-bicep`
53	avm/res/compute/image	`46d3xbcp.res.compute-image`	`@Azure/avm-res-compute-image-module-owners-bicep` `@Azure/avm-res-compute-image-module-contributors-bicep`
54	avm/res/compute/proximity-placement-group	`46d3xbcp.res.compute-proximityplacementgroup`	`@Azure/avm-res-compute-proximityplacementgroup-module-owners-bicep` `@Azure/avm-res-compute-proximityplacementgroup-module-contributors-bicep`
55	avm/res/compute/ssh-public-key	`46d3xbcp.res.compute-sshpublickey`	`@Azure/avm-res-compute-sshpublickey-module-owners-bicep` `@Azure/avm-res-compute-sshpublickey-module-contributors-bicep`
56	avm/res/compute/virtual-machine	`46d3xbcp.res.compute-virtualmachine`	`@Azure/avm-res-compute-virtualmachine-module-owners-bicep` `@Azure/avm-res-compute-virtualmachine-module-contributors-bicep`
57	avm/res/compute/virtual-machine-scale-set	`46d3xbcp.res.compute-virtualmachinescaleset`	`@Azure/avm-res-compute-virtualmachinescaleset-module-owners-bicep` `@Azure/avm-res-compute-virtualmachinescaleset-module-contributors-bicep`
58	avm/res/consumption/budget	`46d3xbcp.res.consumption-budget`	`@Azure/avm-res-consumption-budget-module-owners-bicep` `@Azure/avm-res-consumption-budget-module-contributors-bicep`
59	avm/res/container-instance/container-group	`46d3xbcp.res.containerinstance-containergroup`	`@Azure/avm-res-containerinstance-containergroup-module-owners-bicep` `@Azure/avm-res-containerinstance-containergroup-module-contributors-bicep`
60	avm/res/container-registry/registry	`46d3xbcp.res.containerregistry-registry`	`@Azure/avm-res-containerregistry-registry-module-owners-bicep` `@Azure/avm-res-containerregistry-registry-module-contributors-bicep`
61	avm/res/container-service/managed-cluster	`46d3xbcp.res.containerservice-managedcluster`	`@Azure/avm-res-containerservice-managedcluster-module-owners-bicep` `@Azure/avm-res-containerservice-managedcluster-module-contributors-bicep`
62	avm/res/dashboard/grafana	`46d3xbcp.res.dashboard-grafana`	`@Azure/avm-res-dashboard-grafana-module-owners-bicep` `@Azure/avm-res-dashboard-grafana-module-contributors-bicep`
63	avm/res/data-factory/factory	`46d3xbcp.res.datafactory-factory`	`@Azure/avm-res-datafactory-factory-module-owners-bicep` `@Azure/avm-res-datafactory-factory-module-contributors-bicep`
64	avm/res/data-protection/backup-vault	`46d3xbcp.res.dataprotection-backupvault`	`@Azure/avm-res-dataprotection-backupvault-module-owners-bicep` `@Azure/avm-res-dataprotection-backupvault-module-contributors-bicep`
65	avm/res/data-protection/resource-guard	`46d3xbcp.res.dataprotection-resourceguard`	`@Azure/avm-res-dataprotection-resourceguard-module-owners-bicep` `@Azure/avm-res-dataprotection-resourceguard-module-contributors-bicep`
66	avm/res/databricks/access-connector	`46d3xbcp.res.databricks-accessconnector`	`@Azure/avm-res-databricks-accessconnector-module-owners-bicep` `@Azure/avm-res-databricks-accessconnector-module-contributors-bicep`
67	avm/res/databricks/workspace	`46d3xbcp.res.databricks-workspace`	`@Azure/avm-res-databricks-workspace-module-owners-bicep` `@Azure/avm-res-databricks-workspace-module-contributors-bicep`
68	avm/res/db-for-my-sql/flexible-server	`46d3xbcp.res.dbformysql-flexibleserver`	`@Azure/avm-res-dbformysql-flexibleserver-module-owners-bicep` `@Azure/avm-res-dbformysql-flexibleserver-module-contributors-bicep`
69	avm/res/db-for-postgre-sql/flexible-server	`46d3xbcp.res.dbforpostgresql-flexibleserver`	`@Azure/avm-res-dbforpostgresql-flexibleserver-module-owners-bicep` `@Azure/avm-res-dbforpostgresql-flexibleserver-module-contributors-bicep`
70	avm/res/desktop-virtualization/application-group	`46d3xbcp.res.desktopvirtualization-appgroup`	`@Azure/avm-res-desktopvirtualization-applicationgroup-module-owners-bicep` `@Azure/avm-res-desktopvirtualization-applicationgroup-module-contributors-bicep`
71	avm/res/desktop-virtualization/host-pool	`46d3xbcp.res.desktopvirtualization-hostpool`	`@Azure/avm-res-desktopvirtualization-hostpool-module-owners-bicep` `@Azure/avm-res-desktopvirtualization-hostpool-module-contributors-bicep`
72	avm/res/desktop-virtualization/scaling-plan	`46d3xbcp.res.desktopvirtualization-scalingplan`	`@Azure/avm-res-desktopvirtualization-scalingplan-module-owners-bicep` `@Azure/avm-res-desktopvirtualization-scalingplan-module-contributors-bicep`
73	avm/res/desktop-virtualization/workspace	`46d3xbcp.res.desktopvirtualization-workspace`	`@Azure/avm-res-desktopvirtualization-workspace-module-owners-bicep` `@Azure/avm-res-desktopvirtualization-workspace-module-contributors-bicep`
74	avm/res/dev-center/devcenter	`46d3xbcp.res.devcenter-devcenter`	`@Azure/avm-res-devcenter-devcenter-module-owners-bicep` `@Azure/avm-res-devcenter-devcenter-module-contributors-bicep`
75	avm/res/dev-center/network-connection	`46d3xbcp.res.devcenter-networkconnection`	`@Azure/avm-res-devcenter-networkconnection-module-owners-bicep` `@Azure/avm-res-devcenter-networkconnection-module-contributors-bicep`
76	avm/res/dev-center/project	`46d3xbcp.res.devcenter-project`	`@Azure/avm-res-devcenter-project-module-owners-bicep` `@Azure/avm-res-devcenter-project-module-contributors-bicep`
77	avm/res/dev-ops-infrastructure/pool	`46d3xbcp.res.devopsinfrastructure-pool`	`@Azure/avm-res-devopsinfrastructure-pool-module-owners-bicep` `@Azure/avm-res-devopsinfrastructure-pool-module-contributors-bicep`
78	avm/res/dev-test-lab/lab	`46d3xbcp.res.devtestlab-lab`	`@Azure/avm-res-devtestlab-lab-module-owners-bicep` `@Azure/avm-res-devtestlab-lab-module-contributors-bicep`
79	avm/res/digital-twins/digital-twins-instance	`46d3xbcp.res.digitaltwins-digitaltwinsinstance`	`@Azure/avm-res-digitaltwins-digitaltwinsinstance-module-owners-bicep` `@Azure/avm-res-digitaltwins-digitaltwinsinstance-module-contributors-bicep`
80	avm/res/document-db/database-account	`46d3xbcp.res.documentdb-databaseaccount`	`@Azure/avm-res-documentdb-databaseaccount-module-owners-bicep` `@Azure/avm-res-documentdb-databaseaccount-module-contributors-bicep`
81	avm/res/document-db/database-account/sql-role	`46d3xbcp.res.doctdb-dbacct-sqlrole`	`@Azure/avm-res-documentdb-databaseaccount-module-owners-bicep` `@Azure/avm-res-documentdb-databaseaccount-module-contributors-bicep`
82	avm/res/document-db/mongo-cluster	`46d3xbcp.res.documentdb-mongocluster`	`@Azure/avm-res-documentdb-mongocluster-module-owners-bicep` `@Azure/avm-res-documentdb-mongocluster-module-contributors-bicep`
83	avm/res/elastic-san/elastic-san	`46d3xbcp.res.elasticsan-elasticsan`	`@Azure/avm-res-elasticsan-elasticsan-module-owners-bicep` `@Azure/avm-res-elasticsan-elasticsan-module-contributors-bicep`
84	avm/res/event-grid/domain	`46d3xbcp.res.eventgrid-domain`	`@Azure/avm-res-eventgrid-domain-module-owners-bicep` `@Azure/avm-res-eventgrid-domain-module-contributors-bicep`
85	avm/res/event-grid/namespace	`46d3xbcp.res.eventgrid-namespace`	`@Azure/avm-res-eventgrid-namespace-module-owners-bicep` `@Azure/avm-res-eventgrid-namespace-module-contributors-bicep`
86	avm/res/event-grid/system-topic	`46d3xbcp.res.eventgrid-systemtopic`	`@Azure/avm-res-eventgrid-systemtopic-module-owners-bicep` `@Azure/avm-res-eventgrid-systemtopic-module-contributors-bicep`
87	avm/res/event-grid/topic	`46d3xbcp.res.eventgrid-topic`	`@Azure/avm-res-eventgrid-topic-module-owners-bicep` `@Azure/avm-res-eventgrid-topic-module-contributors-bicep`
88	avm/res/event-hub/namespace	`46d3xbcp.res.eventhub-namespace`	`@Azure/avm-res-eventhub-namespace-module-owners-bicep` `@Azure/avm-res-eventhub-namespace-module-contributors-bicep`
89	avm/res/event-hub/namespace/event-hub	`46d3xbcp.res.eventhub-nseventhub`	`@Azure/avm-res-eventhub-namespace-module-owners-bicep` `@Azure/avm-res-eventhub-namespace-module-contributors-bicep`
90	avm/res/fabric/capacity	`46d3xbcp.res.fabric-capacity`	`@Azure/avm-res-fabric-capacity-module-owners-bicep` `@Azure/avm-res-fabric-capacity-module-contributors-bicep`
91	avm/res/health-bot/health-bot	`46d3xbcp.res.healthbot-healthbot`	`@Azure/avm-res-healthbot-healthbot-module-owners-bicep` `@Azure/avm-res-healthbot-healthbot-module-contributors-bicep`
92	avm/res/healthcare-apis/workspace	`46d3xbcp.res.healthcareapis-workspace`	`@Azure/avm-res-healthcareapis-workspace-module-owners-bicep` `@Azure/avm-res-healthcareapis-workspace-module-contributors-bicep`
93	avm/res/hybrid-compute/gateway	`46d3xbcp.res.hybridcompute-gateway`	`@Azure/avm-res-hybridcompute-gateway-module-owners-bicep` `@Azure/avm-res-hybridcompute-gateway-module-contributors-bicep`
94	avm/res/hybrid-compute/license	`46d3xbcp.res.hybridcompute-license`	`@Azure/avm-res-hybridcompute-license-module-owners-bicep` `@Azure/avm-res-hybridcompute-license-module-contributors-bicep`
95	avm/res/hybrid-compute/machine	`46d3xbcp.res.hybridcompute-machine`	`@Azure/avm-res-hybridcompute-machine-module-owners-bicep` `@Azure/avm-res-hybridcompute-machine-module-contributors-bicep`
96	avm/res/hybrid-compute/private-link-scope	`46d3xbcp.res.hybridcompute-privatelinkscope`	`@Azure/avm-res-hybridcompute-privatelinkscope-module-owners-bicep` `@Azure/avm-res-hybridcompute-privatelinkscope-module-contributors-bicep`
97	avm/res/hybrid-compute/setting	`46d3xbcp.res.hybridcompute-setting`	`@Azure/avm-res-hybridcompute-setting-module-owners-bicep` `@Azure/avm-res-hybridcompute-setting-module-contributors-bicep`
98	avm/res/hybrid-container-service/provisioned-cluster-instance	`46d3xbcp.res.hybcontsvc-provclustinst`	`@Azure/avm-res-hybridcontainerservice-provisionedclusterinstance-module-owners-bicep` `@Azure/avm-res-hybridcontainerservice-provisionedclusterinstance-module-contributors-bicep`
99	avm/res/insights/action-group	`46d3xbcp.res.insights-actiongroup`	`@Azure/avm-res-insights-actiongroup-module-owners-bicep` `@Azure/avm-res-insights-actiongroup-module-contributors-bicep`
100	avm/res/insights/activity-log-alert	`46d3xbcp.res.insights-activitylogalert`	`@Azure/avm-res-insights-activitylogalert-module-owners-bicep` `@Azure/avm-res-insights-activitylogalert-module-contributors-bicep`
101	avm/res/insights/autoscale-setting	`46d3xbcp.res.insights-autoscalesetting`	`@Azure/avm-res-insights-autoscalesetting-module-owners-bicep` `@Azure/avm-res-insights-autoscalesetting-module-contributors-bicep`
102	avm/res/insights/component	`46d3xbcp.res.insights-component`	`@Azure/avm-res-insights-component-module-owners-bicep` `@Azure/avm-res-insights-component-module-contributors-bicep`
103	avm/res/insights/data-collection-endpoint	`46d3xbcp.res.insights-datacollectionendpoint`	`@Azure/avm-res-insights-datacollectionendpoint-module-owners-bicep` `@Azure/avm-res-insights-datacollectionendpoint-module-contributors-bicep`
104	avm/res/insights/data-collection-rule	`46d3xbcp.res.insights-datacollectionrule`	`@Azure/avm-res-insights-datacollectionrule-module-owners-bicep` `@Azure/avm-res-insights-datacollectionrule-module-contributors-bicep`
105	avm/res/insights/diagnostic-setting	`46d3xbcp.res.insights-diagnosticsetting`	`@Azure/avm-res-insights-diagnosticsetting-module-owners-bicep` `@Azure/avm-res-insights-diagnosticsetting-module-contributors-bicep`
106	avm/res/insights/metric-alert	`46d3xbcp.res.insights-metricalert`	`@Azure/avm-res-insights-metricalert-module-owners-bicep` `@Azure/avm-res-insights-metricalert-module-contributors-bicep`
107	avm/res/insights/private-link-scope	`46d3xbcp.res.insights-privatelinkscope`	`@Azure/avm-res-insights-privatelinkscope-module-owners-bicep` `@Azure/avm-res-insights-privatelinkscope-module-contributors-bicep`
108	avm/res/insights/scheduled-query-rule	`46d3xbcp.res.insights-scheduledqueryrule`	`@Azure/avm-res-insights-scheduledqueryrule-module-owners-bicep` `@Azure/avm-res-insights-scheduledqueryrule-module-contributors-bicep`
109	avm/res/insights/webtest	`46d3xbcp.res.insights-webtest`	`@Azure/avm-res-insights-webtest-module-owners-bicep` `@Azure/avm-res-insights-webtest-module-contributors-bicep`
110	avm/res/iot-operations/instance	`46d3xbcp.res.iotoperations-instance`	`@Azure/avm-res-iotoperations-instance-module-owners-bicep` `@Azure/avm-res-iotoperations-instance-module-contributors-bicep`
111	avm/res/key-vault/vault	`46d3xbcp.res.keyvault-vault`	`@Azure/avm-res-keyvault-vault-module-owners-bicep` `@Azure/avm-res-keyvault-vault-module-contributors-bicep`
112	avm/res/key-vault/vault/access-policy	`46d3xbcp.res.keyvault-accesspolicy`	`@Azure/avm-res-keyvault-vault-module-owners-bicep` `@Azure/avm-res-keyvault-vault-module-contributors-bicep`
113	avm/res/key-vault/vault/key	`46d3xbcp.res.keyvault-key`	`@Azure/avm-res-keyvault-vault-module-owners-bicep` `@Azure/avm-res-keyvault-vault-module-contributors-bicep`
114	avm/res/key-vault/vault/secret	`46d3xbcp.res.keyvault-secret`	`@Azure/avm-res-keyvault-vault-module-owners-bicep` `@Azure/avm-res-keyvault-vault-module-contributors-bicep`
115	avm/res/kubernetes-configuration/extension	`46d3xbcp.res.kubernetesconfiguration-extension`	`@Azure/avm-res-kubernetesconfiguration-extension-module-owners-bicep` `@Azure/avm-res-kubernetesconfiguration-extension-module-contributors-bicep`
116	avm/res/kubernetes-configuration/flux-configuration	`46d3xbcp.res.kubernetesconfiguration-fluxconfig`	`@Azure/avm-res-kubernetesconfiguration-fluxconfiguration-module-owners-bicep` `@Azure/avm-res-kubernetesconfiguration-fluxconfiguration-module-contributors-bicep`
117	avm/res/kubernetes/connected-cluster	`46d3xbcp.res.kubernetes-connectedcluster`	`@Azure/avm-res-kubernetes-connectedcluster-module-owners-bicep` `@Azure/avm-res-kubernetes-connectedcluster-module-contributors-bicep`
118	avm/res/kusto/cluster	`46d3xbcp.res.kusto-cluster`	`@Azure/avm-res-kusto-cluster-module-owners-bicep` `@Azure/avm-res-kusto-cluster-module-contributors-bicep`
119	avm/res/load-test-service/load-test	`46d3xbcp.res.loadtestservice-loadtest`	`@Azure/avm-res-loadtestservice-loadtest-module-owners-bicep` `@Azure/avm-res-loadtestservice-loadtest-module-contributors-bicep`
120	avm/res/logic/integration-account	`46d3xbcp.res.logic-integrationaccount`	`@Azure/avm-res-logic-integrationaccount-module-owners-bicep` `@Azure/avm-res-logic-integrationaccount-module-contributors-bicep`
121	avm/res/logic/workflow	`46d3xbcp.res.logic-workflow`	`@Azure/avm-res-logic-workflow-module-owners-bicep` `@Azure/avm-res-logic-workflow-module-contributors-bicep`
122	avm/res/machine-learning-services/registry	`46d3xbcp.res.machinelearningservices-registry`	`@Azure/avm-res-machinelearningservices-registry-module-owners-bicep` `@Azure/avm-res-machinelearningservices-registry-module-contributors-bicep`
123	avm/res/machine-learning-services/workspace	`46d3xbcp.res.machinelearningservices-workspace`	`@Azure/avm-res-machinelearningservices-workspace-module-owners-bicep` `@Azure/avm-res-machinelearningservices-workspace-module-contributors-bicep`
124	avm/res/maintenance/configuration-assignment	`46d3xbcp.res.maintenance-configurationassignment`	`@Azure/avm-res-maintenance-configurationassignment-module-owners-bicep` `@Azure/avm-res-maintenance-configurationassignment-module-contributors-bicep`
125	avm/res/maintenance/maintenance-configuration	`46d3xbcp.res.maintenance-maintenanceconfiguration`	`@Azure/avm-res-maintenance-maintenanceconfiguration-module-owners-bicep` `@Azure/avm-res-maintenance-maintenanceconfiguration-module-contributors-bicep`
126	avm/res/managed-identity/user-assigned-identity	`46d3xbcp.res.managedidentity-userassignedidentity`	`@Azure/avm-res-managedidentity-userassignedidentity-module-owners-bicep` `@Azure/avm-res-managedidentity-userassignedidentity-module-contributors-bicep`
127	avm/res/managed-services/registration-definition	`46d3xbcp.res.managedservices-registrationdef`	`@Azure/avm-res-managedservices-registrationdefinition-module-owners-bicep` `@Azure/avm-res-managedservices-registrationdefinition-module-contributors-bicep`
128	avm/res/management/management-group	`46d3xbcp.res.management-managementgroup`	`@Azure/avm-res-management-managementgroup-module-owners-bicep` `@Azure/avm-res-management-managementgroup-module-contributors-bicep`
129	avm/res/maps/account	`46d3xbcp.res.maps-account`	`@Azure/avm-res-maps-account-module-owners-bicep` `@Azure/avm-res-maps-account-module-contributors-bicep`
130	avm/res/net-app/net-app-account	`46d3xbcp.res.netapp-netappaccount`	`@Azure/avm-res-netapp-netappaccount-module-owners-bicep` `@Azure/avm-res-netapp-netappaccount-module-contributors-bicep`
131	avm/res/network/application-gateway	`46d3xbcp.res.network-appgw`	`@Azure/avm-res-network-applicationgateway-module-owners-bicep` `@Azure/avm-res-network-applicationgateway-module-contributors-bicep`
132	avm/res/network/application-gateway-web-application-firewall-policy	`46d3xbcp.res.network-appgwwebappfirewallpolicy`	`@Azure/avm-res-network-applicationgatewaywebapplicationfirewallpolicy-module-owners-bicep` `@Azure/avm-res-network-applicationgatewaywebapplicationfirewallpolicy-module-contributors-bicep`
133	avm/res/network/application-security-group	`46d3xbcp.res.network-applicationsecuritygroup`	`@Azure/avm-res-network-applicationsecuritygroup-module-owners-bicep` `@Azure/avm-res-network-applicationsecuritygroup-module-contributors-bicep`
134	avm/res/network/azure-firewall	`46d3xbcp.res.network-azurefirewall`	`@Azure/avm-res-network-azurefirewall-module-owners-bicep` `@Azure/avm-res-network-azurefirewall-module-contributors-bicep`
135	avm/res/network/bastion-host	`46d3xbcp.res.network-bastionhost`	`@Azure/avm-res-network-bastionhost-module-owners-bicep` `@Azure/avm-res-network-bastionhost-module-contributors-bicep`
136	avm/res/network/connection	`46d3xbcp.res.network-connection`	`@Azure/avm-res-network-connection-module-owners-bicep` `@Azure/avm-res-network-connection-module-contributors-bicep`
137	avm/res/network/ddos-protection-plan	`46d3xbcp.res.network-ddosprotectionplan`	`@Azure/avm-res-network-ddosprotectionplan-module-owners-bicep` `@Azure/avm-res-network-ddosprotectionplan-module-contributors-bicep`
138	avm/res/network/dns-forwarding-ruleset	`46d3xbcp.res.network-dnsforwardingruleset`	`@Azure/avm-res-network-dnsforwardingruleset-module-owners-bicep` `@Azure/avm-res-network-dnsforwardingruleset-module-contributors-bicep`
139	avm/res/network/dns-resolver	`46d3xbcp.res.network-dnsresolver`	`@Azure/avm-res-network-dnsresolver-module-owners-bicep` `@Azure/avm-res-network-dnsresolver-module-contributors-bicep`
140	avm/res/network/dns-zone	`46d3xbcp.res.network-dnszone`	`@Azure/avm-res-network-dnszone-module-owners-bicep` `@Azure/avm-res-network-dnszone-module-contributors-bicep`
141	avm/res/network/express-route-circuit	`46d3xbcp.res.network-expressroutecircuit`	`@Azure/avm-res-network-expressroutecircuit-module-owners-bicep` `@Azure/avm-res-network-expressroutecircuit-module-contributors-bicep`
142	avm/res/network/express-route-gateway	`46d3xbcp.res.network-expressroutegateway`	`@Azure/avm-res-network-expressroutegateway-module-owners-bicep` `@Azure/avm-res-network-expressroutegateway-module-contributors-bicep`
143	avm/res/network/express-route-port	`46d3xbcp.res.network-expressrouteport`	`@Azure/avm-res-network-expressrouteport-module-owners-bicep` `@Azure/avm-res-network-expressrouteport-module-contributors-bicep`
144	avm/res/network/firewall-policy	`46d3xbcp.res.network-firewallpolicy`	`@Azure/avm-res-network-firewallpolicy-module-owners-bicep` `@Azure/avm-res-network-firewallpolicy-module-contributors-bicep`
145	avm/res/network/front-door	`46d3xbcp.res.network-frontdoor`	`@Azure/avm-res-network-frontdoor-module-owners-bicep` `@Azure/avm-res-network-frontdoor-module-contributors-bicep`
146	avm/res/network/front-door-web-application-firewall-policy	`46d3xbcp.res.network-frontdoorwebappfwpolicy`	`@Azure/avm-res-network-frontdoorwebapplicationfirewallpolicy-module-owners-bicep` `@Azure/avm-res-network-frontdoorwebapplicationfirewallpolicy-module-contributors-bicep`
147	avm/res/network/ip-group	`46d3xbcp.res.network-ipgroup`	`@Azure/avm-res-network-ipgroup-module-owners-bicep` `@Azure/avm-res-network-ipgroup-module-contributors-bicep`
148	avm/res/network/load-balancer	`46d3xbcp.res.network-loadbalancer`	`@Azure/avm-res-network-loadbalancer-module-owners-bicep` `@Azure/avm-res-network-loadbalancer-module-contributors-bicep`
149	avm/res/network/local-network-gateway	`46d3xbcp.res.network-localnetworkgateway`	`@Azure/avm-res-network-localnetworkgateway-module-owners-bicep` `@Azure/avm-res-network-localnetworkgateway-module-contributors-bicep`
150	avm/res/network/nat-gateway	`46d3xbcp.res.network-natgateway`	`@Azure/avm-res-network-natgateway-module-owners-bicep` `@Azure/avm-res-network-natgateway-module-contributors-bicep`
151	avm/res/network/network-interface	`46d3xbcp.res.network-networkinterface`	`@Azure/avm-res-network-networkinterface-module-owners-bicep` `@Azure/avm-res-network-networkinterface-module-contributors-bicep`
152	avm/res/network/network-manager	`46d3xbcp.res.network-networkmanager`	`@Azure/avm-res-network-networkmanager-module-owners-bicep` `@Azure/avm-res-network-networkmanager-module-contributors-bicep`
153	avm/res/network/network-security-group	`46d3xbcp.res.network-networksecuritygroup`	`@Azure/avm-res-network-networksecuritygroup-module-owners-bicep` `@Azure/avm-res-network-networksecuritygroup-module-contributors-bicep`
154	avm/res/network/network-security-perimeter	`46d3xbcp.res.network-nwsecurityperimeter`	`@Azure/avm-res-network-networksecurityperimeter-module-owners-bicep` `@Azure/avm-res-network-networksecurityperimeter-module-contributors-bicep`
155	avm/res/network/network-watcher	`46d3xbcp.res.network-networkwatcher`	`@Azure/avm-res-network-networkwatcher-module-owners-bicep` `@Azure/avm-res-network-networkwatcher-module-contributors-bicep`
156	avm/res/network/p2s-vpn-gateway	`46d3xbcp.res.network-p2svpngateway`	`@Azure/avm-res-network-p2svpngateway-module-owners-bicep` `@Azure/avm-res-network-p2svpngateway-module-contributors-bicep`
157	avm/res/network/private-dns-zone	`46d3xbcp.res.network-privatednszone`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
158	avm/res/network/private-dns-zone/a	`46d3xbcp.res.nw-privdnszonea`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
159	avm/res/network/private-dns-zone/aaaa	`46d3xbcp.res.nw-privdnszoneaaaa`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
160	avm/res/network/private-dns-zone/cname	`46d3xbcp.res.nw-privdnszonecname`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
161	avm/res/network/private-dns-zone/mx	`46d3xbcp.res.nw-privdnszonemx`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
162	avm/res/network/private-dns-zone/ptr	`46d3xbcp.res.nw-privdnszoneptr`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
163	avm/res/network/private-dns-zone/soa	`46d3xbcp.res.nw-privdnszonesoa`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
164	avm/res/network/private-dns-zone/srv	`46d3xbcp.res.nw-privdnszonesrv`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
165	avm/res/network/private-dns-zone/txt	`46d3xbcp.res.nw-privdnszonetxt`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
166	avm/res/network/private-dns-zone/virtual-network-link	`46d3xbcp.res.network-vnetlink`	`@Azure/avm-res-network-privatednszone-module-owners-bicep` `@Azure/avm-res-network-privatednszone-module-contributors-bicep`
167	avm/res/network/private-endpoint	`46d3xbcp.res.network-privateendpoint`	`@Azure/avm-res-network-privateendpoint-module-owners-bicep` `@Azure/avm-res-network-privateendpoint-module-contributors-bicep`
168	avm/res/network/private-link-service	`46d3xbcp.res.network-privatelinkservice`	`@Azure/avm-res-network-privatelinkservice-module-owners-bicep` `@Azure/avm-res-network-privatelinkservice-module-contributors-bicep`
169	avm/res/network/public-ip-address	`46d3xbcp.res.network-publicipaddress`	`@Azure/avm-res-network-publicipaddress-module-owners-bicep` `@Azure/avm-res-network-publicipaddress-module-contributors-bicep`
170	avm/res/network/public-ip-prefix	`46d3xbcp.res.network-publicipprefix`	`@Azure/avm-res-network-publicipprefix-module-owners-bicep` `@Azure/avm-res-network-publicipprefix-module-contributors-bicep`
171	avm/res/network/route-table	`46d3xbcp.res.network-routetable`	`@Azure/avm-res-network-routetable-module-owners-bicep` `@Azure/avm-res-network-routetable-module-contributors-bicep`
172	avm/res/network/service-endpoint-policy	`46d3xbcp.res.network-serviceendpointpolicy`	`@Azure/avm-res-network-serviceendpointpolicy-module-owners-bicep` `@Azure/avm-res-network-serviceendpointpolicy-module-contributors-bicep`
173	avm/res/network/trafficmanagerprofile	`46d3xbcp.res.network-trafficmanagerprofile`	`@Azure/avm-res-network-trafficmanagerprofile-module-owners-bicep` `@Azure/avm-res-network-trafficmanagerprofile-module-contributors-bicep`
174	avm/res/network/virtual-hub	`46d3xbcp.res.network-virtualhub`	`@Azure/avm-res-network-virtualhub-module-owners-bicep` `@Azure/avm-res-network-virtualhub-module-contributors-bicep`
175	avm/res/network/virtual-hub/route-map	`46d3xbcp.res.network-virtualhubroutemap`	`@Azure/avm-res-network-virtualhub-module-owners-bicep` `@Azure/avm-res-network-virtualhub-module-contributors-bicep`
176	avm/res/network/virtual-network	`46d3xbcp.res.network-virtualnetwork`	`@Azure/avm-res-network-virtualnetwork-module-owners-bicep` `@Azure/avm-res-network-virtualnetwork-module-contributors-bicep`
177	avm/res/network/virtual-network-gateway	`46d3xbcp.res.network-virtualnetworkgateway`	`@Azure/avm-res-network-virtualnetworkgateway-module-owners-bicep` `@Azure/avm-res-network-virtualnetworkgateway-module-contributors-bicep`
178	avm/res/network/virtual-network/subnet	`46d3xbcp.res.network-virtualnetworksubnet`	`@Azure/avm-res-network-virtualnetwork-module-owners-bicep` `@Azure/avm-res-network-virtualnetwork-module-contributors-bicep`
179	avm/res/network/virtual-wan	`46d3xbcp.res.network-virtualwan`	`@Azure/avm-res-network-virtualwan-module-owners-bicep` `@Azure/avm-res-network-virtualwan-module-contributors-bicep`
180	avm/res/network/vpn-gateway	`46d3xbcp.res.network-vpngateway`	`@Azure/avm-res-network-vpngateway-module-owners-bicep` `@Azure/avm-res-network-vpngateway-module-contributors-bicep`
181	avm/res/network/vpn-server-configuration	`46d3xbcp.res.network-vpnserverconfiguration`	`@Azure/avm-res-network-vpnserverconfiguration-module-owners-bicep` `@Azure/avm-res-network-vpnserverconfiguration-module-contributors-bicep`
182	avm/res/network/vpn-site	`46d3xbcp.res.network-vpnsite`	`@Azure/avm-res-network-vpnsite-module-owners-bicep` `@Azure/avm-res-network-vpnsite-module-contributors-bicep`
183	avm/res/operational-insights/cluster	`46d3xbcp.res.operationalinsights-cluster`	`@Azure/avm-res-operationalinsights-cluster-module-owners-bicep` `@Azure/avm-res-operationalinsights-cluster-module-contributors-bicep`
184	avm/res/operational-insights/workspace	`46d3xbcp.res.operationalinsights-workspace`	`@Azure/avm-res-operationalinsights-workspace-module-owners-bicep` `@Azure/avm-res-operationalinsights-workspace-module-contributors-bicep`
185	avm/res/operations-management/solution	`46d3xbcp.res.operationsmanagement-solution`	`@Azure/avm-res-operationsmanagement-solution-module-owners-bicep` `@Azure/avm-res-operationsmanagement-solution-module-contributors-bicep`
186	avm/res/portal/dashboard	`46d3xbcp.res.portal-dashboard`	`@Azure/avm-res-portal-dashboard-module-owners-bicep` `@Azure/avm-res-portal-dashboard-module-contributors-bicep`
187	avm/res/power-bi-dedicated/capacity	`46d3xbcp.res.powerbidedicated-capacity`	`@Azure/avm-res-powerbidedicated-capacity-module-owners-bicep` `@Azure/avm-res-powerbidedicated-capacity-module-contributors-bicep`
188	avm/res/purview/account	`46d3xbcp.res.purview-account`	`@Azure/avm-res-purview-account-module-owners-bicep` `@Azure/avm-res-purview-account-module-contributors-bicep`
189	avm/res/recovery-services/vault	`46d3xbcp.res.recoveryservices-vault`	`@Azure/avm-res-recoveryservices-vault-module-owners-bicep` `@Azure/avm-res-recoveryservices-vault-module-contributors-bicep`
190	avm/res/relay/namespace	`46d3xbcp.res.relay-namespace`	`@Azure/avm-res-relay-namespace-module-owners-bicep` `@Azure/avm-res-relay-namespace-module-contributors-bicep`
191	avm/res/resource-graph/query	`46d3xbcp.resourcegraph-query`	`@Azure/avm-res-resourcegraph-query-module-owners-bicep` `@Azure/avm-res-resourcegraph-query-module-contributors-bicep`
192	avm/res/resources/deployment-script	`46d3xbcp.res.resources-deploymentscript`	`@Azure/avm-res-resources-deploymentscript-module-owners-bicep` `@Azure/avm-res-resources-deploymentscript-module-contributors-bicep`
193	avm/res/resources/resource-group	`46d3xbcp.res.resources-resourcegroup`	`@Azure/avm-res-resources-resourcegroup-module-owners-bicep` `@Azure/avm-res-resources-resourcegroup-module-contributors-bicep`
194	avm/res/scom/managed-instance	`46d3xbcp.res.scom-managedinstance`	`@Azure/avm-res-scom-managedinstance-module-owners-bicep` `@Azure/avm-res-scom-managedinstance-module-contributors-bicep`
195	avm/res/search/search-service	`46d3xbcp.res.search-searchservice`	`@Azure/avm-res-search-searchservice-module-owners-bicep` `@Azure/avm-res-search-searchservice-module-contributors-bicep`
196	avm/res/security-insights/data-connector	`46d3xbcp.res.securityinsights-dataconnector`	`@Azure/avm-res-securityinsights-dataconnector-module-owners-bicep` `@Azure/avm-res-securityinsights-dataconnector-module-contributors-bicep`
197	avm/res/security-insights/onboarding-state	`46d3xbcp.res.securityinsights-onboardingstate`	`@Azure/avm-res-securityinsights-onboardingstate-module-owners-bicep` `@Azure/avm-res-securityinsights-onboardingstate-module-contributors-bicep`
198	avm/res/security-insights/setting	`46d3xbcp.res.securityinsights-setting`	`@Azure/avm-res-securityinsights-setting-module-owners-bicep` `@Azure/avm-res-securityinsights-setting-module-contributors-bicep`
199	avm/res/service-bus/namespace	`46d3xbcp.res.servicebus-namespace`	`@Azure/avm-res-servicebus-namespace-module-owners-bicep` `@Azure/avm-res-servicebus-namespace-module-contributors-bicep`
200	avm/res/service-fabric/cluster	`46d3xbcp.res.servicefabric-cluster`	`@Azure/avm-res-servicefabric-cluster-module-owners-bicep` `@Azure/avm-res-servicefabric-cluster-module-contributors-bicep`
201	avm/res/service-networking/traffic-controller	`46d3xbcp.res.servicenetworking-trafficcontroller`	`@Azure/avm-res-servicenetworking-trafficcontroller-module-owners-bicep` `@Azure/avm-res-servicenetworking-trafficcontroller-module-contributors-bicep`
202	avm/res/signal-r-service/signal-r	`46d3xbcp.res.signalrservice-signalr`	`@Azure/avm-res-signalrservice-signalr-module-owners-bicep` `@Azure/avm-res-signalrservice-signalr-module-contributors-bicep`
203	avm/res/signal-r-service/web-pub-sub	`46d3xbcp.res.signalrservice-webpubsub`	`@Azure/avm-res-signalrservice-webpubsub-module-owners-bicep` `@Azure/avm-res-signalrservice-webpubsub-module-contributors-bicep`
204	avm/res/sql-virtual-machine/sql-virtual-machine	`46d3xbcp.res.sqlvm-sqlvm`	`@Azure/avm-res-sqlvirtualmachine-sqlvirtualmachine-module-owners-bicep` `@Azure/avm-res-sqlvirtualmachine-sqlvirtualmachine-module-contributors-bicep`
205	avm/res/sql/instance-pool	`46d3xbcp.res.sql-instancepool`	`@Azure/avm-res-sql-instancepool-module-owners-bicep` `@Azure/avm-res-sql-instancepool-module-contributors-bicep`
206	avm/res/sql/managed-instance	`46d3xbcp.res.sql-managedinstance`	`@Azure/avm-res-sql-managedinstance-module-owners-bicep` `@Azure/avm-res-sql-managedinstance-module-contributors-bicep`
207	avm/res/sql/server	`46d3xbcp.res.sql-server`	`@Azure/avm-res-sql-server-module-owners-bicep` `@Azure/avm-res-sql-server-module-contributors-bicep`
208	avm/res/storage/storage-account	`46d3xbcp.res.storage-storageaccount`	`@Azure/avm-res-storage-storageaccount-module-owners-bicep` `@Azure/avm-res-storage-storageaccount-module-contributors-bicep`
209	avm/res/storage/storage-account/blob-service/container	`46d3xbcp.res.storage-blobcontainer`	`@Azure/avm-res-storage-storageaccount-module-owners-bicep` `@Azure/avm-res-storage-storageaccount-module-contributors-bicep`
210	avm/res/storage/storage-account/blob-service/container/immutability-policy	`46d3xbcp.res.storage-containerimmutpolicy`	`@Azure/avm-res-storage-storageaccount-module-owners-bicep` `@Azure/avm-res-storage-storageaccount-module-contributors-bicep`
211	avm/res/storage/storage-account/file-service/share	`46d3xbcp.res.storage-fileshare`	`@Azure/avm-res-storage-storageaccount-module-owners-bicep` `@Azure/avm-res-storage-storageaccount-module-contributors-bicep`
212	avm/res/storage/storage-account/local-user	`46d3xbcp.res.storage-localuser`	`@Azure/avm-res-storage-storageaccount-module-owners-bicep` `@Azure/avm-res-storage-storageaccount-module-contributors-bicep`
213	avm/res/storage/storage-account/management-policy	`46d3xbcp.res.storage-mgmtpolicy`	`@Azure/avm-res-storage-storageaccount-module-owners-bicep` `@Azure/avm-res-storage-storageaccount-module-contributors-bicep`
214	avm/res/storage/storage-account/queue-service/queue	`46d3xbcp.res.storage-queue`	`@Azure/avm-res-storage-storageaccount-module-owners-bicep` `@Azure/avm-res-storage-storageaccount-module-contributors-bicep`
215	avm/res/storage/storage-account/table-service/table	`46d3xbcp.res.storage-table`	`@Azure/avm-res-storage-storageaccount-module-owners-bicep` `@Azure/avm-res-storage-storageaccount-module-contributors-bicep`
216	avm/res/stream-analytics/streaming-job	`46d3xbcp.res.streamanalytics-streamingjob`	`@Azure/avm-res-streamanalytics-streamingjob-module-owners-bicep` `@Azure/avm-res-streamanalytics-streamingjob-module-contributors-bicep`
217	avm/res/synapse/private-link-hub	`46d3xbcp.res.synapse-privatelinkhub`	`@Azure/avm-res-synapse-privatelinkhub-module-owners-bicep` `@Azure/avm-res-synapse-privatelinkhub-module-contributors-bicep`
218	avm/res/synapse/workspace	`46d3xbcp.res.synapse-workspace`	`@Azure/avm-res-synapse-workspace-module-owners-bicep` `@Azure/avm-res-synapse-workspace-module-contributors-bicep`
219	avm/res/virtual-machine-images/image-template	`46d3xbcp.res.virtualmachineimages-imagetemplate`	`@Azure/avm-res-virtualmachineimages-imagetemplate-module-owners-bicep` `@Azure/avm-res-virtualmachineimages-imagetemplate-module-contributors-bicep`
220	avm/res/web/connection	`46d3xbcp.res.web-connection`	`@Azure/avm-res-web-connection-module-owners-bicep` `@Azure/avm-res-web-connection-module-contributors-bicep`
221	avm/res/web/hosting-environment	`46d3xbcp.res.web-hostingenvironment`	`@Azure/avm-res-web-hostingenvironment-module-owners-bicep` `@Azure/avm-res-web-hostingenvironment-module-contributors-bicep`
222	avm/res/web/serverfarm	`46d3xbcp.res.web-serverfarm`	`@Azure/avm-res-web-serverfarm-module-owners-bicep` `@Azure/avm-res-web-serverfarm-module-contributors-bicep`
223	avm/res/web/site	`46d3xbcp.res.web-site`	`@Azure/avm-res-web-site-module-owners-bicep` `@Azure/avm-res-web-site-module-contributors-bicep`
224	avm/res/web/site/config	`46d3xbcp.res.web-siteconfig`	`@Azure/avm-res-web-site-module-owners-bicep` `@Azure/avm-res-web-site-module-contributors-bicep`
225	avm/res/web/site/slot	`46d3xbcp.res.web-siteslot`	`@Azure/avm-res-web-site-module-owners-bicep` `@Azure/avm-res-web-site-module-contributors-bicep`
226	avm/res/web/static-site	`46d3xbcp.res.web-staticsite`	`@Azure/avm-res-web-staticsite-module-owners-bicep` `@Azure/avm-res-web-staticsite-module-contributors-bicep`

Bicep Pattern Modules

Module catalog

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Bicep	Pattern	36	33	69

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Info

This page contains various views of the module index (catalog) for Bicep Pattern Modules. To see these views, click on the expandable sections with the “➕” sign below.

To see the full, unfiltered, unformatted module index on GitHub, click here.
To download the source CSV file, click here.

Note

Published modules - 🟢 & 🟡

➕ Published Modules - Module names, status and owners

No.	Module Name	Display Name	Owner(s)
01	avm/ptn/aca-lza/hosting-environment	Azure Container Apps (ACA) LZA - Hosting Environment	kpantos Konstantinos Pantos
02	avm/ptn/ai-ml/ai-foundry	AI-ML - AI Foundry	mswantek68 Mike Swantek
03	avm/ptn/ai-platform/baseline	AI Platform - Baseline	cecheta Chinedum Echeta ross-p-smith Ross Smith
04	avm/ptn/alz/empty	Azure Landing Zones (ALZ) - Empty	jtracey93 Jack Tracey oZakari Zach Trocinski
05	avm/ptn/app-service-lza/hosting-environment	App Service LZA - Hosting Environment	MikeTB-Microsoft Michael Baker
06	avm/ptn/app/container-job-toolkit	Container Job Toolkit	ReneHezser Rene Hezser
07	avm/ptn/authorization/pim-role-assignment	Authorization - PIM Role Assignment	sebassem Seif Bassem
08	avm/ptn/authorization/policy-assignment	Authorization - Policy Assignment	arnoldna Nate Arnold
09	avm/ptn/authorization/policy-exemption	Authorization - Policy Exemption	oZakari Zach Trocinski
10	avm/ptn/authorization/resource-role-assignment	Authorization - Resource Role Assignment	peterbud Peter Budai
11	avm/ptn/authorization/role-assignment	Authorization - Role Assignment	jtracey93 Jack Tracey
12	avm/ptn/authorization/role-definition	Authorization - Role Definition	jtracey93 Jack Tracey
13	avm/ptn/azd/acr-container-app	AZD - ACR Container App Azure Developer CLI - ACR Container App	JeffreyCA Jeffrey Chen
14	avm/ptn/azd/aks	AZD - AKS Azure Developer CLI - Azure Kubernetes Services	JeffreyCA Jeffrey Chen
15	avm/ptn/azd/aks-automatic-cluster	AZD - AKS Automatic Cluster Azure Developer CLI - Azure Kubernetes Services Automatic Cluster	JeffreyCA Jeffrey Chen
16	avm/ptn/azd/apim-api	AZD - APIM API Azure Developer CLI - API Management	JeffreyCA Jeffrey Chen
17	avm/ptn/azd/container-app-upsert	AZD - Container App Upsert Azure Developer CLI - Container Apps Upsert	JeffreyCA Jeffrey Chen
18	avm/ptn/azd/container-apps-stack	AZD - Container Apps Stack Azure Developer CLI - Container Apps Stack	JeffreyCA Jeffrey Chen
19	avm/ptn/azd/insights-dashboard	AZD - Insights Dashboard Azure Developer CLI - Inishgts Dashboard	JeffreyCA Jeffrey Chen
20	avm/ptn/azd/monitoring	AZD - Monitoring Azure Developer CLI - Monitoring	JeffreyCA Jeffrey Chen
21	avm/ptn/data/private-analytical-workspace	Private Analytical Workspace Data Analytics, Data Lake, Databricks, Database	jbinko Jiri Binko
22	avm/ptn/deployment-script/import-image-to-acr	Deployment Script - Import Container Image to ACR	ReneHezser Rene Hezser
23	avm/ptn/dev-ops/cicd-agents-and-runners	Azure DevOps and GitHub CI/CD Agents and Runners	sebassem Seif Bassem
24	avm/ptn/finops-toolkit/finops-hub	FinOps Toolkit - FinOps Hub	arthurclares Arthur Clares
25	avm/ptn/lz/sub-vending	Landing Zone Subscription Vending	jtracey93 Jack Tracey sebassem Seif Bassem
26	avm/ptn/mgmt-groups/subscription-placement	Management Groups - Subscription Placement	oZakari Zach Trocinski
27	avm/ptn/network/hub-networking	Hub Networking	hundredacres Matt Schmitt
28	avm/ptn/network/private-link-private-dns-zones	Private Link Private DNS Zones	jtracey93 Jack Tracey
29	avm/ptn/policy-insights/remediation	Policy Insights Remediation	donk-msft Don Koning
30	avm/ptn/sa/content-processing	SA - Content Processing Solution Accelerator - Content Processing	brittneek Brittnee Keller
31	avm/ptn/sa/conversation-knowledge-mining	SA - Conversation knowledge mining Solution Accelerator - Conversation knowledge mining (CKM)	alguadam Alvaro Guadamillas Herranz
32	avm/ptn/sa/modernize-your-code	SA - Modernize your code Solution Accelerator - Modernize your code	sethsteenken Seth Steenken
33	avm/ptn/sa/multi-agent-custom-automation-engine	SA - Multi Agent Custom Automation Engine Solution Accelerator - Multi Agent Custom Automation Engine	alguadam Alvaro Guadamillas Herranz
34	avm/ptn/security/security-center	Azure Security Center (Defender for Cloud)	tony-box Tony Box
35	avm/ptn/subscription/service-health-alerts	Service Health Alerts	sebassem Seif Bassem
36	avm/ptn/virtual-machine-images/azure-image-builder	Custom Images using Azure Image Builder	AlexanderSehr Alexander Sehr

Proposed modules - ⚪

➕ Proposed Modules - Module names, status and owners

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/ai-ml/landing-zone	AI-ML - Landing Zone (LZ)		mbilalamjad Bilal Amjad
02	avm/ptn/alz/ama	Azure Landing Zones (ALZ) - Azure Monitoring Agent (AMA)		oZakari Zach Trocinski
03	avm/ptn/alz/decommissioned	Azure Landing Zones (ALZ) - Decommissioned		jtracey93 Jack Tracey oZakari Zach Trocinski
04	avm/ptn/alz/int-root	Azure Landing Zones (ALZ) - Intermediate Root		jtracey93 Jack Tracey oZakari Zach Trocinski
05	avm/ptn/alz/landing-zones	Azure Landing Zones (ALZ) - Landing Zones		jtracey93 Jack Tracey oZakari Zach Trocinski
06	avm/ptn/alz/landing-zones-corp	Azure Landing Zones (ALZ) - Landing Zones Corp		jtracey93 Jack Tracey oZakari Zach Trocinski
07	avm/ptn/alz/landing-zones-online	Azure Landing Zones (ALZ) - Landing Zones Online		jtracey93 Jack Tracey oZakari Zach Trocinski
08	avm/ptn/alz/platform	Azure Landing Zones (ALZ) - Platform		jtracey93 Jack Tracey oZakari Zach Trocinski
09	avm/ptn/alz/platform-connectivity	Azure Landing Zones (ALZ) - Platform Connectivity		jtracey93 Jack Tracey oZakari Zach Trocinski
10	avm/ptn/alz/platform-identity	Azure Landing Zones (ALZ) - Platform Identity		jtracey93 Jack Tracey oZakari Zach Trocinski
11	avm/ptn/alz/platform-management	Azure Landing Zones (ALZ) - Platform Management		jtracey93 Jack Tracey oZakari Zach Trocinski
12	avm/ptn/alz/sandbox	Azure Landing Zones (ALZ) - Sandbox		jtracey93 Jack Tracey oZakari Zach Trocinski
13	avm/ptn/app/cosmos-db-account-container-app	Cosmos DB Account - Container App		seesharprun Sidney Andrews
14	avm/ptn/app/iaas-vm-cosmosdb-tier4	Workload - IaaS VM Cosmos DB - Tier 4		mikestiers Mike Stiers
15	avm/ptn/app/mongodb-cluster-container-app	MongoDB Cluster - Container App		seesharprun Sidney Andrews
16	avm/ptn/app/paas-ase-cosmosdb-tier4	Workload - PaaS ASE Cosmos DB - Tier 4		mikestiers Mike Stiers
17	avm/ptn/avd-lza/insights	Azure Virtual Desktop (AVD) LZA - Insights
18	avm/ptn/avd-lza/management-plane	Azure Virtual Desktop (AVD) LZA - Management Plane
19	avm/ptn/avd-lza/networking	Azure Virtual Desktop (AVD) LZA - Networking
20	avm/ptn/avd-lza/session-hosts	Azure Virtual Desktop (AVD) LZA - Session Hosts
21	avm/ptn/deployment-script/create-kv-ssh-key-pair	Deployment Script - Create Key Vault SSH Key Pair		vlahane Vishal Lahane
22	avm/ptn/deployment-script/private	Deployment Script - Private Script		sebassem Seif Bassem
23	avm/ptn/dev-center/dev-box	Dev-Box		timfurnival-MSFT Tim Furnival
24	avm/ptn/lza-shared/data-services	LZA Shared - Data Services Landing Zone Accelerators - Shared - Data Services		kpantos Konstantinos Pantos
25	avm/ptn/maintenance/azure-update-manager	Azure Update Manager		akhilthomas011 Akhil Thomas
26	avm/ptn/monitoring/amba	Azure Monitor Baseline Alerts (AMBA)		arjenhuitema Arjen Huitema
27	avm/ptn/monitoring/amba-alz	Azure Monitor Baseline Alerts (AMBA) - ALZ		arjenhuitema Arjen Huitema
28	avm/ptn/network/virtual-wan	Virtual WAN vWAN		ericscheffler Eric Scheffler juancj Juan Jimenez
29	avm/ptn/network/vwan-connected-vnets	VNETs peered to Virtual WAN		juancj Juan Jimenez ericscheffler Eric Scheffler
30	avm/ptn/openai/cognitive-search	Corporate Line of Business (LoB) ChatBot		andbron Andrew Lambert
31	avm/ptn/openai/e2e-baseline	Azure OpenAI End-to-End Baseline Implementation		amillerb Alexandra Miller-Browne
32	avm/ptn/sa/chat-with-your-data	SA - Chat with your data Solution Accelerator - Chat with your data (CWYD)		aldunson Almicia Dunson
33	avm/ptn/security/sentinel	Sentinel		hundredacres Matt Schmitt
34	❌ None listed	❌ None listed	❌ None listed	❌ None listed

Deprecated modules - 🔴

➕ Deprecated Modules - Module names, status and owners

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/azd/ml-ai-environment	AZD - ML AI Environment Azure Developer CLI - Machine Learning AI Environment
02	avm/ptn/azd/ml-hub-dependencies	AZD - ML Hub Dependencies Azure Developer CLI - Machine Learning Hub Dependencies
03	avm/ptn/azd/ml-project	AZD - ML Project Azure Developer CLI - Machine Learning Project
04	❌ None listed	❌ None listed	❌ None listed	❌ None listed

All modules - 📇

➕ All Modules - Module names, status and owners

No.	Module Name	Display Name	Owner(s)
01	avm/ptn/aca-lza/hosting-environment	Azure Container Apps (ACA) LZA - Hosting Environment	kpantos Konstantinos Pantos
02	avm/ptn/ai-ml/ai-foundry	AI-ML - AI Foundry	mswantek68 Mike Swantek
03	avm/ptn/ai-ml/landing-zone	AI-ML - Landing Zone (LZ)	mbilalamjad Bilal Amjad
04	avm/ptn/ai-platform/baseline	AI Platform - Baseline	cecheta Chinedum Echeta ross-p-smith Ross Smith
05	avm/ptn/alz/ama	Azure Landing Zones (ALZ) - Azure Monitoring Agent (AMA)	oZakari Zach Trocinski
06	avm/ptn/alz/decommissioned	Azure Landing Zones (ALZ) - Decommissioned	jtracey93 Jack Tracey oZakari Zach Trocinski
07	avm/ptn/alz/empty	Azure Landing Zones (ALZ) - Empty	jtracey93 Jack Tracey oZakari Zach Trocinski
08	avm/ptn/alz/int-root	Azure Landing Zones (ALZ) - Intermediate Root	jtracey93 Jack Tracey oZakari Zach Trocinski
09	avm/ptn/alz/landing-zones	Azure Landing Zones (ALZ) - Landing Zones	jtracey93 Jack Tracey oZakari Zach Trocinski
10	avm/ptn/alz/landing-zones-corp	Azure Landing Zones (ALZ) - Landing Zones Corp	jtracey93 Jack Tracey oZakari Zach Trocinski
11	avm/ptn/alz/landing-zones-online	Azure Landing Zones (ALZ) - Landing Zones Online	jtracey93 Jack Tracey oZakari Zach Trocinski
12	avm/ptn/alz/platform	Azure Landing Zones (ALZ) - Platform	jtracey93 Jack Tracey oZakari Zach Trocinski
13	avm/ptn/alz/platform-connectivity	Azure Landing Zones (ALZ) - Platform Connectivity	jtracey93 Jack Tracey oZakari Zach Trocinski
14	avm/ptn/alz/platform-identity	Azure Landing Zones (ALZ) - Platform Identity	jtracey93 Jack Tracey oZakari Zach Trocinski
15	avm/ptn/alz/platform-management	Azure Landing Zones (ALZ) - Platform Management	jtracey93 Jack Tracey oZakari Zach Trocinski
16	avm/ptn/alz/sandbox	Azure Landing Zones (ALZ) - Sandbox	jtracey93 Jack Tracey oZakari Zach Trocinski
17	avm/ptn/app-service-lza/hosting-environment	App Service LZA - Hosting Environment	MikeTB-Microsoft Michael Baker
18	avm/ptn/app/container-job-toolkit	Container Job Toolkit	ReneHezser Rene Hezser
19	avm/ptn/app/cosmos-db-account-container-app	Cosmos DB Account - Container App	seesharprun Sidney Andrews
20	avm/ptn/app/iaas-vm-cosmosdb-tier4	Workload - IaaS VM Cosmos DB - Tier 4	mikestiers Mike Stiers
21	avm/ptn/app/mongodb-cluster-container-app	MongoDB Cluster - Container App	seesharprun Sidney Andrews
22	avm/ptn/app/paas-ase-cosmosdb-tier4	Workload - PaaS ASE Cosmos DB - Tier 4	mikestiers Mike Stiers
23	avm/ptn/authorization/pim-role-assignment	Authorization - PIM Role Assignment	sebassem Seif Bassem
24	avm/ptn/authorization/policy-assignment	Authorization - Policy Assignment	arnoldna Nate Arnold
25	avm/ptn/authorization/policy-exemption	Authorization - Policy Exemption	oZakari Zach Trocinski
26	avm/ptn/authorization/resource-role-assignment	Authorization - Resource Role Assignment	peterbud Peter Budai
27	avm/ptn/authorization/role-assignment	Authorization - Role Assignment	jtracey93 Jack Tracey
28	avm/ptn/authorization/role-definition	Authorization - Role Definition	jtracey93 Jack Tracey
29	avm/ptn/avd-lza/insights	Azure Virtual Desktop (AVD) LZA - Insights
30	avm/ptn/avd-lza/management-plane	Azure Virtual Desktop (AVD) LZA - Management Plane
31	avm/ptn/avd-lza/networking	Azure Virtual Desktop (AVD) LZA - Networking
32	avm/ptn/avd-lza/session-hosts	Azure Virtual Desktop (AVD) LZA - Session Hosts
33	avm/ptn/azd/acr-container-app	AZD - ACR Container App Azure Developer CLI - ACR Container App	JeffreyCA Jeffrey Chen
34	avm/ptn/azd/aks	AZD - AKS Azure Developer CLI - Azure Kubernetes Services	JeffreyCA Jeffrey Chen
35	avm/ptn/azd/aks-automatic-cluster	AZD - AKS Automatic Cluster Azure Developer CLI - Azure Kubernetes Services Automatic Cluster	JeffreyCA Jeffrey Chen
36	avm/ptn/azd/apim-api	AZD - APIM API Azure Developer CLI - API Management	JeffreyCA Jeffrey Chen
37	avm/ptn/azd/container-app-upsert	AZD - Container App Upsert Azure Developer CLI - Container Apps Upsert	JeffreyCA Jeffrey Chen
38	avm/ptn/azd/container-apps-stack	AZD - Container Apps Stack Azure Developer CLI - Container Apps Stack	JeffreyCA Jeffrey Chen
39	avm/ptn/azd/insights-dashboard	AZD - Insights Dashboard Azure Developer CLI - Inishgts Dashboard	JeffreyCA Jeffrey Chen
40	avm/ptn/azd/ml-ai-environment	AZD - ML AI Environment Azure Developer CLI - Machine Learning AI Environment
41	avm/ptn/azd/ml-hub-dependencies	AZD - ML Hub Dependencies Azure Developer CLI - Machine Learning Hub Dependencies
42	avm/ptn/azd/ml-project	AZD - ML Project Azure Developer CLI - Machine Learning Project
43	avm/ptn/azd/monitoring	AZD - Monitoring Azure Developer CLI - Monitoring	JeffreyCA Jeffrey Chen
44	avm/ptn/data/private-analytical-workspace	Private Analytical Workspace Data Analytics, Data Lake, Databricks, Database	jbinko Jiri Binko
45	avm/ptn/deployment-script/create-kv-ssh-key-pair	Deployment Script - Create Key Vault SSH Key Pair	vlahane Vishal Lahane
46	avm/ptn/deployment-script/import-image-to-acr	Deployment Script - Import Container Image to ACR	ReneHezser Rene Hezser
47	avm/ptn/deployment-script/private	Deployment Script - Private Script	sebassem Seif Bassem
48	avm/ptn/dev-center/dev-box	Dev-Box	timfurnival-MSFT Tim Furnival
49	avm/ptn/dev-ops/cicd-agents-and-runners	Azure DevOps and GitHub CI/CD Agents and Runners	sebassem Seif Bassem
50	avm/ptn/finops-toolkit/finops-hub	FinOps Toolkit - FinOps Hub	arthurclares Arthur Clares
51	avm/ptn/lz/sub-vending	Landing Zone Subscription Vending	jtracey93 Jack Tracey sebassem Seif Bassem
52	avm/ptn/lza-shared/data-services	LZA Shared - Data Services Landing Zone Accelerators - Shared - Data Services	kpantos Konstantinos Pantos
53	avm/ptn/maintenance/azure-update-manager	Azure Update Manager	akhilthomas011 Akhil Thomas
54	avm/ptn/mgmt-groups/subscription-placement	Management Groups - Subscription Placement	oZakari Zach Trocinski
55	avm/ptn/monitoring/amba	Azure Monitor Baseline Alerts (AMBA)	arjenhuitema Arjen Huitema
56	avm/ptn/monitoring/amba-alz	Azure Monitor Baseline Alerts (AMBA) - ALZ	arjenhuitema Arjen Huitema
57	avm/ptn/network/hub-networking	Hub Networking	hundredacres Matt Schmitt
58	avm/ptn/network/private-link-private-dns-zones	Private Link Private DNS Zones	jtracey93 Jack Tracey
59	avm/ptn/network/virtual-wan	Virtual WAN vWAN	ericscheffler Eric Scheffler juancj Juan Jimenez
60	avm/ptn/network/vwan-connected-vnets	VNETs peered to Virtual WAN	juancj Juan Jimenez ericscheffler Eric Scheffler
61	avm/ptn/openai/cognitive-search	Corporate Line of Business (LoB) ChatBot	andbron Andrew Lambert
62	avm/ptn/openai/e2e-baseline	Azure OpenAI End-to-End Baseline Implementation	amillerb Alexandra Miller-Browne
63	avm/ptn/policy-insights/remediation	Policy Insights Remediation	donk-msft Don Koning
64	avm/ptn/sa/chat-with-your-data	SA - Chat with your data Solution Accelerator - Chat with your data (CWYD)	aldunson Almicia Dunson
65	avm/ptn/sa/content-processing	SA - Content Processing Solution Accelerator - Content Processing	brittneek Brittnee Keller
66	avm/ptn/sa/conversation-knowledge-mining	SA - Conversation knowledge mining Solution Accelerator - Conversation knowledge mining (CKM)	alguadam Alvaro Guadamillas Herranz
67	avm/ptn/sa/modernize-your-code	SA - Modernize your code Solution Accelerator - Modernize your code	sethsteenken Seth Steenken
68	avm/ptn/sa/multi-agent-custom-automation-engine	SA - Multi Agent Custom Automation Engine Solution Accelerator - Multi Agent Custom Automation Engine	alguadam Alvaro Guadamillas Herranz
69	avm/ptn/security/security-center	Azure Security Center (Defender for Cloud)	tony-box Tony Box
70	avm/ptn/security/sentinel	Sentinel	hundredacres Matt Schmitt
71	avm/ptn/subscription/service-health-alerts	Service Health Alerts	sebassem Seif Bassem
72	avm/ptn/virtual-machine-images/azure-image-builder	Custom Images using Azure Image Builder	AlexanderSehr Alexander Sehr

Module Publication History - 📅

➕ Module Publication History - Module names, status and owners

Modules published in July 2025

No.	Module Name	Display Name	Owner(s)
01	avm/ptn/ai-ml/ai-foundry	AI-ML - AI Foundry	mswantek68 Mike Swantek
02	avm/ptn/sa/content-processing	SA - Content Processing Solution Accelerator - Content Processing	brittneek Brittnee Keller
03	avm/ptn/sa/modernize-your-code	SA - Modernize your code Solution Accelerator - Modernize your code	sethsteenken Seth Steenken

Modules published in June 2025

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/sa/multi-agent-custom-automation-engine	SA - Multi Agent Custom Automation Engine Solution Accelerator - Multi Agent Custom Automation Engine		alguadam Alvaro Guadamillas Herranz
02	avm/ptn/subscription/service-health-alerts	Service Health Alerts		sebassem Seif Bassem

Modules published in April 2025

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/alz/empty	Azure Landing Zones (ALZ) - Empty		jtracey93 Jack Tracey oZakari Zach Trocinski
02	avm/ptn/app-service-lza/hosting-environment	App Service LZA - Hosting Environment		MikeTB-Microsoft Michael Baker

Modules published in March 2025

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/sa/conversation-knowledge-mining	SA - Conversation knowledge mining Solution Accelerator - Conversation knowledge mining (CKM)		alguadam Alvaro Guadamillas Herranz

Modules published in February 2025

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/authorization/pim-role-assignment	Authorization - PIM Role Assignment		sebassem Seif Bassem
02	avm/ptn/mgmt-groups/subscription-placement	Management Groups - Subscription Placement		oZakari Zach Trocinski

Modules published in December 2024

No.	Module Name	Display Name	Owner(s)
01	avm/ptn/app/container-job-toolkit	Container Job Toolkit	ReneHezser Rene Hezser
02	avm/ptn/authorization/policy-exemption	Authorization - Policy Exemption	oZakari Zach Trocinski
03	avm/ptn/authorization/role-definition	Authorization - Role Definition	jtracey93 Jack Tracey
04	avm/ptn/azd/aks-automatic-cluster	AZD - AKS Automatic Cluster Azure Developer CLI - Azure Kubernetes Services Automatic Cluster	JeffreyCA Jeffrey Chen

Modules published in October 2024

No.	Module Name	Display Name	Owner(s)
01	avm/ptn/azd/acr-container-app	AZD - ACR Container App Azure Developer CLI - ACR Container App	JeffreyCA Jeffrey Chen
02	avm/ptn/azd/aks	AZD - AKS Azure Developer CLI - Azure Kubernetes Services	JeffreyCA Jeffrey Chen
03	avm/ptn/azd/container-app-upsert	AZD - Container App Upsert Azure Developer CLI - Container Apps Upsert	JeffreyCA Jeffrey Chen
04	avm/ptn/azd/container-apps-stack	AZD - Container Apps Stack Azure Developer CLI - Container Apps Stack	JeffreyCA Jeffrey Chen
05	avm/ptn/azd/ml-ai-environment	AZD - ML AI Environment Azure Developer CLI - Machine Learning AI Environment
06	avm/ptn/azd/ml-hub-dependencies	AZD - ML Hub Dependencies Azure Developer CLI - Machine Learning Hub Dependencies
07	avm/ptn/azd/ml-project	AZD - ML Project Azure Developer CLI - Machine Learning Project
08	avm/ptn/azd/monitoring	AZD - Monitoring Azure Developer CLI - Monitoring	JeffreyCA Jeffrey Chen
09	avm/ptn/data/private-analytical-workspace	Private Analytical Workspace Data Analytics, Data Lake, Databricks, Database	jbinko Jiri Binko

Modules published in September 2024

No.	Module Name	Display Name	Owner(s)
01	avm/ptn/azd/apim-api	AZD - APIM API Azure Developer CLI - API Management	JeffreyCA Jeffrey Chen
02	avm/ptn/azd/insights-dashboard	AZD - Insights Dashboard Azure Developer CLI - Inishgts Dashboard	JeffreyCA Jeffrey Chen
03	avm/ptn/dev-ops/cicd-agents-and-runners	Azure DevOps and GitHub CI/CD Agents and Runners	sebassem Seif Bassem
04	avm/ptn/network/hub-networking	Hub Networking	hundredacres Matt Schmitt
05	avm/ptn/virtual-machine-images/azure-image-builder	Custom Images using Azure Image Builder	AlexanderSehr Alexander Sehr

Modules published in August 2024

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/aca-lza/hosting-environment	Azure Container Apps (ACA) LZA - Hosting Environment		kpantos Konstantinos Pantos

Modules published in July 2024

No.	Module Name	Display Name	Owner(s)
01	avm/ptn/ai-platform/baseline	AI Platform - Baseline	cecheta Chinedum Echeta ross-p-smith Ross Smith
02	avm/ptn/deployment-script/import-image-to-acr	Deployment Script - Import Container Image to ACR	ReneHezser Rene Hezser
03	avm/ptn/network/private-link-private-dns-zones	Private Link Private DNS Zones	jtracey93 Jack Tracey

Modules published in June 2024

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/lz/sub-vending	Landing Zone Subscription Vending		jtracey93 Jack Tracey sebassem Seif Bassem

Modules published in May 2024

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/ptn/authorization/resource-role-assignment	Authorization - Resource Role Assignment		peterbud Peter Budai
02	avm/ptn/finops-toolkit/finops-hub	FinOps Toolkit - FinOps Hub		arthurclares Arthur Clares

Modules published in April 2024

No.	Module Name	Display Name	Owner(s)
01	avm/ptn/authorization/policy-assignment	Authorization - Policy Assignment	arnoldna Nate Arnold
02	avm/ptn/authorization/role-assignment	Authorization - Role Assignment	jtracey93 Jack Tracey
03	avm/ptn/policy-insights/remediation	Policy Insights Remediation	donk-msft Don Koning
04	avm/ptn/security/security-center	Azure Security Center (Defender for Cloud)	tony-box Tony Box

For Module Owners & Contributors

Note

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

➕ All Modules - Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

No.	Module Name	Telemetry ID prefix	GitHub Teams for Module Owners and Contributors
01	avm/ptn/aca-lza/hosting-environment	`46d3xbcp.ptn.acalza-hostingenvironment`	`@Azure/avm-ptn-acalza-hostingenvironment-module-owners-bicep` `@Azure/avm-ptn-acalza-hostingenvironment-module-contributors-bicep`
02	avm/ptn/ai-ml/ai-foundry	`46d3xbcp.ptn.aiml-aifoundry`	`@Azure/avm-ptn-aiml-aifoundry-module-owners-bicep` `@Azure/avm-ptn-aiml-aifoundry-module-contributors-bicep`
03	avm/ptn/ai-ml/landing-zone	`46d3xbcp.ptn.aiml-lz`	`@Azure/avm-ptn-aiml-landingzone-module-owners-bicep` `@Azure/avm-ptn-aiml-landingzone-module-contributors-bicep`
04	avm/ptn/ai-platform/baseline	`46d3xbcp.ptn.aiplatform-baseline`	`@Azure/avm-ptn-aiplatform-baseline-module-owners-bicep` `@Azure/avm-ptn-aiplatform-baseline-module-contributors-bicep`
05	avm/ptn/alz/ama	`46d3xbcp.ptn.alz-ama`	`@Azure/avm-ptn-alz-ama-module-owners-bicep` `@Azure/avm-ptn-alz-ama-module-contributors-bicep`
06	avm/ptn/alz/decommissioned	`46d3xbcp.ptn.alz-decommissioned`	`@Azure/avm-ptn-alz-decommissioned-module-owners-bicep` `@Azure/avm-ptn-alz-decommissioned-module-contributors-bicep`
07	avm/ptn/alz/empty	`46d3xbcp.ptn.alz-empty`	`@Azure/avm-ptn-alz-empty-module-owners-bicep` `@Azure/avm-ptn-alz-empty-module-contributors-bicep`
08	avm/ptn/alz/int-root	`46d3xbcp.ptn.int-root`	`@Azure/avm-ptn-alz-introot-module-owners-bicep` `@Azure/avm-ptn-alz-introot-module-contributors-bicep`
09	avm/ptn/alz/landing-zones	`46d3xbcp.ptn.alz-landingzones`	`@Azure/avm-ptn-alz-landingzones-module-owners-bicep` `@Azure/avm-ptn-alz-landingzones-module-contributors-bicep`
10	avm/ptn/alz/landing-zones-corp	`46d3xbcp.ptn.alz-landingzonescorp`	`@Azure/avm-ptn-alz-landingzonescorp-module-owners-bicep` `@Azure/avm-ptn-alz-landingzonescorp-module-contributors-bicep`
11	avm/ptn/alz/landing-zones-online	`46d3xbcp.ptn.alz-landingzonesonline`	`@Azure/avm-ptn-alz-landingzonesonline-module-owners-bicep` `@Azure/avm-ptn-alz-landingzonesonline-module-contributors-bicep`
12	avm/ptn/alz/platform	`46d3xbcp.ptn.alz-platform`	`@Azure/avm-ptn-alz-platform-module-owners-bicep` `@Azure/avm-ptn-alz-platform-module-contributors-bicep`
13	avm/ptn/alz/platform-connectivity	`46d3xbcp.ptn.alz-platformconnectivity`	`@Azure/avm-ptn-alz-platformconnectivity-module-owners-bicep` `@Azure/avm-ptn-alz-platformconnectivity-module-contributors-bicep`
14	avm/ptn/alz/platform-identity	`46d3xbcp.ptn.alz-platformidentity`	`@Azure/avm-ptn-alz-platformidentity-module-owners-bicep` `@Azure/avm-ptn-alz-platformidentity-module-contributors-bicep`
15	avm/ptn/alz/platform-management	`46d3xbcp.ptn.alz-platformmanagement`	`@Azure/avm-ptn-alz-platformmanagement-module-owners-bicep` `@Azure/avm-ptn-alz-platformmanagement-module-contributors-bicep`
16	avm/ptn/alz/sandbox	`46d3xbcp.ptn.alz-sandbox`	`@Azure/avm-ptn-alz-sandbox-module-owners-bicep` `@Azure/avm-ptn-alz-sandbox-module-contributors-bicep`
17	avm/ptn/app-service-lza/hosting-environment	`46d3xbcp.ptn.appsvclza-hostingenvironment`	`@Azure/avm-ptn-appservicelza-hostingenvironment-module-owners-bicep` `@Azure/avm-ptn-appservicelza-hostingenvironment-module-contributors-bicep`
18	avm/ptn/app/container-job-toolkit	`46d3xbcp.ptn.app-containerjobtoolkit`	`@Azure/avm-ptn-app-containerjobtoolkit-module-owners-bicep` `@Azure/avm-ptn-app-containerjobtoolkit-module-contributors-bicep`
19	avm/ptn/app/cosmos-db-account-container-app	`46d3xbcp.ptn.app-cosmosdbacctcontapp`	`@Azure/avm-ptn-app-cosmosdbaccountcontainerapp-module-owners-bicep` `@Azure/avm-ptn-app-cosmosdbaccountcontainerapp-module-contributors-bicep`
20	avm/ptn/app/iaas-vm-cosmosdb-tier4	`46d3xbcp.ptn.app-iaasvmcosmosdbt4`	`@Azure/avm-ptn-app-iaasvmcosmosdbtier4-module-owners-bicep` `@Azure/avm-ptn-app-iaasvmcosmosdbtier4-module-contributors-bicep`
21	avm/ptn/app/mongodb-cluster-container-app	`46d3xbcp.ptn.app-mongodbclustcontapp`	`@Azure/avm-ptn-app-mongodbclustercontainerapp-module-owners-bicep` `@Azure/avm-ptn-app-mongodbclustercontainerapp-module-contributors-bicep`
22	avm/ptn/app/paas-ase-cosmosdb-tier4	`46d3xbcp.ptn.app-paasasecosmosdbt4`	`@Azure/avm-ptn-app-paasasecosmosdbtier4-module-owners-bicep` `@Azure/avm-ptn-app-paasasecosmosdbtier4-module-contributors-bicep`
23	avm/ptn/authorization/pim-role-assignment	`46d3xbcp.ptn.authorization-pimroleassignment`	`@Azure/avm-ptn-authorization-pimroleassignment-module-owners-bicep` `@Azure/avm-ptn-authorization-pimroleassignment-module-contributors-bicep`
24	avm/ptn/authorization/policy-assignment	`46d3xbcp.ptn.authorization-policyassignment`	`@Azure/avm-ptn-authorization-policyassignment-module-owners-bicep` `@Azure/avm-ptn-authorization-policyassignment-module-contributors-bicep`
25	avm/ptn/authorization/policy-exemption	`46d3xbcp.ptn.authorization-policyexemption`	`@Azure/avm-ptn-authorization-policyexemption-module-owners-bicep` `@Azure/avm-ptn-authorization-policyexemption-module-contributors-bicep`
26	avm/ptn/authorization/resource-role-assignment	`46d3xbcp.ptn.authorization-resourceroleassignment`	`@Azure/avm-ptn-authorization-resourceroleassignment-module-owners-bicep` `@Azure/avm-ptn-authorization-resourceroleassignment-module-contributors-bicep`
27	avm/ptn/authorization/role-assignment	`46d3xbcp.ptn.authorization-roleassignment`	`@Azure/avm-ptn-authorization-roleassignment-module-owners-bicep` `@Azure/avm-ptn-authorization-roleassignment-module-contributors-bicep`
28	avm/ptn/authorization/role-definition	`46d3xbcp.ptn.authorization-roledefinition`	`@Azure/avm-ptn-authorization-roledefinition-module-owners-bicep` `@Azure/avm-ptn-authorization-roledefinition-module-contributors-bicep`
29	avm/ptn/avd-lza/insights	`46d3xbcp.ptn.avdlza-insights`	`@Azure/avm-ptn-avdlza-insights-module-owners-bicep` `@Azure/avm-ptn-avdlza-insights-module-contributors-bicep`
30	avm/ptn/avd-lza/management-plane	`46d3xbcp.ptn.avdlza-managementplane`	`@Azure/avm-ptn-avdlza-managementplane-module-owners-bicep` `@Azure/avm-ptn-avdlza-managementplane-module-contributors-bicep`
31	avm/ptn/avd-lza/networking	`46d3xbcp.ptn.avdlza-networking`	`@Azure/avm-ptn-avdlza-networking-module-owners-bicep` `@Azure/avm-ptn-avdlza-networking-module-contributors-bicep`
32	avm/ptn/avd-lza/session-hosts	`46d3xbcp.ptn.avdlza-sessionhosts`	`@Azure/avm-ptn-avdlza-sessionhosts-module-owners-bicep` `@Azure/avm-ptn-avdlza-sessionhosts-module-contributors-bicep`
33	avm/ptn/azd/acr-container-app	`46d3xbcp.ptn.azd-acrcontainerapp`	`@Azure/avm-ptn-azd-acrcontainerapp-module-owners-bicep` `@Azure/avm-ptn-azd-acrcontainerapp-module-contributors-bicep`
34	avm/ptn/azd/aks	`46d3xbcp.ptn.azd-aks`	`@Azure/avm-ptn-azd-aks-module-owners-bicep` `@Azure/avm-ptn-azd-aks-module-contributors-bicep`
35	avm/ptn/azd/aks-automatic-cluster	`46d3xbcp.ptn.azd-aksautomaticcluster`	`@Azure/avm-ptn-azd-aksautomaticcluster-module-owners-bicep` `@Azure/avm-ptn-azd-aksautomaticcluster-module-contributors-bicep`
36	avm/ptn/azd/apim-api	`46d3xbcp.ptn.azd-apimapi`	`@Azure/avm-ptn-azd-apimapi-module-owners-bicep` `@Azure/avm-ptn-azd-apimapi-module-contributors-bicep`
37	avm/ptn/azd/container-app-upsert	`46d3xbcp.ptn.azd-containerappupsert`	`@Azure/avm-ptn-azd-containerappupsert-module-owners-bicep` `@Azure/avm-ptn-azd-containerappupsert-module-contributors-bicep`
38	avm/ptn/azd/container-apps-stack	`46d3xbcp.ptn.azd-containerappsstack`	`@Azure/avm-ptn-azd-containerappsstack-module-owners-bicep` `@Azure/avm-ptn-azd-containerappsstack-module-contributors-bicep`
39	avm/ptn/azd/insights-dashboard	`46d3xbcp.ptn.azd-insightsdashboard`	`@Azure/avm-ptn-azd-insightsdashboard-module-owners-bicep` `@Azure/avm-ptn-azd-insightsdashboard-module-contributors-bicep`
40	avm/ptn/azd/ml-ai-environment	`46d3xbcp.ptn.azd-mlaienvironment`	`@Azure/avm-ptn-azd-mlaienvironment-module-owners-bicep` `@Azure/avm-ptn-azd-mlaienvironment-module-contributors-bicep`
41	avm/ptn/azd/ml-hub-dependencies	`46d3xbcp.ptn.azd-mlhubdependencies`	`@Azure/avm-ptn-azd-mlhubdependencies-module-owners-bicep` `@Azure/avm-ptn-azd-mlhubdependencies-module-contributors-bicep`
42	avm/ptn/azd/ml-project	`46d3xbcp.ptn.azd-mlproject`	`@Azure/avm-ptn-azd-mlproject-module-owners-bicep` `@Azure/avm-ptn-azd-mlproject-module-contributors-bicep`
43	avm/ptn/azd/monitoring	`46d3xbcp.ptn.azd-monitoring`	`@Azure/avm-ptn-azd-monitoring-module-owners-bicep` `@Azure/avm-ptn-azd-monitoring-module-contributors-bicep`
44	avm/ptn/data/private-analytical-workspace	`46d3xbcp.ptn.data-privateanalyticalworkspace`	`@Azure/avm-ptn-data-privateanalyticalworkspace-module-owners-bicep` `@Azure/avm-ptn-data-privateanalyticalworkspace-module-contributors-bicep`
45	avm/ptn/deployment-script/create-kv-ssh-key-pair	`46d3xbcp.ptn.deploymentscript-createkvsshkeypair`	`@Azure/avm-ptn-deploymentscript-createkvsshkeypair-module-owners-bicep` `@Azure/avm-ptn-deploymentscript-createkvsshkeypair-module-contributors-bicep`
46	avm/ptn/deployment-script/import-image-to-acr	`46d3xbcp.ptn.deploymentscript-importimagetoacr`	`@Azure/avm-ptn-deploymentscript-importimagetoacr-module-owners-bicep` `@Azure/avm-ptn-deploymentscript-importimagetoacr-module-contributors-bicep`
47	avm/ptn/deployment-script/private	`46d3xbcp.ptn.deploymentscript-private`	`@Azure/avm-ptn-deploymentscript-private-module-owners-bicep` `@Azure/avm-ptn-deploymentscript-private-module-contributors-bicep`
48	avm/ptn/dev-center/dev-box	`46d3xbcp.ptn.devcenter-devbox`	`@Azure/avm-ptn-devcenter-devbox-module-owners-bicep` `@Azure/avm-ptn-devcenter-devbox-module-contributors-bicep`
49	avm/ptn/dev-ops/cicd-agents-and-runners	`46d3xbcp.ptn.devops-cicdagentsandrunners`	`@Azure/avm-ptn-devops-cicdagentsandrunners-module-owners-bicep` `@Azure/avm-ptn-devops-cicdagentsandrunners-module-contributors-bicep`
50	avm/ptn/finops-toolkit/finops-hub	`46d3xbcp.ptn.finopstoolkit-finopshub`	`@Azure/avm-ptn-finopstoolkit-finopshub-module-owners-bicep` `@Azure/avm-ptn-finopstoolkit-finopshub-module-contributors-bicep`
51	avm/ptn/lz/sub-vending	`46d3xbcp.ptn.lz-subvending`	`@Azure/avm-ptn-lz-subvending-module-owners-bicep` `@Azure/avm-ptn-lz-subvending-module-contributors-bicep`
52	avm/ptn/lza-shared/data-services	`46d3xbcp.ptn.lzashared-dataservices`	`@Azure/avm-ptn-lzashared-dataservices-module-owners-bicep` `@Azure/avm-ptn-lzashared-dataservices-module-contributors-bicep`
53	avm/ptn/maintenance/azure-update-manager	`46d3xbcp.ptn.maintenance-azureupdatemanager`	`@Azure/avm-ptn-maintenance-azureupdatemanager-module-owners-bicep` `@Azure/avm-ptn-maintenance-azureupdatemanager-module-contributors-bicep`
54	avm/ptn/mgmt-groups/subscription-placement	`46d3xbcp.ptn.mgmtgroup-subplacement`	`@Azure/avm-ptn-mgmtgroups-subscriptionplacement-module-owners-bicep` `@Azure/avm-ptn-mgmtgroups-subscriptionplacement-module-contributors-bicep`
55	avm/ptn/monitoring/amba	`46d3xbcp.ptn.monitoring-amba`	`@Azure/avm-ptn-monitoring-amba-module-owners-bicep` `@Azure/avm-ptn-monitoring-amba-module-contributors-bicep`
56	avm/ptn/monitoring/amba-alz	`46d3xbcp.ptn.monitoring-ambaalz`	`@Azure/avm-ptn-monitoring-ambaalz-module-owners-bicep` `@Azure/avm-ptn-monitoring-ambaalz-module-contributors-bicep`
57	avm/ptn/network/hub-networking	`46d3xbcp.ptn.network-hubnetworking`	`@Azure/avm-ptn-network-hubnetworking-module-owners-bicep` `@Azure/avm-ptn-network-hubnetworking-module-contributors-bicep`
58	avm/ptn/network/private-link-private-dns-zones	`46d3xbcp.ptn.network-privatelinkprivatednszones`	`@Azure/avm-ptn-network-privatelinkprivatednszones-module-owners-bicep` `@Azure/avm-ptn-network-privatelinkprivatednszones-module-contributors-bicep`
59	avm/ptn/network/virtual-wan	`46d3xbcp.ptn.network-virtualwan`	`@Azure/avm-ptn-network-virtualwan-module-owners-bicep` `@Azure/avm-ptn-network-virtualwan-module-contributors-bicep`
60	avm/ptn/network/vwan-connected-vnets	`46d3xbcp.ptn.network-vwanconnectedvnets`	`@Azure/avm-ptn-network-vwanconnectedvnets-module-owners-bicep` `@Azure/avm-ptn-network-vwanconnectedvnets-module-contributors-bicep`
61	avm/ptn/openai/cognitive-search	`46d3xbcp.ptn.openai-cognitivesearch`	`@Azure/avm-ptn-openai-cognitivesearch-module-owners-bicep` `@Azure/avm-ptn-openai-cognitivesearch-module-contributors-bicep`
62	avm/ptn/openai/e2e-baseline	`46d3xbcp.ptn.openai-e2ebaseline`	`@Azure/avm-ptn-openai-e2ebaseline-module-owners-bicep` `@Azure/avm-ptn-openai-e2ebaseline-module-contributors-bicep`
63	avm/ptn/policy-insights/remediation	`46d3xbcp.ptn.policyinsights-remediation`	`@Azure/avm-ptn-policyinsights-remediation-module-owners-bicep` `@Azure/avm-ptn-policyinsights-remediation-module-contributors-bicep`
64	avm/ptn/sa/chat-with-your-data	`46d3xbcp.ptn.sa-chatwithyourdata`	`@Azure/avm-ptn-sa-chatwithyourdata-module-owners-bicep` `@Azure/avm-ptn-sa-chatwithyourdata-module-contributors-bicep`
65	avm/ptn/sa/content-processing	`46d3xbcp.ptn.sa-contentprocessing`	`@Azure/avm-ptn-sa-contentprocessing-module-owners-bicep` `@Azure/avm-ptn-sa-contentprocessing-module-contributors-bicep`
66	avm/ptn/sa/conversation-knowledge-mining	`46d3xbcp.ptn.sa-convknowledgemining`	`@Azure/avm-ptn-sa-conversationknowledgemining-module-owners-bicep` `@Azure/avm-ptn-sa-conversationknowledgemining-module-contributors-bicep`
67	avm/ptn/sa/modernize-your-code	`46d3xbcp.ptn.sa-modernizeyourcode`	`@Azure/avm-ptn-sa-modernizeyourcode-module-owners-bicep` `@Azure/avm-ptn-sa-modernizeyourcode-module-contributors-bicep`
68	avm/ptn/sa/multi-agent-custom-automation-engine	`46d3xbcp.ptn.sa-multiagentcustauteng`	`@Azure/avm-ptn-sa-multiagentcustomautomationengine-module-owners-bicep` `@Azure/avm-ptn-sa-multiagentcustomautomationengine-module-contributors-bicep`
69	avm/ptn/security/security-center	`46d3xbcp.ptn.security-securitycenter`	`@Azure/avm-ptn-security-securitycenter-module-owners-bicep` `@Azure/avm-ptn-security-securitycenter-module-contributors-bicep`
70	avm/ptn/security/sentinel	`46d3xbcp.ptn.security-sentinel`	`@Azure/avm-ptn-security-sentinel-module-owners-bicep` `@Azure/avm-ptn-security-sentinel-module-contributors-bicep`
71	avm/ptn/subscription/service-health-alerts	`46d3xbcp.ptn.subscription-svchealthalerts`	`@Azure/avm-ptn-subscription-servicehealthalerts-module-owners-bicep` `@Azure/avm-ptn-subscription-servicehealthalerts-module-contributors-bicep`
72	avm/ptn/virtual-machine-images/azure-image-builder	`46d3xbcp.ptn.vmimages-azureimagebuilder`	`@Azure/avm-ptn-virtualmachineimages-azureimagebuilder-module-owners-bicep` `@Azure/avm-ptn-virtualmachineimages-azureimagebuilder-module-contributors-bicep`

Bicep Utility Modules

Module catalog

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Bicep	Utility	1	1	2

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Info

This page contains various views of the module index (catalog) for Bicep Utility Modules. To see these views, click on the expandable sections with the “➕” sign below.

To see the full, unfiltered, unformatted module index on GitHub, click here.
To download the source CSV file, click here.

Note

Published modules - 🟢 & 🟡

➕ Published Modules - Module names, status and owners

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/utl/types/avm-common-types	AVM Common Types		AlexanderSehr Alexander Sehr

Proposed modules - ⚪

➕ Proposed Modules - Module names, status and owners

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/utl/general/get-environment	Get-Environment		alex-frankel Alex Frankel emilyredm Emily Redmond
02	❌ None listed	❌ None listed	❌ None listed	❌ None listed

Deprecated modules - 🔴

➕ Deprecated Modules - Module names, status and owners

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	❌ None listed	❌ None listed	❌ None listed	❌ None listed

All modules - 📇

➕ All Modules - Module names, status and owners

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/utl/general/get-environment	Get-Environment		alex-frankel Alex Frankel emilyredm Emily Redmond
02	avm/utl/types/avm-common-types	AVM Common Types		AlexanderSehr Alexander Sehr

Module Publication History - 📅

➕ Module Publication History - Module names, status and owners

Modules published in October 2024

No.	Module Name	Display Name	Status & Versions	Owner(s)
01	avm/utl/types/avm-common-types	AVM Common Types		AlexanderSehr Alexander Sehr

For Module Owners & Contributors

Note

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

➕ All Modules - Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

No.	Module Name	Telemetry ID prefix	GitHub Teams for Module Owners and Contributors
01	avm/utl/general/get-environment	`46d3xbcp.utl.general-getenvironment`	`@Azure/avm-utl-general-getenvironment-module-owners-bicep` `@Azure/avm-utl-general-getenvironment-module-contributors-bicep`
02	avm/utl/types/avm-common-types	`46d3xbcp.utl.types-avmcommontypes`	`@Azure/avm-utl-types-avmcommontypes-module-owners-bicep` `@Azure/avm-utl-types-avmcommontypes-module-contributors-bicep`

Terraform Modules

Summary

The following table shows the number of all available, orphaned and planned Terraform Modules.

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Terraform	Resource	92	49	141
	Pattern	23	17	40
	Utility	4	1	5

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Want to contribute to AVM Terraform modules?

#	Labels	Link and description
1.	Type: New Module Proposal 💡 Needs: Module Owner 📣 Language: Terraform 🌐	To become the owner of a new Terraform module, see all new Terraform modules looking for owners or check out the “Looking for owners” swimlane here.
2.	Status: Module Orphaned 🟡 Language: Terraform 🌐	To become the owner of an orphaned Terraform module, see all orphaned Terraform modules or check out the “Orphaned” swimlane here.
3.	Needs: Module Contributor 📣 Language: Terraform 🌐	To become a co-owner or contribute to a Terraform module, see all Terraform modules looking for contributors.

For more details on “What are the different ways to contribute to AVM?”, see here.

Terraform Resource Modules

Module catalog

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Terraform	Resource	92	49	141

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Info

This page contains various views of the module index (catalog) for Terraform Resource Modules. To see these views, click on the expandable sections with the “➕” sign below.

To see the full, unfiltered, unformatted module index on GitHub, click here.
To download the source CSV file, click here.

Note

Published modules - 🟢 & 🟡

➕ Published Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Primary Owner
01	avm-res-apimanagement-service	📄	API Management Service	swatilekhapaul Swatilekha Paul
02	avm-res-app-containerapp	📄	Container App	lonegunmanb Zijie He
03	avm-res-app-job	📄	App Job	sujaypillai Sujay Pillai
04	avm-res-app-managedenvironment	📄	App Managed Environment	segraef Sebastian Graef
05	avm-res-appconfiguration-configurationstore	📄	App Configuration Store	matt-FFFFFF Matt White
06	avm-res-authorization-roleassignment	📄	Role Assignment	jaredfholgate Jared Holgate
07	avm-res-automation-automationaccount	📄	Automation Account	didayal-msft Divyadeep Dayal Poven795909 Poornima Venkataramanan
08	avm-res-avs-privatecloud	📄	AVS Private Cloud	jchancellor-ms Jon Chancellor
09	avm-res-azurestackhci-cluster	📄	Azure Stack HCI Cluster	xhy8759 Hangyu Xu
10	avm-res-azurestackhci-logicalnetwork	📄	AzureStackHCI logical network	xhy8759 Hangyu Xu
11	avm-res-azurestackhci-virtualmachineinstance	📄	Stack HCI Virtual Machine Instance	xhy8759 Hangyu Xu
12	avm-res-batch-batchaccount	📄	Batch Account	ethanjenkins1 Ethan Jenkins
13	avm-res-cache-redis	📄	Redis Cache	jchancellor-ms Jon Chancellor
14	avm-res-cdn-profile	📄	CDN Profile	Poven795909 Poornima Venkataramanan didayal-msft Divyadeep Dayal
15	avm-res-cognitiveservices-account	📄	Cognitive Service	lonegunmanb Zijie He
16	avm-res-compute-disk	📄	Compute Disk	terrymandin Terry Mandin
17	avm-res-compute-diskencryptionset	📄	Disk Encryption Set	Akashc0807 Akash Choudhary
18	avm-res-compute-gallery	📄	Azure Compute Gallery	Akashc0807 Akash Choudhary
19	avm-res-compute-hostgroup	📄	Host Groups	chianw Chian Wong
20	avm-res-compute-proximityplacementgroup	📄	Proximity Placement Group	fafriha Farouk Friha
21	avm-res-compute-sshpublickey	📄	Public SSH Key	ChrisSidebotham Chris Sidebotham
22	avm-res-compute-virtualmachine	📄	Virtual Machine VM	jchancellor-ms Jon Chancellor
23	avm-res-compute-virtualmachinescaleset	📄	Virtual Machine Scale Set VMSS	terrymandin Terry Mandin marcelkmfst Marcel Keller
24	avm-res-containerinstance-containergroup	📄	Container Instance	sharmilamusunuru Sharmila Musunuru
25	avm-res-containerregistry-registry	📄	Azure Container Registry (ACR)	Akashc0807 Akash Choudhary
26	avm-res-containerservice-managedcluster	📄	AKS managed clusters	ibersanoMS Isabelle Bersano
27	avm-res-databricks-workspace	📄	Azure Databricks Workspace	segraef Sebastian Graef
28	avm-res-datafactory-factory	📄	Data Factory	asishr Asish R
29	avm-res-dataprotection-backupvault	📄	Data Protection Backup Vault	ethanjenkins1 Ethan Jenkins
30	avm-res-dbformysql-flexibleserver	📄	DB for MySQL Flexible Server	mbilalamjad Bilal Amjad
31	avm-res-dbforpostgresql-flexibleserver	📄	DB for Postgre SQL Flexible Server	mbilalamjad Bilal Amjad
32	avm-res-desktopvirtualization-applicationgroup	📄	Azure Virtual Desktop (AVD) Application Group	jensheerin Jen Sheerin
33	avm-res-desktopvirtualization-hostpool	📄	Azure Virtual Desktop (AVD) Host Pool	jensheerin Jen Sheerin
34	avm-res-desktopvirtualization-scalingplan	📄	Azure Virtual Desktop (AVD) Scaling Plan	jensheerin Jen Sheerin
35	avm-res-desktopvirtualization-workspace	📄	Azure Virtual Desktop (AVD) Workspace	jensheerin Jen Sheerin
36	avm-res-devcenter-devcenter	📄	Dev Center
37	avm-res-devopsinfrastructure-pool	📄	DevOps Pools	jaredfholgate Jared Holgate
38	avm-res-documentdb-databaseaccount	📄	CosmosDB Database Account	bryansan-msft Bryan Sanchez Pernia
39	avm-res-edge-site	📄	Azure Arc Site manager	xhy8759 Hangyu Xu
40	avm-res-eventhub-namespace	📄	Event Hub Namespace	mbilalamjad Bilal Amjad
41	avm-res-hybridcontainerservice-provisionedclusterinstance	📄	AKS Arc	xhy8759 Hangyu Xu
42	avm-res-insights-autoscalesetting	📄	Auto scale settings	chianw Chian Wong
43	avm-res-insights-component	📄	Application Insight	Jfolberth John Folberth
44	avm-res-insights-datacollectionendpoint	📄	Data Collection Endpoint	sharmilamusunuru Sharmila Musunuru
45	avm-res-keyvault-vault	📄	Key Vault KV	matt-FFFFFF Matt White
46	avm-res-kusto-cluster	📄	Kusto Clusters	LaurentLesle Laurent Lesle
47	avm-res-logic-workflow	📄	Logic Apps (Workflow)	bakrish Bala Krishnamoorthy
48	avm-res-machinelearningservices-workspace	📄	Machine Learning Services Workspace ML Workspace	Nepomuceno Gabriel Monteiro Nepomuceno
49	avm-res-maintenance-maintenanceconfiguration	📄	Maintenance Configuration	ASHR4 Rhys Ash
50	avm-res-managedidentity-userassignedidentity	📄	User Assigned Identity MSI	Jfolberth John Folberth
51	avm-res-netapp-netappaccount	📄	Azure NetApp File	jtracey93 Jack Tracey
52	avm-res-network-applicationgateway	📄	Application Gateway App GW	mofaizal Mohamed Faizal
53	avm-res-network-applicationgatewaywebapplicationfirewallpolicy	📄	Application Gateway Web Application Firewall (WAF) Policy	mofaizal Mohamed Faizal
54	avm-res-network-applicationsecuritygroup	📄	Application Security Group (ASG) ASG	mbilalamjad Bilal Amjad
55	avm-res-network-azurefirewall	📄	Azure Firewall Azure FW
56	avm-res-network-bastionhost	📄	Bastion Host	humanascode Itamar Hirosh
57	avm-res-network-connection	📄	Virtual Network Gateway Connection	jchancellor-ms Jon Chancellor
58	avm-res-network-ddosprotectionplan	📄	DDoS Protection	sitarant Simona Tarantola jtracey93 Jack Tracey
59	avm-res-network-dnsresolver	📄	DNS Resolver	humanascode Itamar Hirosh
60	avm-res-network-dnszone	📄	Public DNS Zone	sharmilamusunuru Sharmila Musunuru
61	avm-res-network-expressroutecircuit	📄	ExpressRoute Circuit ER	khushal08 Khush Kaviraj adammontlake Adam Montlake
62	avm-res-network-firewallpolicy	📄	Azure Firewall Policy
63	avm-res-network-frontdoorwebapplicationfirewallpolicy	📄	Front Door Web Application Firewall (WAF) Policy	sihbher Gerardo Reyes
64	avm-res-network-ipgroup	📄	IP Group	mathewsg Mathew George
65	avm-res-network-loadbalancer	📄	Loadbalancer	donovm4 Donovan McCoy
66	avm-res-network-localnetworkgateway	📄	Local Network Gateway	Bhavyasree08 Bhavyasree Damarla
67	avm-res-network-natgateway	📄	NAT Gateway	mbilalamjad Bilal Amjad
68	avm-res-network-networkinterface	📄	Network Interface NIC	fafriha Farouk Friha
69	avm-res-network-networkmanager	📄	Azure Virtual Network Manager
70	avm-res-network-networksecuritygroup	📄	Network Security Group	maheshbenke Mahesh Benke
71	avm-res-network-networkwatcher	📄	Azure Network Watcher	terrymandin Terry Mandin
72	avm-res-network-privatednszone	📄	Private DNS Zone	chianw Chian Wong
73	avm-res-network-privateendpoint	📄	Private Endpoint	Misba-Yousuf Misba Yousuf
74	avm-res-network-publicipaddress	📄	Public IP Address PIP
75	avm-res-network-publicipprefix	📄	Public IP Prefix	PmeshramPM Pankaj Meshram
76	avm-res-network-routetable	📄	Route Table UDR	adammontlake Adam Montlake
77	avm-res-network-virtualnetwork	📄	Virtual Network VNET	jaredfholgate Jared Holgate
78	avm-res-operationalinsights-workspace	📄	Log Analytics workspace	jensheerin Jen Sheerin
79	avm-res-oracledatabase-cloudexadatainfrastructure	📄	Oracle Exadata Infrastructure	sihbher Gerardo Reyes terrymandin Terry Mandin
80	avm-res-oracledatabase-cloudvmcluster	📄	Oracle VM cluster	sihbher Gerardo Reyes terrymandin Terry Mandin
81	avm-res-portal-dashboard	📄	Azure Portal Dashboard	VeronicaSea Veronica Xu
82	avm-res-resourcegraph-query	📄	Resource Graph Query	SJAYAP S Jayaprakash
83	avm-res-resources-resourcegroup	📄	Resource Group RG	Jfolberth John Folberth
84	avm-res-search-searchservice	📄	Search Service	seekerofsai Bhanu Neti
85	avm-res-servicebus-namespace	📄	Service Bus Namespace	bryansan-msft Bryan Sanchez Pernia
86	avm-res-sql-managedinstance	📄	SQL Managed Instance SQL MI	mbilalamjad Bilal Amjad
87	avm-res-sql-server	📄	Azure SQL Server	mbilalamjad Bilal Amjad
88	avm-res-storage-storageaccount	📄	Storage Account	chinthakaru Chinthaka Rupasinghe
89	avm-res-web-hostingenvironment	📄	App Service Environment ASE	ibersanoMS Isabelle Bersano
90	avm-res-web-serverfarm	📄	App Service Plan	ibersanoMS Isabelle Bersano
91	avm-res-web-site	📄	Web/Function App App Service, Web Site, Logic App, Function App	donovm4 Donovan McCoy
92	avm-res-web-staticsite	📄	Static Web App	donovm4 Donovan McCoy

Proposed modules - ⚪

➕ Proposed Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Status & Versions	Primary Owner
01	avm-res-aad-domainservice	n/a	Azure Active Directory Domain Service		humanascode Itamar Hirosh
02	avm-res-alertsmanagement-actionrule	n/a	Action Rules		joeybarnes Joseph Barnes
03	avm-res-analysisservices-server	n/a	Analysis Services Server		Bhavyasree08 Bhavyasree Damarla
04	avm-res-botservice-botservice	n/a	Bot Service		salujamanish Manish Saluja
05	avm-res-communication-emailservice	n/a	Email Communication Service		lonegunmanb Zijie He
06	avm-res-compute-image	n/a	Image
07	avm-res-consumption-budget	n/a	Consumption Budget
08	avm-res-dashboard-grafana	n/a	Azure Managed Grafana		khajour Abdelaziz Khajour
09	avm-res-databricks-accessconnector	n/a	Azure Databricks Access Connector
10	avm-res-devtestlab-lab	n/a	DevTest Lab		sharmilamusunuru Sharmila Musunuru
11	avm-res-digitaltwins-digitaltwinsinstance	n/a	Digital Twins Instance
12	avm-res-eventgrid-domain	n/a	Event Grid Domain
13	avm-res-eventgrid-namespace	n/a	Event Grid Namespace		dassbernd Berna Sandalli
14	avm-res-eventgrid-systemtopic	n/a	Event Grid System Topic
15	avm-res-eventgrid-topic	n/a	Event Grid Topic
16	avm-res-healthbot-healthbot	n/a	Azure Health Bot
17	avm-res-hybridcompute-machine	n/a	Hybrid Compute Machine
18	avm-res-insights-actiongroup	n/a	Action Group		arjenhuitema Arjen Huitema
19	avm-res-insights-activitylogalert	n/a	Activity log alerts		tagolovina Tanya Golovina
20	avm-res-insights-alertrule	n/a	Alert Rules		joeybarnes Joseph Barnes
21	avm-res-insights-datacollectionrule	n/a	Data Collection Rule		sharmilamusunuru Sharmila Musunuru
22	avm-res-insights-logprofile	n/a	Log profile		sharmilamusunuru Sharmila Musunuru
23	avm-res-insights-metricalert	n/a	Metric Alert		arjenhuitema Arjen Huitema
24	avm-res-insights-privatelinkscope	n/a	Azure Monitor Private Link Scope		sharmilamusunuru Sharmila Musunuru
25	avm-res-insights-scheduledqueryrule	n/a	Scheduled Query Rule
26	avm-res-loadtestservice-loadtest	n/a	Load Testing Service		LaurentLesle Laurent Lesle
27	avm-res-managedservices-registrationdefinition	n/a	Registration Definition (Lighthouse)
28	avm-res-management-managementgroup	n/a	Management Group MG
29	avm-res-network-dnsforwardingruleset	n/a	DNS Forwarding Ruleset		sharmilamusunuru Sharmila Musunuru
30	avm-res-network-frontdoor	n/a	Azure Front Door		mbilalamjad Bilal Amjad
31	avm-res-network-privatelinkservice	n/a	Private Link Service		avivshrem Aviv Shrem
32	avm-res-network-serviceendpointpolicy	n/a	Service Endpoint Policy
33	avm-res-network-trafficmanagerprofile	n/a	Traffic Manager Profile		AnubhaR94 Anubha Rana
34	avm-res-network-virtualnetworkgateway	n/a	Virtual Network Gateway VNET GW
35	avm-res-network-virtualrouter	n/a	Route Server
36	avm-res-operationsmanagement-solution	n/a	Operations Management Solution
37	avm-res-powerbidedicated-capacity	n/a	Power BI Dedicated Capacity
38	avm-res-purview-account	n/a	Purview Account		leonid-klatt Leonid Klatt
39	avm-res-recoveryservices-vault	n/a	Recovery Services Vault		elsalvos Cesar Abrego
40	avm-res-redhatopenShift-openshiftcluster	n/a	OpenShift Cluster		ljtill Lyon Till
41	avm-res-relay-namespace	n/a	Relay Namespace
42	avm-res-servicefabric-cluster	n/a	Service Fabric Cluster
43	avm-res-servicenetworking-trafficcontroller	n/a	Application Gateway for Containers (Traffic Controller)		mofaizal Mohamed Faizal
44	avm-res-signalrservice-signalr	n/a	SignalR Service SignalR
45	avm-res-sql-instancepool	n/a	Instance Pools
46	avm-res-sqlvirtualmachine-sqlvirtualmachine	n/a	Sql Virtual Machine SQL VM		timchapman Tim Chapman
47	avm-res-synapse-workspace	n/a	Synapse Workspace		Karni-G Karni Gupta
48	avm-res-virtualmachineimages-imagetemplate	n/a	Virtual Machine Image Template
49	avm-res-web-connection	n/a	API Connection		dukumili Sandhya Kumili
50	❌ None listed	❌ None listed	❌ None listed	❌ None listed	❌ None listed

Deprecated modules - 🔴

➕ Deprecated Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Status & Versions	Primary Owner
01	❌ None listed	❌ None listed	❌ None listed	❌ None listed	❌ None listed

All modules - 📇

➕ All Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Primary Owner
01	avm-res-aad-domainservice	n/a	Azure Active Directory Domain Service	humanascode Itamar Hirosh
02	avm-res-alertsmanagement-actionrule	n/a	Action Rules	joeybarnes Joseph Barnes
03	avm-res-analysisservices-server	n/a	Analysis Services Server	Bhavyasree08 Bhavyasree Damarla
04	avm-res-apimanagement-service	📄	API Management Service	swatilekhapaul Swatilekha Paul
05	avm-res-app-containerapp	📄	Container App	lonegunmanb Zijie He
06	avm-res-app-job	📄	App Job	sujaypillai Sujay Pillai
07	avm-res-app-managedenvironment	📄	App Managed Environment	segraef Sebastian Graef
08	avm-res-appconfiguration-configurationstore	📄	App Configuration Store	matt-FFFFFF Matt White
09	avm-res-authorization-roleassignment	📄	Role Assignment	jaredfholgate Jared Holgate
10	avm-res-automation-automationaccount	📄	Automation Account	didayal-msft Divyadeep Dayal Poven795909 Poornima Venkataramanan
11	avm-res-avs-privatecloud	📄	AVS Private Cloud	jchancellor-ms Jon Chancellor
12	avm-res-azurestackhci-cluster	📄	Azure Stack HCI Cluster	xhy8759 Hangyu Xu
13	avm-res-azurestackhci-logicalnetwork	📄	AzureStackHCI logical network	xhy8759 Hangyu Xu
14	avm-res-azurestackhci-virtualmachineinstance	📄	Stack HCI Virtual Machine Instance	xhy8759 Hangyu Xu
15	avm-res-batch-batchaccount	📄	Batch Account	ethanjenkins1 Ethan Jenkins
16	avm-res-botservice-botservice	n/a	Bot Service	salujamanish Manish Saluja
17	avm-res-cache-redis	📄	Redis Cache	jchancellor-ms Jon Chancellor
18	avm-res-cdn-profile	📄	CDN Profile	Poven795909 Poornima Venkataramanan didayal-msft Divyadeep Dayal
19	avm-res-cognitiveservices-account	📄	Cognitive Service	lonegunmanb Zijie He
20	avm-res-communication-emailservice	n/a	Email Communication Service	lonegunmanb Zijie He
21	avm-res-compute-disk	📄	Compute Disk	terrymandin Terry Mandin
22	avm-res-compute-diskencryptionset	📄	Disk Encryption Set	Akashc0807 Akash Choudhary
23	avm-res-compute-gallery	📄	Azure Compute Gallery	Akashc0807 Akash Choudhary
24	avm-res-compute-hostgroup	📄	Host Groups	chianw Chian Wong
25	avm-res-compute-image	n/a	Image
26	avm-res-compute-proximityplacementgroup	📄	Proximity Placement Group	fafriha Farouk Friha
27	avm-res-compute-sshpublickey	📄	Public SSH Key	ChrisSidebotham Chris Sidebotham
28	avm-res-compute-virtualmachine	📄	Virtual Machine VM	jchancellor-ms Jon Chancellor
29	avm-res-compute-virtualmachinescaleset	📄	Virtual Machine Scale Set VMSS	terrymandin Terry Mandin marcelkmfst Marcel Keller
30	avm-res-consumption-budget	n/a	Consumption Budget
31	avm-res-containerinstance-containergroup	📄	Container Instance	sharmilamusunuru Sharmila Musunuru
32	avm-res-containerregistry-registry	📄	Azure Container Registry (ACR)	Akashc0807 Akash Choudhary
33	avm-res-containerservice-managedcluster	📄	AKS managed clusters	ibersanoMS Isabelle Bersano
34	avm-res-dashboard-grafana	n/a	Azure Managed Grafana	khajour Abdelaziz Khajour
35	avm-res-databricks-accessconnector	n/a	Azure Databricks Access Connector
36	avm-res-databricks-workspace	📄	Azure Databricks Workspace	segraef Sebastian Graef
37	avm-res-datafactory-factory	📄	Data Factory	asishr Asish R
38	avm-res-dataprotection-backupvault	📄	Data Protection Backup Vault	ethanjenkins1 Ethan Jenkins
39	avm-res-dbformysql-flexibleserver	📄	DB for MySQL Flexible Server	mbilalamjad Bilal Amjad
40	avm-res-dbforpostgresql-flexibleserver	📄	DB for Postgre SQL Flexible Server	mbilalamjad Bilal Amjad
41	avm-res-desktopvirtualization-applicationgroup	📄	Azure Virtual Desktop (AVD) Application Group	jensheerin Jen Sheerin
42	avm-res-desktopvirtualization-hostpool	📄	Azure Virtual Desktop (AVD) Host Pool	jensheerin Jen Sheerin
43	avm-res-desktopvirtualization-scalingplan	📄	Azure Virtual Desktop (AVD) Scaling Plan	jensheerin Jen Sheerin
44	avm-res-desktopvirtualization-workspace	📄	Azure Virtual Desktop (AVD) Workspace	jensheerin Jen Sheerin
45	avm-res-devcenter-devcenter	📄	Dev Center
46	avm-res-devopsinfrastructure-pool	📄	DevOps Pools	jaredfholgate Jared Holgate
47	avm-res-devtestlab-lab	n/a	DevTest Lab	sharmilamusunuru Sharmila Musunuru
48	avm-res-digitaltwins-digitaltwinsinstance	n/a	Digital Twins Instance
49	avm-res-documentdb-databaseaccount	📄	CosmosDB Database Account	bryansan-msft Bryan Sanchez Pernia
50	avm-res-edge-site	📄	Azure Arc Site manager	xhy8759 Hangyu Xu
51	avm-res-eventgrid-domain	n/a	Event Grid Domain
52	avm-res-eventgrid-namespace	n/a	Event Grid Namespace	dassbernd Berna Sandalli
53	avm-res-eventgrid-systemtopic	n/a	Event Grid System Topic
54	avm-res-eventgrid-topic	n/a	Event Grid Topic
55	avm-res-eventhub-namespace	📄	Event Hub Namespace	mbilalamjad Bilal Amjad
56	avm-res-healthbot-healthbot	n/a	Azure Health Bot
57	avm-res-hybridcompute-machine	n/a	Hybrid Compute Machine
58	avm-res-hybridcontainerservice-provisionedclusterinstance	📄	AKS Arc	xhy8759 Hangyu Xu
59	avm-res-insights-actiongroup	n/a	Action Group	arjenhuitema Arjen Huitema
60	avm-res-insights-activitylogalert	n/a	Activity log alerts	tagolovina Tanya Golovina
61	avm-res-insights-alertrule	n/a	Alert Rules	joeybarnes Joseph Barnes
62	avm-res-insights-autoscalesetting	📄	Auto scale settings	chianw Chian Wong
63	avm-res-insights-component	📄	Application Insight	Jfolberth John Folberth
64	avm-res-insights-datacollectionendpoint	📄	Data Collection Endpoint	sharmilamusunuru Sharmila Musunuru
65	avm-res-insights-datacollectionrule	n/a	Data Collection Rule	sharmilamusunuru Sharmila Musunuru
66	avm-res-insights-logprofile	n/a	Log profile	sharmilamusunuru Sharmila Musunuru
67	avm-res-insights-metricalert	n/a	Metric Alert	arjenhuitema Arjen Huitema
68	avm-res-insights-privatelinkscope	n/a	Azure Monitor Private Link Scope	sharmilamusunuru Sharmila Musunuru
69	avm-res-insights-scheduledqueryrule	n/a	Scheduled Query Rule
70	avm-res-keyvault-vault	📄	Key Vault KV	matt-FFFFFF Matt White
71	avm-res-kusto-cluster	📄	Kusto Clusters	LaurentLesle Laurent Lesle
72	avm-res-loadtestservice-loadtest	n/a	Load Testing Service	LaurentLesle Laurent Lesle
73	avm-res-logic-workflow	📄	Logic Apps (Workflow)	bakrish Bala Krishnamoorthy
74	avm-res-machinelearningservices-workspace	📄	Machine Learning Services Workspace ML Workspace	Nepomuceno Gabriel Monteiro Nepomuceno
75	avm-res-maintenance-maintenanceconfiguration	📄	Maintenance Configuration	ASHR4 Rhys Ash
76	avm-res-managedidentity-userassignedidentity	📄	User Assigned Identity MSI	Jfolberth John Folberth
77	avm-res-managedservices-registrationdefinition	n/a	Registration Definition (Lighthouse)
78	avm-res-management-managementgroup	n/a	Management Group MG
79	avm-res-netapp-netappaccount	📄	Azure NetApp File	jtracey93 Jack Tracey
80	avm-res-network-applicationgateway	📄	Application Gateway App GW	mofaizal Mohamed Faizal
81	avm-res-network-applicationgatewaywebapplicationfirewallpolicy	📄	Application Gateway Web Application Firewall (WAF) Policy	mofaizal Mohamed Faizal
82	avm-res-network-applicationsecuritygroup	📄	Application Security Group (ASG) ASG	mbilalamjad Bilal Amjad
83	avm-res-network-azurefirewall	📄	Azure Firewall Azure FW
84	avm-res-network-bastionhost	📄	Bastion Host	humanascode Itamar Hirosh
85	avm-res-network-connection	📄	Virtual Network Gateway Connection	jchancellor-ms Jon Chancellor
86	avm-res-network-ddosprotectionplan	📄	DDoS Protection	sitarant Simona Tarantola jtracey93 Jack Tracey
87	avm-res-network-dnsforwardingruleset	n/a	DNS Forwarding Ruleset	sharmilamusunuru Sharmila Musunuru
88	avm-res-network-dnsresolver	📄	DNS Resolver	humanascode Itamar Hirosh
89	avm-res-network-dnszone	📄	Public DNS Zone	sharmilamusunuru Sharmila Musunuru
90	avm-res-network-expressroutecircuit	📄	ExpressRoute Circuit ER	khushal08 Khush Kaviraj adammontlake Adam Montlake
91	avm-res-network-firewallpolicy	📄	Azure Firewall Policy
92	avm-res-network-frontdoor	n/a	Azure Front Door	mbilalamjad Bilal Amjad
93	avm-res-network-frontdoorwebapplicationfirewallpolicy	📄	Front Door Web Application Firewall (WAF) Policy	sihbher Gerardo Reyes
94	avm-res-network-ipgroup	📄	IP Group	mathewsg Mathew George
95	avm-res-network-loadbalancer	📄	Loadbalancer	donovm4 Donovan McCoy
96	avm-res-network-localnetworkgateway	📄	Local Network Gateway	Bhavyasree08 Bhavyasree Damarla
97	avm-res-network-natgateway	📄	NAT Gateway	mbilalamjad Bilal Amjad
98	avm-res-network-networkinterface	📄	Network Interface NIC	fafriha Farouk Friha
99	avm-res-network-networkmanager	📄	Azure Virtual Network Manager
100	avm-res-network-networksecuritygroup	📄	Network Security Group	maheshbenke Mahesh Benke
101	avm-res-network-networkwatcher	📄	Azure Network Watcher	terrymandin Terry Mandin
102	avm-res-network-privatednszone	📄	Private DNS Zone	chianw Chian Wong
103	avm-res-network-privateendpoint	📄	Private Endpoint	Misba-Yousuf Misba Yousuf
104	avm-res-network-privatelinkservice	n/a	Private Link Service	avivshrem Aviv Shrem
105	avm-res-network-publicipaddress	📄	Public IP Address PIP
106	avm-res-network-publicipprefix	📄	Public IP Prefix	PmeshramPM Pankaj Meshram
107	avm-res-network-routetable	📄	Route Table UDR	adammontlake Adam Montlake
108	avm-res-network-serviceendpointpolicy	n/a	Service Endpoint Policy
109	avm-res-network-trafficmanagerprofile	n/a	Traffic Manager Profile	AnubhaR94 Anubha Rana
110	avm-res-network-virtualnetwork	📄	Virtual Network VNET	jaredfholgate Jared Holgate
111	avm-res-network-virtualnetworkgateway	n/a	Virtual Network Gateway VNET GW
112	avm-res-network-virtualrouter	n/a	Route Server
113	avm-res-operationalinsights-workspace	📄	Log Analytics workspace	jensheerin Jen Sheerin
114	avm-res-operationsmanagement-solution	n/a	Operations Management Solution
115	avm-res-oracledatabase-cloudexadatainfrastructure	📄	Oracle Exadata Infrastructure	sihbher Gerardo Reyes terrymandin Terry Mandin
116	avm-res-oracledatabase-cloudvmcluster	📄	Oracle VM cluster	sihbher Gerardo Reyes terrymandin Terry Mandin
117	avm-res-portal-dashboard	📄	Azure Portal Dashboard	VeronicaSea Veronica Xu
118	avm-res-powerbidedicated-capacity	n/a	Power BI Dedicated Capacity
119	avm-res-purview-account	n/a	Purview Account	leonid-klatt Leonid Klatt
120	avm-res-recoveryservices-vault	n/a	Recovery Services Vault	elsalvos Cesar Abrego
121	avm-res-redhatopenShift-openshiftcluster	n/a	OpenShift Cluster	ljtill Lyon Till
122	avm-res-relay-namespace	n/a	Relay Namespace
123	avm-res-resourcegraph-query	📄	Resource Graph Query	SJAYAP S Jayaprakash
124	avm-res-resources-resourcegroup	📄	Resource Group RG	Jfolberth John Folberth
125	avm-res-search-searchservice	📄	Search Service	seekerofsai Bhanu Neti
126	avm-res-servicebus-namespace	📄	Service Bus Namespace	bryansan-msft Bryan Sanchez Pernia
127	avm-res-servicefabric-cluster	n/a	Service Fabric Cluster
128	avm-res-servicenetworking-trafficcontroller	n/a	Application Gateway for Containers (Traffic Controller)	mofaizal Mohamed Faizal
129	avm-res-signalrservice-signalr	n/a	SignalR Service SignalR
130	avm-res-sql-instancepool	n/a	Instance Pools
131	avm-res-sql-managedinstance	📄	SQL Managed Instance SQL MI	mbilalamjad Bilal Amjad
132	avm-res-sql-server	📄	Azure SQL Server	mbilalamjad Bilal Amjad
133	avm-res-sqlvirtualmachine-sqlvirtualmachine	n/a	Sql Virtual Machine SQL VM	timchapman Tim Chapman
134	avm-res-storage-storageaccount	📄	Storage Account	chinthakaru Chinthaka Rupasinghe
135	avm-res-synapse-workspace	n/a	Synapse Workspace	Karni-G Karni Gupta
136	avm-res-virtualmachineimages-imagetemplate	n/a	Virtual Machine Image Template
137	avm-res-web-connection	n/a	API Connection	dukumili Sandhya Kumili
138	avm-res-web-hostingenvironment	📄	App Service Environment ASE	ibersanoMS Isabelle Bersano
139	avm-res-web-serverfarm	📄	App Service Plan	ibersanoMS Isabelle Bersano
140	avm-res-web-site	📄	Web/Function App App Service, Web Site, Logic App, Function App	donovm4 Donovan McCoy
141	avm-res-web-staticsite	📄	Static Web App	donovm4 Donovan McCoy

Module Publication History - 📅

➕ Module Publication History - Module names, status and owners

Modules published in May 2025

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-app-job	📄	App Job	sujaypillai Sujay Pillai
02	avm-res-batch-batchaccount	📄	Batch Account	ethanjenkins1 Ethan Jenkins
03	avm-res-dataprotection-backupvault	📄	Data Protection Backup Vault	ethanjenkins1 Ethan Jenkins

Modules published in April 2025

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-apimanagement-service	📄	API Management Service	swatilekhapaul Swatilekha Paul
02	avm-res-automation-automationaccount	📄	Automation Account	didayal-msft Divyadeep Dayal Poven795909 Poornima Venkataramanan
03	avm-res-datafactory-factory	📄	Data Factory	asishr Asish R
04	avm-res-eventhub-namespace	📄	Event Hub Namespace	mbilalamjad Bilal Amjad
05	avm-res-maintenance-maintenanceconfiguration	📄	Maintenance Configuration	ASHR4 Rhys Ash
06	avm-res-network-ipgroup	📄	IP Group	mathewsg Mathew George
07	avm-res-network-publicipprefix	📄	Public IP Prefix	PmeshramPM Pankaj Meshram
08	avm-res-resourcegraph-query	📄	Resource Graph Query	SJAYAP S Jayaprakash

Modules published in March 2025

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-res-appconfiguration-configurationstore	📄	App Configuration Store		matt-FFFFFF Matt White

Modules published in February 2025

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-res-network-applicationgatewaywebapplicationfirewallpolicy	📄	Application Gateway Web Application Firewall (WAF) Policy		mofaizal Mohamed Faizal

Modules published in January 2025

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-containerservice-managedcluster	📄	AKS managed clusters	ibersanoMS Isabelle Bersano
02	avm-res-netapp-netappaccount	📄	Azure NetApp File	jtracey93 Jack Tracey
03	avm-res-network-applicationsecuritygroup	📄	Application Security Group (ASG) ASG	mbilalamjad Bilal Amjad
04	avm-res-network-connection	📄	Virtual Network Gateway Connection	jchancellor-ms Jon Chancellor

Modules published in December 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-res-compute-gallery	📄	Azure Compute Gallery		Akashc0807 Akash Choudhary

Modules published in November 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-compute-proximityplacementgroup	📄	Proximity Placement Group	fafriha Farouk Friha
02	avm-res-insights-autoscalesetting	📄	Auto scale settings	chianw Chian Wong
03	avm-res-network-localnetworkgateway	📄	Local Network Gateway	Bhavyasree08 Bhavyasree Damarla
04	avm-res-network-networkinterface	📄	Network Interface NIC	fafriha Farouk Friha

Modules published in October 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-compute-diskencryptionset	📄	Disk Encryption Set	Akashc0807 Akash Choudhary
02	avm-res-devcenter-devcenter	📄	Dev Center
03	avm-res-network-expressroutecircuit	📄	ExpressRoute Circuit ER	khushal08 Khush Kaviraj adammontlake Adam Montlake
04	avm-res-network-frontdoorwebapplicationfirewallpolicy	📄	Front Door Web Application Firewall (WAF) Policy	sihbher Gerardo Reyes

Modules published in September 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-dbformysql-flexibleserver	📄	DB for MySQL Flexible Server	mbilalamjad Bilal Amjad
02	avm-res-dbforpostgresql-flexibleserver	📄	DB for Postgre SQL Flexible Server	mbilalamjad Bilal Amjad
03	avm-res-network-privateendpoint	📄	Private Endpoint	Misba-Yousuf Misba Yousuf
04	avm-res-oracledatabase-cloudexadatainfrastructure	📄	Oracle Exadata Infrastructure	sihbher Gerardo Reyes terrymandin Terry Mandin
05	avm-res-oracledatabase-cloudvmcluster	📄	Oracle VM cluster	sihbher Gerardo Reyes terrymandin Terry Mandin
06	avm-res-portal-dashboard	📄	Azure Portal Dashboard	VeronicaSea Veronica Xu
07	avm-res-sql-managedinstance	📄	SQL Managed Instance SQL MI	mbilalamjad Bilal Amjad
08	avm-res-sql-server	📄	Azure SQL Server	mbilalamjad Bilal Amjad

Modules published in August 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-azurestackhci-cluster	📄	Azure Stack HCI Cluster	xhy8759 Hangyu Xu
02	avm-res-azurestackhci-logicalnetwork	📄	AzureStackHCI logical network	xhy8759 Hangyu Xu
03	avm-res-azurestackhci-virtualmachineinstance	📄	Stack HCI Virtual Machine Instance	xhy8759 Hangyu Xu
04	avm-res-compute-hostgroup	📄	Host Groups	chianw Chian Wong
05	avm-res-devopsinfrastructure-pool	📄	DevOps Pools	jaredfholgate Jared Holgate
06	avm-res-documentdb-databaseaccount	📄	CosmosDB Database Account	bryansan-msft Bryan Sanchez Pernia
07	avm-res-edge-site	📄	Azure Arc Site manager	xhy8759 Hangyu Xu
08	avm-res-hybridcontainerservice-provisionedclusterinstance	📄	AKS Arc	xhy8759 Hangyu Xu
09	avm-res-insights-component	📄	Application Insight	Jfolberth John Folberth
10	avm-res-insights-datacollectionendpoint	📄	Data Collection Endpoint	sharmilamusunuru Sharmila Musunuru
11	avm-res-network-applicationgateway	📄	Application Gateway App GW	mofaizal Mohamed Faizal
12	avm-res-network-dnszone	📄	Public DNS Zone	sharmilamusunuru Sharmila Musunuru
13	avm-res-resources-resourcegroup	📄	Resource Group RG	Jfolberth John Folberth
14	avm-res-search-searchservice	📄	Search Service	seekerofsai Bhanu Neti
15	avm-res-web-serverfarm	📄	App Service Plan	ibersanoMS Isabelle Bersano

Modules published in July 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-app-containerapp	📄	Container App	lonegunmanb Zijie He
02	avm-res-containerinstance-containergroup	📄	Container Instance	sharmilamusunuru Sharmila Musunuru
03	avm-res-machinelearningservices-workspace	📄	Machine Learning Services Workspace ML Workspace	Nepomuceno Gabriel Monteiro Nepomuceno
04	avm-res-network-networkwatcher	📄	Azure Network Watcher	terrymandin Terry Mandin

Modules published in June 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-cache-redis	📄	Redis Cache	jchancellor-ms Jon Chancellor
02	avm-res-logic-workflow	📄	Logic Apps (Workflow)	bakrish Bala Krishnamoorthy
03	avm-res-web-hostingenvironment	📄	App Service Environment ASE	ibersanoMS Isabelle Bersano

Modules published in May 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-cdn-profile	📄	CDN Profile	Poven795909 Poornima Venkataramanan didayal-msft Divyadeep Dayal
02	avm-res-compute-disk	📄	Compute Disk	terrymandin Terry Mandin
03	avm-res-compute-sshpublickey	📄	Public SSH Key	ChrisSidebotham Chris Sidebotham
04	avm-res-network-dnsresolver	📄	DNS Resolver	humanascode Itamar Hirosh
05	avm-res-network-routetable	📄	Route Table UDR	adammontlake Adam Montlake

Modules published in April 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-res-kusto-cluster	📄	Kusto Clusters		LaurentLesle Laurent Lesle
02	avm-res-servicebus-namespace	📄	Service Bus Namespace		bryansan-msft Bryan Sanchez Pernia

Modules published in March 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-databricks-workspace	📄	Azure Databricks Workspace	segraef Sebastian Graef
02	avm-res-managedidentity-userassignedidentity	📄	User Assigned Identity MSI	Jfolberth John Folberth
03	avm-res-network-privatednszone	📄	Private DNS Zone	chianw Chian Wong

Modules published in February 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-app-managedenvironment	📄	App Managed Environment	segraef Sebastian Graef
02	avm-res-avs-privatecloud	📄	AVS Private Cloud	jchancellor-ms Jon Chancellor
03	avm-res-cognitiveservices-account	📄	Cognitive Service	lonegunmanb Zijie He
04	avm-res-compute-virtualmachinescaleset	📄	Virtual Machine Scale Set VMSS	terrymandin Terry Mandin marcelkmfst Marcel Keller
05	avm-res-containerregistry-registry	📄	Azure Container Registry (ACR)	Akashc0807 Akash Choudhary
06	avm-res-network-bastionhost	📄	Bastion Host	humanascode Itamar Hirosh
07	avm-res-network-networksecuritygroup	📄	Network Security Group	maheshbenke Mahesh Benke
08	avm-res-network-publicipaddress	📄	Public IP Address PIP
09	avm-res-storage-storageaccount	📄	Storage Account	chinthakaru Chinthaka Rupasinghe
10	avm-res-web-site	📄	Web/Function App App Service, Web Site, Logic App, Function App	donovm4 Donovan McCoy
11	avm-res-web-staticsite	📄	Static Web App	donovm4 Donovan McCoy

Modules published in January 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-authorization-roleassignment	📄	Role Assignment	jaredfholgate Jared Holgate
02	avm-res-network-azurefirewall	📄	Azure Firewall Azure FW
03	avm-res-network-firewallpolicy	📄	Azure Firewall Policy
04	avm-res-network-networkmanager	📄	Azure Virtual Network Manager
05	avm-res-operationalinsights-workspace	📄	Log Analytics workspace	jensheerin Jen Sheerin

Modules published in December 2023

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-desktopvirtualization-applicationgroup	📄	Azure Virtual Desktop (AVD) Application Group	jensheerin Jen Sheerin
02	avm-res-desktopvirtualization-scalingplan	📄	Azure Virtual Desktop (AVD) Scaling Plan	jensheerin Jen Sheerin
03	avm-res-desktopvirtualization-workspace	📄	Azure Virtual Desktop (AVD) Workspace	jensheerin Jen Sheerin
04	avm-res-network-natgateway	📄	NAT Gateway	mbilalamjad Bilal Amjad

Modules published in November 2023

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-res-compute-virtualmachine	📄	Virtual Machine VM	jchancellor-ms Jon Chancellor
02	avm-res-network-ddosprotectionplan	📄	DDoS Protection	sitarant Simona Tarantola jtracey93 Jack Tracey
03	avm-res-network-loadbalancer	📄	Loadbalancer	donovm4 Donovan McCoy

Modules published in October 2023

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-res-desktopvirtualization-hostpool	📄	Azure Virtual Desktop (AVD) Host Pool		jensheerin Jen Sheerin
02	avm-res-network-virtualnetwork	📄	Virtual Network VNET		jaredfholgate Jared Holgate

Modules published in September 2023

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-res-keyvault-vault	📄	Key Vault KV		matt-FFFFFF Matt White

For Module Owners & Contributors

Note

This section is mainly intended for module owners and contributors as it contains information about the GitHub Teams for Owners & Contributors.

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

➕ All Modules - Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

No.	Module Name	GitHub Teams for Module Owners and Contributors
01	avm-res-aad-domainservice	`@Azure/avm-res-aad-domainservice-module-owners-tf` `@Azure/avm-res-aad-domainservice-module-contributors-tf`
02	avm-res-alertsmanagement-actionrule	`@Azure/avm-res-alertsmanagement-actionrule-module-owners-tf` `@Azure/avm-res-alertsmanagement-actionrule-module-contributors-tf`
03	avm-res-analysisservices-server	`@Azure/avm-res-analysisservices-server-module-owners-tf` `@Azure/avm-res-analysisservices-server-module-contributors-tf`
04	avm-res-apimanagement-service	`@Azure/avm-res-apimanagement-service-module-owners-tf` `@Azure/avm-res-apimanagement-service-module-contributors-tf`
05	avm-res-app-containerapp	`@Azure/avm-res-app-containerapp-module-owners-tf` `@Azure/avm-res-app-containerapp-module-contributors-tf`
06	avm-res-app-job	`@Azure/avm-res-app-job-module-owners-tf` `@Azure/avm-res-app-job-module-contributors-tf`
07	avm-res-app-managedenvironment	`@Azure/avm-res-app-managedenvironment-module-owners-tf` `@Azure/avm-res-app-managedenvironment-module-contributors-tf`
08	avm-res-appconfiguration-configurationstore	`@Azure/avm-res-appconfiguration-configurationstore-module-owners-tf` `@Azure/avm-res-appconfiguration-configurationstore-module-contributors-tf`
09	avm-res-authorization-roleassignment	`@Azure/avm-res-authorization-roleassignment-module-owners-tf` `@Azure/avm-res-authorization-roleassignment-module-contributors-tf`
10	avm-res-automation-automationaccount	`@Azure/avm-res-automation-automationaccount-module-owners-tf` `@Azure/avm-res-automation-automationaccount-module-contributors-tf`
11	avm-res-avs-privatecloud	`@Azure/avm-res-avs-privatecloud-module-owners-tf` `@Azure/avm-res-avs-privatecloud-module-contributors-tf`
12	avm-res-azurestackhci-cluster	`@Azure/avm-res-azurestackhci-cluster-module-owners-tf` `@Azure/avm-res-azurestackhci-cluster-module-contributors-tf`
13	avm-res-azurestackhci-logicalnetwork	`@Azure/avm-res-azurestackhci-logicalnetwork-module-owners-tf` `@Azure/avm-res-azurestackhci-logicalnetwork-module-contributors-tf`
14	avm-res-azurestackhci-virtualmachineinstance	`@Azure/avm-res-azurestackhci-virtualmachineinstance-module-owners-tf` `@Azure/avm-res-azurestackhci-virtualmachineinstance-module-contributors-tf`
15	avm-res-batch-batchaccount	`@Azure/avm-res-batch-batchaccount-module-owners-tf` `@Azure/avm-res-batch-batchaccount-module-contributors-tf`
16	avm-res-botservice-botservice	`@Azure/avm-res-botservice-botservice-module-owners-tf` `@Azure/avm-res-botservice-botservice-module-contributors-tf`
17	avm-res-cache-redis	`@Azure/avm-res-cache-redis-module-owners-tf` `@Azure/avm-res-cache-redis-module-contributors-tf`
18	avm-res-cdn-profile	`@Azure/avm-res-cdn-profile-module-owners-tf` `@Azure/avm-res-cdn-profile-module-contributors-tf`
19	avm-res-cognitiveservices-account	`@Azure/avm-res-cognitiveservices-account-module-owners-tf` `@Azure/avm-res-cognitiveservices-account-module-contributors-tf`
20	avm-res-communication-emailservice	`@Azure/avm-res-communication-emailservice-module-owners-tf` `@Azure/avm-res-communication-emailservice-module-contributors-tf`
21	avm-res-compute-disk	`@Azure/avm-res-compute-disk-module-owners-tf` `@Azure/avm-res-compute-disk-module-contributors-tf`
22	avm-res-compute-diskencryptionset	`@Azure/avm-res-compute-diskencryptionset-module-owners-tf` `@Azure/avm-res-compute-diskencryptionset-module-contributors-tf`
23	avm-res-compute-gallery	`@Azure/avm-res-compute-gallery-module-owners-tf` `@Azure/avm-res-compute-gallery-module-contributors-tf`
24	avm-res-compute-hostgroup	`@Azure/avm-res-compute-hostgroup-module-owners-tf` `@Azure/avm-res-compute-hostgroup-module-contributors-tf`
25	avm-res-compute-image	`@Azure/avm-res-compute-image-module-owners-tf` `@Azure/avm-res-compute-image-module-contributors-tf`
26	avm-res-compute-proximityplacementgroup	`@Azure/avm-res-compute-proximityplacementgroup-module-owners-tf` `@Azure/avm-res-compute-proximityplacementgroup-module-contributors-tf`
27	avm-res-compute-sshpublickey	`@Azure/avm-res-compute-sshpublickey-module-owners-tf` `@Azure/avm-res-compute-sshpublickey-module-contributors-tf`
28	avm-res-compute-virtualmachine	`@Azure/avm-res-compute-virtualmachine-module-owners-tf` `@Azure/avm-res-compute-virtualmachine-module-contributors-tf`
29	avm-res-compute-virtualmachinescaleset	`@Azure/avm-res-compute-virtualmachinescaleset-module-owners-tf` `@Azure/avm-res-compute-virtualmachinescaleset-module-contributors-tf`
30	avm-res-consumption-budget	`@Azure/avm-res-consumption-budget-module-owners-tf` `@Azure/avm-res-consumption-budget-module-contributors-tf`
31	avm-res-containerinstance-containergroup	`@Azure/avm-res-containerinstance-containergroup-module-owners-tf` `@Azure/avm-res-containerinstance-containergroup-module-contributors-tf`
32	avm-res-containerregistry-registry	`@Azure/avm-res-containerregistry-registry-module-owners-tf` `@Azure/avm-res-containerregistry-registry-module-contributors-tf`
33	avm-res-containerservice-managedcluster	`@Azure/avm-res-containerservice-managedcluster-module-owners-tf` `@Azure/avm-res-containerservice-managedcluster-module-contributors-tf`
34	avm-res-dashboard-grafana	`@Azure/avm-res-dashboard-grafana-module-owners-tf` `@Azure/avm-res-dashboard-grafana-module-contributors-tf`
35	avm-res-databricks-accessconnector	`@Azure/avm-res-databricks-accessconnector-module-owners-tf` `@Azure/avm-res-databricks-accessconnector-module-contributors-tf`
36	avm-res-databricks-workspace	`@Azure/avm-res-databricks-workspace-module-owners-tf` `@Azure/avm-res-databricks-workspace-module-contributors-tf`
37	avm-res-datafactory-factory	`@Azure/avm-res-datafactory-factory-module-owners-tf` `@Azure/avm-res-datafactory-factory-module-contributors-tf`
38	avm-res-dataprotection-backupvault	`@Azure/avm-res-dataprotection-backupvault-module-owners-tf` `@Azure/avm-res-dataprotection-backupvault-module-contributors-tf`
39	avm-res-dbformysql-flexibleserver	`@Azure/avm-res-dbformysql-flexibleserver-module-owners-tf` `@Azure/avm-res-dbformysql-flexibleserver-module-contributors-tf`
40	avm-res-dbforpostgresql-flexibleserver	`@Azure/avm-res-dbforpostgresql-flexibleserver-module-owners-tf` `@Azure/avm-res-dbforpostgresql-flexibleserver-module-contributors-tf`
41	avm-res-desktopvirtualization-applicationgroup	`@Azure/avm-res-desktopvirtualization-applicationgroup-module-owners-tf` `@Azure/avm-res-desktopvirtualization-applicationgroup-module-contributors-tf`
42	avm-res-desktopvirtualization-hostpool	`@Azure/avm-res-desktopvirtualization-hostpool-module-owners-tf` `@Azure/avm-res-desktopvirtualization-hostpool-module-contributors-tf`
43	avm-res-desktopvirtualization-scalingplan	`@Azure/avm-res-desktopvirtualization-scalingplan-module-owners-tf` `@Azure/avm-res-desktopvirtualization-scalingplan-module-contributors-tf`
44	avm-res-desktopvirtualization-workspace	`@Azure/avm-res-desktopvirtualization-workspace-module-owners-tf` `@Azure/avm-res-desktopvirtualization-workspace-module-contributors-tf`
45	avm-res-devcenter-devcenter	`@Azure/avm-res-devcenter-devcenter-module-owners-tf` `@Azure/avm-res-devcenter-devcenter-module-contributors-tf`
46	avm-res-devopsinfrastructure-pool	`@Azure/avm-res-devopsinfrastructure-pool-module-owners-tf` `@Azure/avm-res-devopsinfrastructure-pool-module-contributors-tf`
47	avm-res-devtestlab-lab	`@Azure/avm-res-devtestlab-lab-module-owners-tf` `@Azure/avm-res-devtestlab-lab-module-contributors-tf`
48	avm-res-digitaltwins-digitaltwinsinstance	`@Azure/avm-res-digitaltwins-digitaltwinsinstance-module-owners-tf` `@Azure/avm-res-digitaltwins-digitaltwinsinstance-module-contributors-tf`
49	avm-res-documentdb-databaseaccount	`@Azure/avm-res-documentdb-databaseaccount-module-owners-tf` `@Azure/avm-res-documentdb-databaseaccount-module-contributors-tf`
50	avm-res-edge-site	`@Azure/avm-res-edge-site-module-owners-tf` `@Azure/avm-res-edge-site-module-contributors-tf`
51	avm-res-eventgrid-domain	`@Azure/avm-res-eventgrid-domain-module-owners-tf` `@Azure/avm-res-eventgrid-domain-module-contributors-tf`
52	avm-res-eventgrid-namespace	`@Azure/avm-res-eventgrid-namespace-module-owners-tf` `@Azure/avm-res-eventgrid-namespace-module-contributors-tf`
53	avm-res-eventgrid-systemtopic	`@Azure/avm-res-eventgrid-systemtopic-module-owners-tf` `@Azure/avm-res-eventgrid-systemtopic-module-contributors-tf`
54	avm-res-eventgrid-topic	`@Azure/avm-res-eventgrid-topic-module-owners-tf` `@Azure/avm-res-eventgrid-topic-module-contributors-tf`
55	avm-res-eventhub-namespace	`@Azure/avm-res-eventhub-namespace-module-owners-tf` `@Azure/avm-res-eventhub-namespace-module-contributors-tf`
56	avm-res-healthbot-healthbot	`@Azure/avm-res-healthbot-healthbot-module-owners-tf` `@Azure/avm-res-healthbot-healthbot-module-contributors-tf`
57	avm-res-hybridcompute-machine	`@Azure/avm-res-hybridcompute-machine-module-owners-tf` `@Azure/avm-res-hybridcompute-machine-module-contributors-tf`
58	avm-res-hybridcontainerservice-provisionedclusterinstance	`@Azure/avm-res-hybridcontainerservice-provisionedclusterinstance-module-owners-tf` `@Azure/avm-res-hybridcontainerservice-provisionedclusterinstance-module-contributors-tf`
59	avm-res-insights-actiongroup	`@Azure/avm-res-insights-actiongroup-module-owners-tf` `@Azure/avm-res-insights-actiongroup-module-contributors-tf`
60	avm-res-insights-activitylogalert	`@Azure/avm-res-insights-activitylogalert-module-owners-tf` `@Azure/avm-res-insights-activitylogalert-module-contributors-tf`
61	avm-res-insights-alertrule	`@Azure/avm-res-insights-alertrule-module-owners-tf` `@Azure/avm-res-insights-alertrule-module-contributors-tf`
62	avm-res-insights-autoscalesetting	`@Azure/avm-res-insights-autoscalesetting-module-owners-tf` `@Azure/avm-res-insights-autoscalesetting-module-contributors-tf`
63	avm-res-insights-component	`@Azure/avm-res-insights-component-module-owners-tf` `@Azure/avm-res-insights-component-module-contributors-tf`
64	avm-res-insights-datacollectionendpoint	`@Azure/avm-res-insights-datacollectionendpoint-module-owners-tf` `@Azure/avm-res-insights-datacollectionendpoint-module-contributors-tf`
65	avm-res-insights-datacollectionrule	`@Azure/avm-res-insights-datacollectionrule-module-owners-tf` `@Azure/avm-res-insights-datacollectionrule-module-contributors-tf`
66	avm-res-insights-logprofile	`@Azure/avm-res-insights-logprofile-module-owners-tf` `@Azure/avm-res-insights-logprofile-module-contributors-tf`
67	avm-res-insights-metricalert	`@Azure/avm-res-insights-metricalert-module-owners-tf` `@Azure/avm-res-insights-metricalert-module-contributors-tf`
68	avm-res-insights-privatelinkscope	`@Azure/avm-res-insights-privatelinkscope-module-owners-tf` `@Azure/avm-res-insights-privatelinkscope-module-contributors-tf`
69	avm-res-insights-scheduledqueryrule	`@Azure/avm-res-insights-scheduledqueryrule-module-owners-tf` `@Azure/avm-res-insights-scheduledqueryrule-module-contributors-tf`
70	avm-res-keyvault-vault	`@Azure/avm-res-keyvault-vault-module-owners-tf` `@Azure/avm-res-keyvault-vault-module-contributors-tf`
71	avm-res-kusto-cluster	`@Azure/avm-res-kusto-cluster-module-owners-tf` `@Azure/avm-res-kusto-cluster-module-contributors-tf`
72	avm-res-loadtestservice-loadtest	`@Azure/avm-res-loadtestservice-loadtest-module-owners-tf` `@Azure/avm-res-loadtestservice-loadtest-module-contributors-tf`
73	avm-res-logic-workflow	`@Azure/avm-res-logic-workflow-module-owners-tf` `@Azure/avm-res-logic-workflow-module-contributors-tf`
74	avm-res-machinelearningservices-workspace	`@Azure/avm-res-machinelearningservices-workspace-module-owners-tf` `@Azure/avm-res-machinelearningservices-workspace-module-contributors-tf`
75	avm-res-maintenance-maintenanceconfiguration	`@Azure/avm-res-maintenance-maintenanceconfiguration-module-owners-tf` `@Azure/avm-res-maintenance-maintenanceconfiguration-module-contributors-tf`
76	avm-res-managedidentity-userassignedidentity	`@Azure/avm-res-managedidentity-userassignedidentity-module-owners-tf` `@Azure/avm-res-managedidentity-userassignedidentity-module-contributors-tf`
77	avm-res-managedservices-registrationdefinition	`@Azure/avm-res-managedservices-registrationdefinition-module-owners-tf` `@Azure/avm-res-managedservices-registrationdefinition-module-contributors-tf`
78	avm-res-management-managementgroup	`@Azure/avm-res-management-managementgroup-module-owners-tf` `@Azure/avm-res-management-managementgroup-module-contributors-tf`
79	avm-res-netapp-netappaccount	`@Azure/avm-res-netapp-netappaccount-module-owners-tf` `@Azure/avm-res-netapp-netappaccount-module-contributors-tf`
80	avm-res-network-applicationgateway	`@Azure/avm-res-network-applicationgateway-module-owners-tf` `@Azure/avm-res-network-applicationgateway-module-contributors-tf`
81	avm-res-network-applicationgatewaywebapplicationfirewallpolicy	`@Azure/avm-res-network-applicationgatewaywebapplicationfirewallpolicy-module-owners-tf` `@Azure/avm-res-network-applicationgatewaywebapplicationfirewallpolicy-module-contributors-tf`
82	avm-res-network-applicationsecuritygroup	`@Azure/avm-res-network-applicationsecuritygroup-module-owners-tf` `@Azure/avm-res-network-applicationsecuritygroup-module-contributors-tf`
83	avm-res-network-azurefirewall	`@Azure/avm-res-network-azurefirewall-module-owners-tf` `@Azure/avm-res-network-azurefirewall-module-contributors-tf`
84	avm-res-network-bastionhost	`@Azure/avm-res-network-bastionhost-module-owners-tf` `@Azure/avm-res-network-bastionhost-module-contributors-tf`
85	avm-res-network-connection	`@Azure/avm-res-network-connection-module-owners-tf` `@Azure/avm-res-network-connection-module-contributors-tf`
86	avm-res-network-ddosprotectionplan	`@Azure/avm-res-network-ddosprotectionplan-module-owners-tf` `@Azure/avm-res-network-ddosprotectionplan-module-contributors-tf`
87	avm-res-network-dnsforwardingruleset	`@Azure/avm-res-network-dnsforwardingruleset-module-owners-tf` `@Azure/avm-res-network-dnsforwardingruleset-module-contributors-tf`
88	avm-res-network-dnsresolver	`@Azure/avm-res-network-dnsresolver-module-owners-tf` `@Azure/avm-res-network-dnsresolver-module-contributors-tf`
89	avm-res-network-dnszone	`@Azure/avm-res-network-dnszone-module-owners-tf` `@Azure/avm-res-network-dnszone-module-contributors-tf`
90	avm-res-network-expressroutecircuit	`@Azure/avm-res-network-expressroutecircuit-module-owners-tf` `@Azure/avm-res-network-expressroutecircuit-module-contributors-tf`
91	avm-res-network-firewallpolicy	`@Azure/avm-res-network-firewallpolicy-module-owners-tf` `@Azure/avm-res-network-firewallpolicy-module-contributors-tf`
92	avm-res-network-frontdoor	`@Azure/avm-res-network-frontdoor-module-owners-tf` `@Azure/avm-res-network-frontdoor-module-contributors-tf`
93	avm-res-network-frontdoorwebapplicationfirewallpolicy	`@Azure/avm-res-network-frontdoorwebapplicationfirewallpolicy-module-owners-tf` `@Azure/avm-res-network-frontdoorwebapplicationfirewallpolicy-module-contributors-tf`
94	avm-res-network-ipgroup	`@Azure/avm-res-network-ipgroup-module-owners-tf` `@Azure/avm-res-network-ipgroup-module-contributors-tf`
95	avm-res-network-loadbalancer	`@Azure/avm-res-network-loadbalancer-module-owners-tf` `@Azure/avm-res-network-loadbalancer-module-contributors-tf`
96	avm-res-network-localnetworkgateway	`@Azure/avm-res-network-localnetworkgateway-module-owners-tf` `@Azure/avm-res-network-localnetworkgateway-module-contributors-tf`
97	avm-res-network-natgateway	`@Azure/avm-res-network-natgateway-module-owners-tf` `@Azure/avm-res-network-natgateway-module-contributors-tf`
98	avm-res-network-networkinterface	`@Azure/avm-res-network-networkinterface-module-owners-tf` `@Azure/avm-res-network-networkinterface-module-contributors-tf`
99	avm-res-network-networkmanager	`@Azure/avm-res-network-networkmanager-module-owners-tf` `@Azure/avm-res-network-networkmanager-module-contributors-tf`
100	avm-res-network-networksecuritygroup	`@Azure/avm-res-network-networksecuritygroup-module-owners-tf` `@Azure/avm-res-network-networksecuritygroup-module-contributors-tf`
101	avm-res-network-networkwatcher	`@Azure/avm-res-network-networkwatcher-module-owners-tf` `@Azure/avm-res-network-networkwatcher-module-contributors-tf`
102	avm-res-network-privatednszone	`@Azure/avm-res-network-privatednszone-module-owners-tf` `@Azure/avm-res-network-privatednszone-module-contributors-tf`
103	avm-res-network-privateendpoint	`@Azure/avm-res-network-privateendpoint-module-owners-tf` `@Azure/avm-res-network-privateendpoint-module-contributors-tf`
104	avm-res-network-privatelinkservice	`@Azure/avm-res-network-privatelinkservice-module-owners-tf` `@Azure/avm-res-network-privatelinkservice-module-contributors-tf`
105	avm-res-network-publicipaddress	`@Azure/avm-res-network-publicipaddress-module-owners-tf` `@Azure/avm-res-network-publicipaddress-module-contributors-tf`
106	avm-res-network-publicipprefix	`@Azure/avm-res-network-publicipprefix-module-owners-tf` `@Azure/avm-res-network-publicipprefix-module-contributors-tf`
107	avm-res-network-routetable	`@Azure/avm-res-network-routetable-module-owners-tf` `@Azure/avm-res-network-routetable-module-contributors-tf`
108	avm-res-network-serviceendpointpolicy	`@Azure/avm-res-network-serviceendpointpolicy-module-owners-tf` `@Azure/avm-res-network-serviceendpointpolicy-module-contributors-tf`
109	avm-res-network-trafficmanagerprofile	`@Azure/avm-res-network-trafficmanagerprofile-module-owners-tf` `@Azure/avm-res-network-trafficmanagerprofile-module-contributors-tf`
110	avm-res-network-virtualnetwork	`@Azure/avm-res-network-virtualnetwork-module-owners-tf` `@Azure/avm-res-network-virtualnetwork-module-contributors-tf`
111	avm-res-network-virtualnetworkgateway	`@Azure/avm-res-network-virtualnetworkgateway-module-owners-tf` `@Azure/avm-res-network-virtualnetworkgateway-module-contributors-tf`
112	avm-res-network-virtualrouter	`@Azure/avm-res-network-virtualrouter-module-owners-tf` `@Azure/avm-res-network-virtualrouter-module-contributors-tf`
113	avm-res-operationalinsights-workspace	`@Azure/avm-res-operationalinsights-workspace-module-owners-tf` `@Azure/avm-res-operationalinsights-workspace-module-contributors-tf`
114	avm-res-operationsmanagement-solution	`@Azure/avm-res-operationsmanagement-solution-module-owners-tf` `@Azure/avm-res-operationsmanagement-solution-module-contributors-tf`
115	avm-res-oracledatabase-cloudexadatainfrastructure	`@Azure/avm-res-oracledatabase-cloudexadatainfrastructure-module-owners-tf` `@Azure/avm-res-oracledatabase-cloudexadatainfrastructure-module-contributors-tf`
116	avm-res-oracledatabase-cloudvmcluster	`@Azure/avm-res-oracledatabase-cloudvmcluster-module-owners-tf` `@Azure/avm-res-oracledatabase-cloudvmcluster-module-contributors-tf`
117	avm-res-portal-dashboard	`@Azure/avm-res-portal-dashboard-module-owners-tf` `@Azure/avm-res-portal-dashboard-module-contributors-tf`
118	avm-res-powerbidedicated-capacity	`@Azure/avm-res-powerbidedicated-capacity-module-owners-tf` `@Azure/avm-res-powerbidedicated-capacity-module-contributors-tf`
119	avm-res-purview-account	`@Azure/avm-res-purview-account-module-owners-tf` `@Azure/avm-res-purview-account-module-contributors-tf`
120	avm-res-recoveryservices-vault	`@Azure/avm-res-recoveryservices-vault-module-owners-tf` `@Azure/avm-res-recoveryservices-vault-module-contributors-tf`
121	avm-res-redhatopenShift-openshiftcluster	`@Azure/avm-res-redhatopenShift-openshiftcluster-module-owners-tf` `@Azure/avm-res-redhatopenShift-openshiftcluster-module-contributors-tf`
122	avm-res-relay-namespace	`@Azure/avm-res-relay-namespace-module-owners-tf` `@Azure/avm-res-relay-namespace-module-contributors-tf`
123	avm-res-resourcegraph-query	`@Azure/avm-res-resourcegraph-query-module-owners-tf` `@Azure/avm-res-resourcegraph-query-module-contributors-tf`
124	avm-res-resources-resourcegroup	`@Azure/avm-res-resources-resourcegroup-module-owners-tf` `@Azure/avm-res-resources-resourcegroup-module-contributors-tf`
125	avm-res-search-searchservice	`@Azure/avm-res-search-searchservice-module-owners-tf` `@Azure/avm-res-search-searchservice-module-contributors-tf`
126	avm-res-servicebus-namespace	`@Azure/avm-res-servicebus-namespace-module-owners-tf` `@Azure/avm-res-servicebus-namespace-module-contributors-tf`
127	avm-res-servicefabric-cluster	`@Azure/avm-res-servicefabric-cluster-module-owners-tf` `@Azure/avm-res-servicefabric-cluster-module-contributors-tf`
128	avm-res-servicenetworking-trafficcontroller	`@Azure/avm-res-servicenetworking-trafficcontroller-module-owners-tf` `@Azure/avm-res-servicenetworking-trafficcontroller-module-contributors-tf`
129	avm-res-signalrservice-signalr	`@Azure/avm-res-signalrservice-signalr-module-owners-tf` `@Azure/avm-res-signalrservice-signalr-module-contributors-tf`
130	avm-res-sql-instancepool	`@Azure/avm-res-sql-instancepool-module-owners-tf` `@Azure/avm-res-sql-instancepool-module-contributors-tf`
131	avm-res-sql-managedinstance	`@Azure/avm-res-sql-managedinstance-module-owners-tf` `@Azure/avm-res-sql-managedinstance-module-contributors-tf`
132	avm-res-sql-server	`@Azure/avm-res-sql-server-module-owners-tf` `@Azure/avm-res-sql-server-module-contributors-tf`
133	avm-res-sqlvirtualmachine-sqlvirtualmachine	`@Azure/avm-res-sqlvirtualmachine-sqlvirtualmachine-module-owners-tf` `@Azure/avm-res-sqlvirtualmachine-sqlvirtualmachine-module-contributors-tf`
134	avm-res-storage-storageaccount	`@Azure/avm-res-storage-storageaccount-module-owners-tf` `@Azure/avm-res-storage-storageaccount-module-contributors-tf`
135	avm-res-synapse-workspace	`@Azure/avm-res-synapse-workspace-module-owners-tf` `@Azure/avm-res-synapse-workspace-module-contributors-tf`
136	avm-res-virtualmachineimages-imagetemplate	`@Azure/avm-res-virtualmachineimages-imagetemplate-module-owners-tf` `@Azure/avm-res-virtualmachineimages-imagetemplate-module-contributors-tf`
137	avm-res-web-connection	`@Azure/avm-res-web-connection-module-owners-tf` `@Azure/avm-res-web-connection-module-contributors-tf`
138	avm-res-web-hostingenvironment	`@Azure/avm-res-web-hostingenvironment-module-owners-tf` `@Azure/avm-res-web-hostingenvironment-module-contributors-tf`
139	avm-res-web-serverfarm	`@Azure/avm-res-web-serverfarm-module-owners-tf` `@Azure/avm-res-web-serverfarm-module-contributors-tf`
140	avm-res-web-site	`@Azure/avm-res-web-site-module-owners-tf` `@Azure/avm-res-web-site-module-contributors-tf`
141	avm-res-web-staticsite	`@Azure/avm-res-web-staticsite-module-owners-tf` `@Azure/avm-res-web-staticsite-module-contributors-tf`

Terraform Pattern Modules

Module catalog

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Terraform	Pattern	23	17	40

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Info

This page contains various views of the module index (catalog) for Terraform Pattern Modules. To see these views, click on the expandable sections with the “➕” sign below.

To see the full, unfiltered, unformatted module index on GitHub, click here.
To download the source CSV file, click here.

Note

Published modules - 🟢 & 🟡

➕ Published Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Primary Owner
01	avm-ptn-aks-dev	📄	AKS dev	ms-henglu Heng Lu
02	avm-ptn-aks-economy	📄	AKS economy	ms-henglu Heng Lu
03	avm-ptn-aks-enterprise	📄	AKS Enterprise	ms-henglu Heng Lu
04	avm-ptn-aks-production	📄	Azure Kubernetes Service	zioproto Saverio Proto
05	avm-ptn-alz	📄	Azure Landing Zone	matt-FFFFFF Matt White
06	avm-ptn-alz-connectivity-hub-and-spoke-vnet	📄	ALZ Connectivity Hub and Spoke Azure Landing Zones - Hub and Spoke	jaredfholgate Jared Holgate
07	avm-ptn-alz-connectivity-virtual-wan	📄	ALZ Connectivity vWAN Azure Landing Zones - vWAN	jaredfholgate Jared Holgate
08	avm-ptn-alz-management	📄	ALZ Management Azure Landing Zones - Management	luke-taylor Luke Taylor
09	avm-ptn-avd-lza-insights	📄	AVD Insights Azure Virtual Desktop Insights	jensheerin Jen Sheerin
10	avm-ptn-avd-lza-managementplane	📄	AVD Management Plane Azure Virtual Desktop Management Plane	jensheerin Jen Sheerin
11	avm-ptn-azuremonitorwindowsagent	📄	Azure Monitor Windows Agent	xhy8759 Hangyu Xu
12	avm-ptn-cicd-agents-and-runners	📄	CI CD Agents and Runners	jaredfholgate Jared Holgate
13	avm-ptn-function-app-storage-private-endpoints	📄	Function App and private endpoint-secured Storage	donovm4 Donovan McCoy
14	avm-ptn-hci-ad-provisioner	📄	Arc for AD registration	xhy8759 Hangyu Xu
15	avm-ptn-hci-server-provisioner	📄	Arc for Server registration	xhy8759 Hangyu Xu
16	avm-ptn-hubnetworking	📄	Hub Networking	jaredfholgate Jared Holgate
17	avm-ptn-monitoring-amba-alz	📄	AMBA ALZ Pattern Azure Monitor Baseline Alerts - Azure Landing Zones Pattern	arjenhuitema Arjen Huitema
18	avm-ptn-network-private-link-private-dns-zones	📄	Private Link Private DNS Zones	jtracey93 Jack Tracey
19	avm-ptn-network-routeserver	📄	Azure Route Server	jchancellor-ms Jon Chancellor
20	avm-ptn-odaa	📄	Oracle Exedata Workload	terrymandin Terry Mandin
21	avm-ptn-policyassignment	📄	Policy assignment	steph409 Stephanie Lanius bjornhofer Bjorn Hofer
22	avm-ptn-virtualwan	📄	Virtual WAN vWAN	khushal08 Khush Kaviraj
23	avm-ptn-vnetgateway	📄	Virtual Network Gateway VNET GW	luke-taylor Luke Taylor matt-FFFFFF Matt White

Proposed modules - ⚪

➕ Proposed Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Status & Versions	Primary Owner
01	avm-ptn-ai-platform-baseline	n/a	AI platform baseline		Nepomuceno Gabriel Monteiro Nepomuceno
02	avm-ptn-aiml-ai-foundry	n/a	AI-ML - AI Foundry		mikestiers Mike Stiers
03	avm-ptn-aiml-landing-zone	n/a	AI-ML - Landing Zone (LZ)		mbilalamjad Bilal Amjad
04	avm-ptn-avd-lza-sessionhosts	n/a	AVD Session Hosts Azure Virtual Desktop Session Hosts
05	avm-ptn-azure-ipam	n/a	IPAM IP Address Management		pagyP Paul Paginton
06	avm-ptn-bcdr-vm-replication	n/a	Azure Site Recovery VM Replication		FreddyAyala Freddy Ayala
07	avm-ptn-cicd-bootstrap	n/a	CI CD bootstrap		luke-taylor Luke Taylor
08	avm-ptn-confidential-compute	n/a	Azure Confidential Compute		humblejay Kunal Pole
09	avm-ptn-finopstoolkit-finopshub	n/a	FinOps Hubs		didayal-msft Divyadeep Dayal
10	avm-ptn-lbvmss	n/a	Virtual Machine Scale Set		terrymandin Terry Mandin
11	avm-ptn-monitoring-amba	n/a	AMBA Azure Monitor Baseline Alerts		arjenhuitema Arjen Huitema
12	avm-ptn-odaa-identity	n/a	Oracle Identity		terrymandin Terry Mandin
13	avm-ptn-openai-cognitivesearch	n/a	Corporate Line of Business (LoB) ChatBot		mikestiers Mike Stiers
14	avm-ptn-openai-e2e-baseline	n/a	Baseline OpenAI end-to-end chat
15	avm-ptn-oracle-iaas	n/a	Oracle Database on Azure		sihbher Gerardo Reyes
16	avm-ptn-sentinel-solutions	n/a	Sentinel Solutions		LaurentLesle Laurent Lesle
17	avm-ptn-subnets-nsgs-routes	n/a	Network Security Groups NSG		swathialuganti Swathi Aluganti Narasimhulu
18	❌ None listed	❌ None listed	❌ None listed	❌ None listed	❌ None listed

Deprecated modules - 🔴

➕ Deprecated Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Status & Versions	Primary Owner
01	❌ None listed	❌ None listed	❌ None listed	❌ None listed	❌ None listed

All modules - 📇

➕ All Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Primary Owner
01	avm-ptn-ai-platform-baseline	n/a	AI platform baseline	Nepomuceno Gabriel Monteiro Nepomuceno
02	avm-ptn-aiml-ai-foundry	n/a	AI-ML - AI Foundry	mikestiers Mike Stiers
03	avm-ptn-aiml-landing-zone	n/a	AI-ML - Landing Zone (LZ)	mbilalamjad Bilal Amjad
04	avm-ptn-aks-dev	📄	AKS dev	ms-henglu Heng Lu
05	avm-ptn-aks-economy	📄	AKS economy	ms-henglu Heng Lu
06	avm-ptn-aks-enterprise	📄	AKS Enterprise	ms-henglu Heng Lu
07	avm-ptn-aks-production	📄	Azure Kubernetes Service	zioproto Saverio Proto
08	avm-ptn-alz	📄	Azure Landing Zone	matt-FFFFFF Matt White
09	avm-ptn-alz-connectivity-hub-and-spoke-vnet	📄	ALZ Connectivity Hub and Spoke Azure Landing Zones - Hub and Spoke	jaredfholgate Jared Holgate
10	avm-ptn-alz-connectivity-virtual-wan	📄	ALZ Connectivity vWAN Azure Landing Zones - vWAN	jaredfholgate Jared Holgate
11	avm-ptn-alz-management	📄	ALZ Management Azure Landing Zones - Management	luke-taylor Luke Taylor
12	avm-ptn-avd-lza-insights	📄	AVD Insights Azure Virtual Desktop Insights	jensheerin Jen Sheerin
13	avm-ptn-avd-lza-managementplane	📄	AVD Management Plane Azure Virtual Desktop Management Plane	jensheerin Jen Sheerin
14	avm-ptn-avd-lza-sessionhosts	n/a	AVD Session Hosts Azure Virtual Desktop Session Hosts
15	avm-ptn-azure-ipam	n/a	IPAM IP Address Management	pagyP Paul Paginton
16	avm-ptn-azuremonitorwindowsagent	📄	Azure Monitor Windows Agent	xhy8759 Hangyu Xu
17	avm-ptn-bcdr-vm-replication	n/a	Azure Site Recovery VM Replication	FreddyAyala Freddy Ayala
18	avm-ptn-cicd-agents-and-runners	📄	CI CD Agents and Runners	jaredfholgate Jared Holgate
19	avm-ptn-cicd-bootstrap	n/a	CI CD bootstrap	luke-taylor Luke Taylor
20	avm-ptn-confidential-compute	n/a	Azure Confidential Compute	humblejay Kunal Pole
21	avm-ptn-finopstoolkit-finopshub	n/a	FinOps Hubs	didayal-msft Divyadeep Dayal
22	avm-ptn-function-app-storage-private-endpoints	📄	Function App and private endpoint-secured Storage	donovm4 Donovan McCoy
23	avm-ptn-hci-ad-provisioner	📄	Arc for AD registration	xhy8759 Hangyu Xu
24	avm-ptn-hci-server-provisioner	📄	Arc for Server registration	xhy8759 Hangyu Xu
25	avm-ptn-hubnetworking	📄	Hub Networking	jaredfholgate Jared Holgate
26	avm-ptn-lbvmss	n/a	Virtual Machine Scale Set	terrymandin Terry Mandin
27	avm-ptn-monitoring-amba	n/a	AMBA Azure Monitor Baseline Alerts	arjenhuitema Arjen Huitema
28	avm-ptn-monitoring-amba-alz	📄	AMBA ALZ Pattern Azure Monitor Baseline Alerts - Azure Landing Zones Pattern	arjenhuitema Arjen Huitema
29	avm-ptn-network-private-link-private-dns-zones	📄	Private Link Private DNS Zones	jtracey93 Jack Tracey
30	avm-ptn-network-routeserver	📄	Azure Route Server	jchancellor-ms Jon Chancellor
31	avm-ptn-odaa	📄	Oracle Exedata Workload	terrymandin Terry Mandin
32	avm-ptn-odaa-identity	n/a	Oracle Identity	terrymandin Terry Mandin
33	avm-ptn-openai-cognitivesearch	n/a	Corporate Line of Business (LoB) ChatBot	mikestiers Mike Stiers
34	avm-ptn-openai-e2e-baseline	n/a	Baseline OpenAI end-to-end chat
35	avm-ptn-oracle-iaas	n/a	Oracle Database on Azure	sihbher Gerardo Reyes
36	avm-ptn-policyassignment	📄	Policy assignment	steph409 Stephanie Lanius bjornhofer Bjorn Hofer
37	avm-ptn-sentinel-solutions	n/a	Sentinel Solutions	LaurentLesle Laurent Lesle
38	avm-ptn-subnets-nsgs-routes	n/a	Network Security Groups NSG	swathialuganti Swathi Aluganti Narasimhulu
39	avm-ptn-virtualwan	📄	Virtual WAN vWAN	khushal08 Khush Kaviraj
40	avm-ptn-vnetgateway	📄	Virtual Network Gateway VNET GW	luke-taylor Luke Taylor matt-FFFFFF Matt White

Module Publication History - 📅

➕ Module Publication History - Module names, status and owners

Modules published in April 2025

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-ptn-alz-connectivity-virtual-wan	📄	ALZ Connectivity vWAN Azure Landing Zones - vWAN	jaredfholgate Jared Holgate
02	avm-ptn-function-app-storage-private-endpoints	📄	Function App and private endpoint-secured Storage	donovm4 Donovan McCoy
03	avm-ptn-monitoring-amba-alz	📄	AMBA ALZ Pattern Azure Monitor Baseline Alerts - Azure Landing Zones Pattern	arjenhuitema Arjen Huitema

Modules published in March 2025

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-alz-connectivity-hub-and-spoke-vnet	📄	ALZ Connectivity Hub and Spoke Azure Landing Zones - Hub and Spoke		jaredfholgate Jared Holgate

Modules published in November 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-aks-economy	📄	AKS economy		ms-henglu Heng Lu
02	avm-ptn-aks-enterprise	📄	AKS Enterprise		ms-henglu Heng Lu

Modules published in October 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-ptn-aks-dev	📄	AKS dev	ms-henglu Heng Lu
02	avm-ptn-odaa	📄	Oracle Exedata Workload	terrymandin Terry Mandin
03	avm-ptn-policyassignment	📄	Policy assignment	steph409 Stephanie Lanius bjornhofer Bjorn Hofer

Modules published in September 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-hubnetworking	📄	Hub Networking		jaredfholgate Jared Holgate

Modules published in August 2024

No.	Module Name	Source Code	Display Name	Owner(s)
01	avm-ptn-azuremonitorwindowsagent	📄	Azure Monitor Windows Agent	xhy8759 Hangyu Xu
02	avm-ptn-cicd-agents-and-runners	📄	CI CD Agents and Runners	jaredfholgate Jared Holgate
03	avm-ptn-hci-ad-provisioner	📄	Arc for AD registration	xhy8759 Hangyu Xu
04	avm-ptn-hci-server-provisioner	📄	Arc for Server registration	xhy8759 Hangyu Xu

Modules published in June 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-network-private-link-private-dns-zones	📄	Private Link Private DNS Zones		jtracey93 Jack Tracey
02	avm-ptn-network-routeserver	📄	Azure Route Server		jchancellor-ms Jon Chancellor

Modules published in May 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-avd-lza-insights	📄	AVD Insights Azure Virtual Desktop Insights		jensheerin Jen Sheerin
02	avm-ptn-avd-lza-managementplane	📄	AVD Management Plane Azure Virtual Desktop Management Plane		jensheerin Jen Sheerin

Modules published in April 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-aks-production	📄	Azure Kubernetes Service		zioproto Saverio Proto

Modules published in December 2023

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-alz-management	📄	ALZ Management Azure Landing Zones - Management		luke-taylor Luke Taylor

Modules published in November 2023

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-alz	📄	Azure Landing Zone		matt-FFFFFF Matt White
02	avm-ptn-vnetgateway	📄	Virtual Network Gateway VNET GW		luke-taylor Luke Taylor matt-FFFFFF Matt White

Modules published in October 2023

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-ptn-virtualwan	📄	Virtual WAN vWAN		khushal08 Khush Kaviraj

For Module Owners & Contributors

Note

This section is mainly intended for module owners and contributors as it contains information about the GitHub Teams for Owners & Contributors.

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

➕ All Modules - Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

No.	Module Name	GitHub Teams for Module Owners and Contributors
01	avm-ptn-ai-platform-baseline
02	avm-ptn-aiml-ai-foundry
03	avm-ptn-aiml-landing-zone
04	avm-ptn-aks-dev
05	avm-ptn-aks-economy
06	avm-ptn-aks-enterprise
07	avm-ptn-aks-production
08	avm-ptn-alz
09	avm-ptn-alz-connectivity-hub-and-spoke-vnet
10	avm-ptn-alz-connectivity-virtual-wan
11	avm-ptn-alz-management
12	avm-ptn-avd-lza-insights
13	avm-ptn-avd-lza-managementplane
14	avm-ptn-avd-lza-sessionhosts
15	avm-ptn-azure-ipam
16	avm-ptn-azuremonitorwindowsagent
17	avm-ptn-bcdr-vm-replication
18	avm-ptn-cicd-agents-and-runners
19	avm-ptn-cicd-bootstrap
20	avm-ptn-confidential-compute
21	avm-ptn-finopstoolkit-finopshub
22	avm-ptn-function-app-storage-private-endpoints
23	avm-ptn-hci-ad-provisioner
24	avm-ptn-hci-server-provisioner
25	avm-ptn-hubnetworking
26	avm-ptn-lbvmss
27	avm-ptn-monitoring-amba
28	avm-ptn-monitoring-amba-alz
29	avm-ptn-network-private-link-private-dns-zones
30	avm-ptn-network-routeserver
31	avm-ptn-odaa
32	avm-ptn-odaa-identity
33	avm-ptn-openai-cognitivesearch
34	avm-ptn-openai-e2e-baseline
35	avm-ptn-oracle-iaas
36	avm-ptn-policyassignment
37	avm-ptn-sentinel-solutions
38	avm-ptn-subnets-nsgs-routes
39	avm-ptn-virtualwan
40	avm-ptn-vnetgateway

Terraform Utility Modules

Module catalog

Language	Classification	Published 🟢 & 🟡	Proposed ⚪	SUM
Terraform	Utility	4	1	5

➕ Additional information

Legend

Summary of status icons used on this page

Icon	Status	Description
⚪	Proposed modules	Modules that are proposed and/or being worked on but not published yet.
🟢 & 🟡	Published modules	Available (🟢) and Orphaned (🟡) modules that are active and usable.
🔴	Deprecated modules	Modules that reached the end of their lifecycle.
📇	All modules	Including Published, Proposed and Deprecated ones.

See the Module Lifecycle page for more details.

Info

This page contains various views of the module index (catalog) for Terraform Utility Modules. To see these views, click on the expandable sections with the “➕” sign below.

To see the full, unfiltered, unformatted module index on GitHub, click here.
To download the source CSV file, click here.

Note

Published modules - 🟢 & 🟡

➕ Published Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Primary Owner
01	avm-utl-interfaces	📄	AVM Interfaces	matt-FFFFFF Matt White
02	avm-utl-network-ip-addresses	📄	AVM Network IP Addresses IPv4 CIDR	jaredfholgate Jared Holgate
03	avm-utl-regions	📄	Azure Regions Data	matt-FFFFFF Matt White
04	avm-utl-sku-finder	📄	AVM SKU Finder Sku	jchancellor-ms Jon Chancellor

Proposed modules - ⚪

➕ Proposed Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Status & Versions	Primary Owner
01	avm-utl-naming	n/a	Module Naming		Nepomuceno Gabriel Monteiro Nepomuceno
02	❌ None listed	❌ None listed	❌ None listed	❌ None listed	❌ None listed

Deprecated modules - 🔴

➕ Deprecated Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Status & Versions	Primary Owner
01	❌ None listed	❌ None listed	❌ None listed	❌ None listed	❌ None listed

All modules - 📇

➕ All Modules - Module names, status and owners

No.	Module Name	Source Code	Display Name	Primary Owner
01	avm-utl-interfaces	📄	AVM Interfaces	matt-FFFFFF Matt White
02	avm-utl-naming	n/a	Module Naming	Nepomuceno Gabriel Monteiro Nepomuceno
03	avm-utl-network-ip-addresses	📄	AVM Network IP Addresses IPv4 CIDR	jaredfholgate Jared Holgate
04	avm-utl-regions	📄	Azure Regions Data	matt-FFFFFF Matt White
05	avm-utl-sku-finder	📄	AVM SKU Finder Sku	jchancellor-ms Jon Chancellor

Module Publication History - 📅

➕ Module Publication History - Module names, status and owners

Modules published in March 2025

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-utl-network-ip-addresses	📄	AVM Network IP Addresses IPv4 CIDR		jaredfholgate Jared Holgate

Modules published in January 2025

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-utl-interfaces	📄	AVM Interfaces		matt-FFFFFF Matt White

Modules published in December 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-utl-sku-finder	📄	AVM SKU Finder Sku		jchancellor-ms Jon Chancellor

Modules published in August 2024

No.	Module Name	Source Code	Display Name	Status & Versions	Owner(s)
01	avm-utl-regions	📄	Azure Regions Data		matt-FFFFFF Matt White

For Module Owners & Contributors

Note

This section is mainly intended for module owners and contributors as it contains information about the GitHub Teams for Owners & Contributors.

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

➕ All Modules - Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

No.	Module Name	GitHub Teams for Module Owners and Contributors
01	avm-utl-interfaces
02	avm-utl-naming
03	avm-utl-network-ip-addresses
04	avm-utl-regions
05	avm-utl-sku-finder

Usage Guide

Summary

This section describes usage guidance.

Concepts

Note

This page is a work in progress and will be updated as we improve & finalize the content. Please check back regularly for updates.

When developing an Azure solution using AVM modules, there are several aspects to consider. This page covers important concepts and provides guidance the technical decisions. Each concept/topic referenced here will be further detailed in the corresponding Bicep or Terraform specific guidance.

Language-agnostic concepts

Topics/concepts that are relevant and applicable for both Bicep and Terraform.

Module Sourcing

Public Registry

Leveraging the public registries (i.e., the Bicep Public Registry or the Terraform Public Registry) is the most common and recommended approach.

This allows you to leverage the latest and greatest features of the AVM modules, as well as the latest security updates. While there aren’t any prerequisites for using the public registry - no extra software component or service needs to be installed and no configuration is needed - the client machine the deployment is initiated from will need to have access to the public registry.

Private Registry (synced)

A private registry - that is hosted in your own environment - can store modules originating from the public registry. Using a private registry still grants you the latest version of AVM modules while allowing you to review each version of each module before admitting them to your private registry. You also have control over who can access your own private registry. Note that using a private registry means that you’re still using each module as is, without making any changes.

Inner-sourcing

Inner-sourcing AVM means maintaining your own, synchronized copy of AVM modules in your own internal private registry, repositories or other storage option. Customers normally look to inner-source AVM modules when they have strict security and compliance requirements, or when they want to publish their own lightly wrapped versions of the modules to meet their specific needs; for example changing some allowed or default values for parameter or variable inputs.

This is a more complex approach and requires more effort to maintain, but it can be beneficial in certain scenarios, however, it should not be the default approach as it can lead to a lot of overhead and maintenance and requires significant skills and resources to set up and maintain.

There are many ways to approach inner-sourcing AVM modules for both Bicep and Terraform. The AVM team will be publishing guidance on this topic, based on customer experience and learnings.

Tip

You can see the AVM team talking about inner-sourcing on the AVM February 2025 community call on YouTube.

Solution Development

This section provides advanced guidance for developing solutions using Azure Verified Modules (AVM). It covers technical decisions and concepts that are important for building and deploying Azure solutions using AVM modules.

Planning your solution

When implementing infrastructure in Azure leveraging IaaS and PaaS services, there are multiple options for Azure deployments. In this article we assume that a decision has been made to implement your solution, using Infrastructure-as-Code (IaC). This is best suited to allow programmatic declarative control of the target infrastructure and is ideal for projects that require repeatability and idempotency.

Choosing an Infrastructure-as-Code language

There are multiple language choices when implementing your solution using IaC in Azure. The Azure Verified Modules project currently supports Bicep and Terraform. The following guidance summarizes considerations that can help choose the option that best suits your requirements.

Reasons to choose Bicep

Bicep is the Microsoft 1st party offering for IaC deployments. It supports Generally Available (GA) and preview features for all Azure resources and allows for modular composition of resources and solution templates. The use of simplified syntax makes IaC development intuitive and the use of the Bicep extension for VSCode provides IntelliSense and syntax validation to assist with coding. Finally, Bicep is well suited for infrastructure projects and teams that don’t require management of other cloud platforms or services outside of Azure. For a more detailed read on reasons to choose Bicep, read this article from the Bicep documentation.

Reasons to choose Terraform

HashiCorp’s Terraform is an extensible 3rd party platform that can be used across multiple cloud and on-premises platforms using multiple provider plugins. It has widespread adoption due to its simplified human-readable configuration files, common functionality, and the ability to allow a project to span multiple provider spaces.

In Azure, support is provided through two primary providers called AzureRM and AzAPI respectively. The default provider for many Azure use cases is AzureRM which is co-developed between Microsoft and HashiCorp. It includes support for generally available (GA) features, while support for new and preview features might be slightly delayed following their initial release. AzAPI is developed exclusively by Microsoft and supports all preview and GA features while being more complex to use due to the more direct interaction with Azure’s APIs. While it is possible to use both providers in a single project as needed, the best practice is to standardize on a single provider as much as is reasonable.

Projects typically choose Terraform when they bridge multiple cloud infrastructure platforms or when the development team has previous experience coding in Terraform. Modern Integrated Development Environments (IDE) - such as Visual Studio Code - include extension support for Terraform features as well as additional Azure specific extensions. These extensions enable syntax validation and highlighting as well as code formatting and HashiCorp Cloud Platform (HCP) integration for HashiCorp Cloud customers. For a more detailed read on reasons to choose Terraform, read this article from the Terraform on Azure documentation.

Architecture design

Before starting the process of codifying infrastructure, it is important to develop a detailed architecture of what will be created. This should include details for:

Organizational elements such as management groups, subscriptions, and resource groups as well as any tagging and Role Based Access (RBAC) configurations for each.
Infrastructure services that will be created along with key configuration details like sku values, network CIDR range sizes, or other solution specific configuration.
Any relationship between services that will be codified as part of the deployment.
Identify inputs to your solution for designs that are intended to be used as templates.

Note

For a production grade solution, you need to

follow the recommendations of the Cloud Adoption Framework (CAF) and have your platform and application landing zones defined, as per Azure Landing Zones (ALZ);
follow the recommendations of the Azure Well-Architected Framework (WAF) to ensure that your solution is compliant with and integrates into your organization’s policies and standards. This includes considerations for security, identity, networking, monitoring, cost management, and governance.

Sourcing content for deployment

Once the architecture is agreed upon, it is time to plan the development of your IaC code. There are several key decision points that should be considered during this phase.

Content creation methods

The two primary methods used to create your solutions module are:

Using base resources (“vanilla resources”) from scratch or
Leveraging pre-created modules from the AVM library to minimize the time to value during development.

The trade-off between the two options is primarily around control vs. speed. AVM works to provide the best of both options by providing modules with opinionated and recommended practice defaults while allowing for more detailed configuration as needed. In our sample exercise we’ll be using AVM modules to demonstrate building the example solution.

AVM module type considerations

When using AVM modules for your solution, there is an additional choice that should be considered. The AVM library includes both pattern and resource module types. If your architecture includes or follows a well-known pattern then a pattern module may be the right option for you. If you determine this is the case, then search the module index for pattern modules in your chosen language to see if an option exists for your scenario. Otherwise, using resource modules from the library will be your best option.

In cases where an AVM resource or pattern module isn’t available for use, review the Bicep or Terraform provider documentation to identify how to augment AVM modules with standalone resources. If you feel that additional resource or pattern modules would be useful, you can also request the creation of a pattern or resource module by creating a module proposal issue on the AVM github repository.

Module source considerations

Once the decision has been made to use AVM modules to help accelerate solution development, a decision about where those modules will be sourced from is the next key decision point. A detailed exploration of the different sourcing options can be found in the Module Sourcing section of the Concepts page. Take a moment to review the options discussed there.

For our solution we will leverage the Public Registry option by sourcing AVM modules directly from the respective Terraform and Bicep public registries. This will avoid the need to fork copies of the modules for private use.

Bicep - Solution Development

Introduction

Azure Verified Modules (AVM) for Bicep are a powerful tool that leverage the Bicep domain-specific language (DSL), industry knowledge, and an Open Source community, which altogether enable developers to quickly deploy Azure resources that follow Microsoft’s recommended practices for Azure.
In this article, we will walk through the Bicep specific considerations and recommended practices on developing your solution leveraging Azure Verified Modules. We’ll review some of the design features and trade-offs and include sample code to illustrate each discussion point.

In this tutorial, we will:

Deploy a basic Virtual Machine architecture into Azure
Explore recommended practices related to Bicep template development
Demonstrate the ease with which you can deploy AVM modules
Describe each of the development and deployment steps in detail

After completing this tutorial, you’ll have a working knowledge of:

How to discover and add AVM modules to your Bicep template
How to reference and use outputs across AVM modules
Recommended practices for parameterization and structure of your Bicep file
Configuration of AVM modules to meet Microsoft’s Well Architected Framework (WAF) principles
How to deploy your Bicep template into an Azure subscription from your local machine

Let’s get started!

Prerequisites

title: “Bicep Prerequisites”
description: “Learn about the prerequisites for using Bicep to deploy Azure Verified Modules or develop them.”

You will need the following tools and components to complete this guide:

Visual Studio Code (VS Code) to develop your solution.
Bicep Visual Studio Code Extension to author your Bicep template and explore modules published in the Registry.
One of the following command line tools:
- PowerShell AND Azure PowerShell
- Azure CLI to deploy your solution.
Bicep CLI
Azure Subscription to deploy your Bicep templates.

Before you begin, make sure you have these tools installed in your development environment.

Solution Architecture

Before we begin coding, it is important to have details about what the infrastructure architecture will include. For our example, we will be building a solution that will host a simple application on a Linux virtual machine (VM). The solution must be secure and auditable. The VM must not be accessible from the internet and its logs should be easily accessible. All azure services should utilize logging tools for auditing purposes.

Develop the Solution Code

Creating the main.bicep file

The architecture diagram shows all components needed for a successful solution deployment. Rather than building the complete solution at once, this tutorial takes an incremental approach building the Bicep file piece-by-piece and testing the deployment at each stage. This approach allows for discussion of each design decision along the way.

The development will start with core platform components: first the backend logging services (Log Analytics) and then the virtual network.

Let’s begin by creating our folder structure along with a main.bicep file. Your folder structure should be as follows:

VirtualMachineAVM_Example1/
└── main.bicep

After you have your folder structure and main.bicep file, we can proceed with our first AVM resources!

Log Analytics

Let’s start by adding a logging service to our main.bicep since all other deployed resources will use this service for their logs.

Tip

Always begin template development by adding resources that create dependencies for other downstream services. This approach simplifies referencing these dependencies within your other modules as you develop them. For example, starting with Logging and Virtual Network services makes sense since all other services will depend on these.

The logging solution depicted in our Architecture Diagram shows we will be using a Log Analytics workspace. Let’s add that to our template! Open your main.bicep file and add the following:

➕ Expand Code

1module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
2  name: 'logAnalyticsWorkspace'
3  params: {
4    // Required parameters
5    name: 'VM-AVM-Ex1-law'
6    // Non-required parameters
7    location: 'westus2'
8  }
9}

Note

Always click on the “Copy to clipboard” button in the top right corner of the Code sample area in order not to have the line numbers included in the copied code.

You now have a fully functional Bicep template that will deploy a working Log Analytics workspace! If you would like to try it, run the following in your console:

Note

For keeping the example below simple, we are using the traditional deployment commands, e.g., az deployment group create or New-AzResourceGroupDeployment. However, we encourage you to look into using Deployment Stacks instead by simply replacing the previous commands with az stack group create or New-AzResourceGroupDeploymentStack as well as the other required input parameters as shown here.

Deployment Stacks allow you to deploy a Bicep file as a stack, which is a collection of resources that are deployed together. This allows you to manage the lifecycle of the stack as a single unit, making it easier to deploy, update, and now even delete resources via Bicep. You can also implement RBAC Deny Assignments on your stacks deployed resources to prevent changes to the resources or specific actions on the resources to all but an excluded list of users, groups or other principals.

Deploy with

# Log in to Azure
Connect-AzAccount

# Select your subscription
Set-AzContext -SubscriptionId '<subscriptionId>'

# Deploy a resource group
New-AzResourceGroup -Name 'avm-bicep-vmexample1' -Location '<location>'

# Invoke your deployment
New-AzResourceGroupDeployment -DeploymentName 'avm-bicep-vmexample1-deployment' -ResourceGroupName 'avm-bicep-vmexample1' -TemplateFile '/<path-to>/VirtualMachineAVM_Example1/main.bicep'

# Log in to Azure
az login

# Select your subscription
az account set --subscription '<subscriptionId>'

# Deploy a resource group
az group create --name 'avm-bicep-vmexample1' --location '<location>'

# Invoke your deployment
az deployment group create --name 'avm-bicep-vmexample1-deployment' --resource-group 'avm-bicep-vmexample1' --template-file '/<path-to>/VirtualMachineAVM_Example1/main.bicep'

The above commands will log you in to your Azure subscription, select a subscription to use, create a resource group, then deploy the main.bicep template to your resource group.

AVM Makes the deployment of Azure resources incredibly easy. Many of the parameters you would normally be required to define are taken care of by the AVM module itself. In fact, the location parameter is not even needed in your template—when left blank, by default, all AVM modules will deploy to the location in which your target Resource Group exists.

Now we have a Log Analytics workspace in our resource group which doesn’t do a whole lot of good on its own. Let’s take our template a step further by adding a Virtual Network that integrates with the Log Analytics workspace.

Virtual Network

We will now add a Virtual Network to our main.bicep file. This VNet will contain subnets and Network Security Groups (NSGs) for any of the resources we deploy that require IP addresses.

In your main.bicep file, add the following:

➕ Expand Code

 1module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 2  name: 'logAnalyticsWorkspace'
 3  params: {
 4    // Required parameters
 5    name: 'VM-AVM-Ex1-law'
 6    // Non-required parameters
 7    location: 'westus2'
 8  }
 9}
10
11module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
12  name: 'virtualNetworkDeployment'
13  params: {
14    // Required parameters
15    addressPrefixes: [
16      '10.0.0.0/16'
17    ]
18    name: 'VM-AVM-Ex1-vnet'
19    // Non-required parameters
20    location: 'westus2'
21  }
22}

Again, the Virtual Network AVM module requires only two things: a name and an addressPrefixes parameter.

Configure Diagnostics Settings

There is an additional parameter available in most AVM modules named diagnosticSettings. This parameter allows you to configure your resource to send its logs to any suitable logging service. In our case, we are using a Log Analytics workspace.

Let’s update our main.bicep file to have our VNet send all of its logging data to our Log Analytics workspace:

➕ Expand Code

 1module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 2  name: 'logAnalyticsWorkspace'
 3  params: {
 4    // Required parameters
 5    name: 'VM-AVM-Ex1-law'
 6    // Non-required parameters
 7    location: 'westus2'
 8  }
 9}
10
11module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
12  name: 'virtualNetworkDeployment'
13  params: {
14    // Required parameters
15    addressPrefixes: [
16      '10.0.0.0/16'
17    ]
18    name: 'VM-AVM-Ex1-vnet'
19    // Non-required parameters
20    location: 'westus2'
21    diagnosticSettings: [
22      {
23        name: 'vNetDiagnostics'
24        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
25      }
26    ]
27  }
28}

Notice how the diagnosticsSettings parameter needs a workspaceResourceId? All you need to do is add a reference to the built-in logAnalyticsWorkspaceId output of the logAnalyticsWorkspace AVM module. That’s it! Our VNet now has integrated its logging with our Log Analytics workspace. All AVM modules come with a set of built-in outputs that can be easily referenced by other modules within your template.

Info

All AVM modules have built-in outputs which can be referenced using the <moduleName>.outputs.<outputName> syntax.

When using plain Bicep, many of these outputs require multiple lines of code or knowledge of the correct object ID references to get at the desired output. AVM modules do much of this heavy lifting for you by taking care of these complex tasks within the module itself, then exposing them to you through the module’s outputs. Find out more about Bicep Outputs.

Add a Subnet and NAT Gateway

We can’t use a Virtual Network without subnets, so let’s add a subnet next. According to our Architecture, we will have three subnets: one for the Virtual Machine, one for the Bastion host, and one for Private Endpoints. We can start with the VM subnet for now. While we’re at it, let’s also add the NAT Gateway, the NAT Gateway’s Public IP, the attach the NAT Gateway to the VM subnet.

Add the following to your main.bicep:

➕ Expand Code

 1module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 2  name: 'logAnalyticsWorkspace'
 3  params: {
 4    // Required parameters
 5    name: 'VM-AVM-Ex1-law'
 6    // Non-required parameters
 7    location: 'westus2'
 8  }
 9}
10
11module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
12  name: 'natGwPublicIpDeployment'
13  params: {
14    // Required parameters
15    name: 'VM-AVM-Ex1-natgwpip'
16    // Non-required parameters
17    location: 'westus2'
18    diagnosticSettings: [
19      {
20        name: 'natGwPublicIpDiagnostics'
21        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
22      }
23    ]
24  }
25}
26
27module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
28  name: 'natGatewayDeployment'
29  params: {
30    // Required parameters
31    name: 'VM-AVM-Ex1-natGw'
32    zone: 1
33    // Non-required parameters
34    publicIpResourceIds: [
35      natGwPublicIp.outputs.resourceId
36    ]
37  }
38}
39
40module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
41  name: 'virtualNetworkDeployment'
42  params: {
43    // Required parameters
44    addressPrefixes: [
45      '10.0.0.0/16'
46    ]
47    name: 'VM-AVM-Ex1-vnet'
48    // Non-required parameters
49    location: 'westus2'
50    diagnosticSettings: [
51      {
52        name: 'vNetDiagnostics'
53        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
54      }
55    ]
56    subnets: [
57      {
58        name: 'VMSubnet'
59        addressPrefix: cidrSubnet('10.0.0.0/16', 24, 0) // first subnet in address space
60        natGatewayResourceId: natGateway.outputs.resourceId
61      }
62    ]
63  }
64}

The modification adds a subnets property to our virtualNetwork module. The AVM network/virtual-network module supports the creation of subnets directly within the module itself. We can also link our NAT Gateway directly to the subnet within this submodule.

A nice feature within Bicep are the various functions available. We use the cidrSubnet() function to declare CIDR blocks without having to calculate them on your own.

Switch to Parameters and Variables

See how we are reusing the same CIDR block 10.0.0.0/16 in multiple locations? You may have noticed we are defining the same location in two different spots as well. We’re now at a point in the development where we should leverage one of our first recommended practices: using parameters and variables!

Tip

Use Bicep variables to define values that will be constant and reused with your template; use parameters anywhere you may need a modifiable value.

Let’s enhance the template by adding variables for the CIDR block and prefix, then use a location parameter with a default value. We’ll then reference those in the module:

➕ Expand Code

 1param location string = 'westus2'
 2
 3var addressPrefix = '10.0.0.0/16'
 4var prefix = 'VM-AVM-Ex1'
 5
 6module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 7  name: 'logAnalyticsWorkspace'
 8  params: {
 9    // Required parameters
10    name: '${prefix}-law'
11    // Non-required parameters
12    location: location
13  }
14}
15
16module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
17  name: 'natGwPublicIpDeployment'
18  params: {
19    // Required parameters
20    name: '${prefix}-natgwpip'
21    // Non-required parameters
22    location: location
23    diagnosticSettings: [
24      {
25        name: 'natGwPublicIpDiagnostics'
26        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
27      }
28    ]
29  }
30}
31
32module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
33  name: 'natGatewayDeployment'
34  params: {
35    // Required parameters
36    name: '${prefix}-natgw'
37    zone: 1
38    // Non-required parameters
39    publicIpResourceIds: [
40      natGwPublicIp.outputs.resourceId
41    ]
42  }
43}
44
45module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
46  name: 'virtualNetworkDeployment'
47  params: {
48    // Required parameters
49    addressPrefixes: [
50      addressPrefix
51    ]
52    name: '${prefix}-vnet'
53    // Non-required parameters
54    location: location
55    diagnosticSettings: [
56      {
57        name: 'vNetDiagnostics'
58        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
59      }
60    ]
61    subnets: [
62      {
63        name: 'VMSubnet'
64        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
65        natGatewayResourceId: natGateway.outputs.resourceId
66      }
67    ]
68  }
69}

We now have a good basis for the infrastructure to be utilized by the rest of the resources in our Architecture. We will come back to our networking in a future step, once we are ready to create some Network Security Groups. For now, let’s move on to other modules.

Key Vault

Key Vaults are one of the key components in most Azure architectures as they create a place where you can save and reference secrets in a secure manner (“secrets” in the general sense, as opposed to the secret object type in Key Vaults). The Key Vault AVM module makes it very simple to store secrets generated in your template. In this tutorial, we will use one of the most secure methods of storing and retrieving secrets by leveraging this Key Vault in our Bicep template.

The first step is easy: add the Key Vault AVM module to our main.bicep file. In addition, let’s also ensure it’s hooked into our Log Analytics workspace (we will do this for every new module from here on out).

➕ Expand Code

 1param location string = 'westus2'
 2
 3var addressPrefix = '10.0.0.0/16'
 4var prefix = 'VM-AVM-Ex1'
 5
 6module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 7  name: 'logAnalyticsWorkspace'
 8  params: {
 9    // Required parameters
10    name: '${prefix}-law'
11    // Non-required parameters
12    location: location
13  }
14}
15
16module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
17  name: 'natGwPublicIpDeployment'
18  params: {
19    // Required parameters
20    name: '${prefix}-natgwpip'
21    // Non-required parameters
22    location: location
23    diagnosticSettings: [
24      {
25        name: 'natGwPublicIpDiagnostics'
26        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
27      }
28    ]
29  }
30}
31
32module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
33  name: 'natGatewayDeployment'
34  params: {
35    // Required parameters
36    name: '${prefix}-natgw'
37    zone: 1
38    // Non-required parameters
39    publicIpResourceIds: [
40      natGwPublicIp.outputs.resourceId
41    ]
42  }
43}
44
45module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
46  name: 'virtualNetworkDeployment'
47  params: {
48    // Required parameters
49    addressPrefixes: [
50      addressPrefix
51    ]
52    name: '${prefix}-vnet'
53    // Non-required parameters
54    location: location
55    diagnosticSettings: [
56      {
57        name: 'vNetDiagnostics'
58        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
59      }
60    ]
61    subnets: [
62      {
63        name: 'VMSubnet'
64        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
65        natGatewayResourceId: natGateway.outputs.resourceId
66      }
67    ]
68  }
69}
70
71module keyVault 'br/public:avm/res/key-vault/vault:0.12.1' = {
72  name: 'keyVaultDeployment'
73  params: {
74    // Required parameters
75    name: '${uniqueString(resourceGroup().id)}-kv'
76    // Non-required parameters
77    location: location
78    diagnosticSettings: [
79      {
80        name: 'keyVaultDiagnostics'
81        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
82      }
83    ]
84  }
85}

The name of the Key Vault we will deploy uses the uniqueString() Bicep function. Key Vault names must be globally unique. We will therefore deviate from our standard naming convention thus far and make an exception for the Key Vault. Note how we are still adding a suffix to the Key Vault name, so its name remains recognizable; you can use a combination of concatenating unique strings, prefixes, or suffixes to follow your own naming standard preferences.

When we generate our unique string, we will pass in the resourceGroup().id as the seed for the uniqueString() function so that every time you deploy this main.bicep to the same resource group, it will use the same randomly generated name for your Key Vault (since resourceGroup().id will be the same).

Tip

Bicep has many built-in functions available. We used two here: uniqueString() and resourceGroup(). The resourceGroup(), subscription(), and deployment() functions are very useful when seeding uniqueString() or guid() functions. Just be cautious about name length limitations for each Azure service! Visit this page to learn more about Bicep functions.

We will use this Key Vault later on when we create a VM and need to store its password. Now that we have it, a Virtual Network, Subnet, and Log Analytics prepared, we should have everything we need to deploy a Virtual Machine!

Info

In the future, we will update this guide to show how to generate and store a certificate in the Key Vault, then use that certificate to authenticate into the Virtual Machine.

Virtual Machine

Warning

The AVM Virtual Machine module enables the EncryptionAtHost feature by default. You must enable this feature within your Azure subscription successfully deploy this example code. To do so, run the following:

Deploy with

# Wait a few minutes after running the command to allow it to propagate
Register-AzProviderFeature -FeatureName "EncryptionAtHost" -ProviderNamespace "Microsoft.Compute"

az feature register --namespace Microsoft.Compute --name EncryptionAtHost

# Propagate the change
az provider register --namespace Microsoft.Compute

For our Virtual Machine (VM) deployment, we need to add the following to our main.bicep file:

➕ Expand Code

  1param location string = 'westus2'
  2
  3// START add-password-param
  4@description('Required. A password for the VM admin user.')
  5@secure()
  6param vmAdminPass string
  7// END add-password-param
  8
  9var addressPrefix = '10.0.0.0/16'
 10var prefix = 'VM-AVM-Ex1'
 11
 12module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 13  name: 'logAnalyticsWorkspace'
 14  params: {
 15    // Required parameters
 16    name: '${prefix}-law'
 17    // Non-required parameters
 18    location: location
 19  }
 20}
 21
 22module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
 23  name: 'natGwPublicIpDeployment'
 24  params: {
 25    // Required parameters
 26    name: '${prefix}-natgwpip'
 27    // Non-required parameters
 28    location: location
 29    diagnosticSettings: [
 30      {
 31        name: 'natGwPublicIpDiagnostics'
 32        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 33      }
 34    ]
 35  }
 36}
 37
 38module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
 39  name: 'natGatewayDeployment'
 40  params: {
 41    // Required parameters
 42    name: '${prefix}-natgw'
 43    zone: 1
 44    // Non-required parameters
 45    publicIpResourceIds: [
 46      natGwPublicIp.outputs.resourceId
 47    ]
 48  }
 49}
 50
 51module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
 52  name: 'virtualNetworkDeployment'
 53  params: {
 54    // Required parameters
 55    addressPrefixes: [
 56      addressPrefix
 57    ]
 58    name: '${prefix}-vnet'
 59    // Non-required parameters
 60    location: location
 61    diagnosticSettings: [
 62      {
 63        name: 'vNetDiagnostics'
 64        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 65      }
 66    ]
 67    subnets: [
 68      {
 69        name: 'VMSubnet'
 70        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
 71        natGatewayResourceId: natGateway.outputs.resourceId
 72      }
 73    ]
 74  }
 75}
 76
 77module keyVault 'br/public:avm/res/key-vault/vault:0.12.1' = {
 78  name: 'keyVaultDeployment'
 79  params: {
 80    // Required parameters
 81    name: '${uniqueString(resourceGroup().id)}-kv'
 82    // Non-required parameters
 83    location: location
 84    diagnosticSettings: [
 85      {
 86        name: 'keyVaultDiagnostics'
 87        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 88      }
 89    ]
 90    // START add-keyvault-secret
 91    secrets: [
 92      {
 93        name: 'vmAdminPassword'
 94        value: vmAdminPass
 95      }
 96    ]
 97    // END add-keyvault-secret
 98  }
 99}
100
101module virtualMachine 'br/public:avm/res/compute/virtual-machine:0.13.1' = {
102  name: 'linuxVirtualMachineDeployment'
103  params: {
104    // Required parameters
105    adminUsername: 'localAdminUser'
106    adminPassword: vmAdminPass
107    imageReference: {
108      offer: '0001-com-ubuntu-server-jammy'
109      publisher: 'Canonical'
110      sku: '22_04-lts-gen2'
111      version: 'latest'
112    }
113    name: '${prefix}-vm1'
114    // START vm-subnet-reference
115    nicConfigurations: [
116      {
117        ipConfigurations: [
118          {
119            name: 'ipconfig01'
120            subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet
121          }
122        ]
123        nicSuffix: '-nic-01'
124      }
125    ]
126    // END vm-subnet-reference
127    osDisk: {
128      caching: 'ReadWrite'
129      diskSizeGB: 128
130      managedDisk: {
131        storageAccountType: 'Standard_LRS'
132      }
133    }
134    osType: 'Linux'
135    vmSize: 'Standard_B2s_v2'
136    zone: 0
137    // Non-required parameters
138    location: location
139  }
140}

The VM module is one of the more complex modules in AVM—behind the scenes, it takes care of a lot of heavy lifting that, without AVM, would require multiple Bicep resources to be deployed and referenced.

For example, look at the nicConfigurations parameter: normally, you would need to deploy a separate NIC resource, which itself also requires an IP resource, then attach them to each other, and finally, attach them all to your VM.

With the AVM VM module, the nicConfigurations parameter accepts an object, allowing you to create any number of NICs to attach to your VM from within the VM resource deployment itself. It handles all the naming, creation of other necessary dependencies, and attaches them all together, so you don’t have to. The osDisk parameter is similar, though slightly less complex. There are many more parameters within the VM module that you can leverage if needed, that share a similar ease-of-use.

Since this is the real highlight of our main.bicep file, we need to take a closer look at some of the other changes that were made.

VM Admin Password Parameter
```
1@description('Required. A password for the VM admin user.')
2@secure()
3param vmAdminPass string
```
First, we added a new parameter. The value of this will be provided when the main.bicep template is deployed. We don’t want any passwords stored as text in code; for our purposes, the safest way to do this is to prompt the end user for the password at the time of deployment.
Warning
The supplied password must be between 6-72 characters long and must satisfy at least 3 of password complexity requirements from the following: Contains an uppercase character; Contains a lowercase character; Contains a numeric digit; Contains a special character. Control characters are not allowed
Also note how we are using the @secure() decorator on the password parameter. This will ensure the value of the password is never displayed in any of the deployment logs or in Azure. We have also added the @description() decorator and started the description with “Required.” It’s a good habit and recommended practice to document your parameters in Bicep. This will ensure that VS Code’s built-in Bicep linter can provide end-users insightful information when deploying your Bicep templates.
Info
Always use the @secure() decorator when creating a parameter that will hold sensitive data!
Add the VM Admin Password to Key Vault
```
1    secrets: [
2      {
3        name: 'vmAdminPassword'
4        value: vmAdminPass
5      }
6    ]
```
The next thing we have done is save the value of our vmAdminPass parameter to our Key Vault. We have done this by adding a secrets parameter to the Key Vault module. Adding secrets to Key Vaults is very simple when using the AVM module.
By adding our password to the Key Vault, it will ensure that we never lose the password and that it is stored securely. As long as a user has appropriate permissions on the vault, the password can be fetched easily.
Reference the VM Subnet
```
 1    nicConfigurations: [
 2      {
 3        ipConfigurations: [
 4          {
 5            name: 'ipconfig01'
 6            subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet
 7          }
 8        ]
 9        nicSuffix: '-nic-01'
10      }
11    ]
```
Here, we reference another built-in output, this time from the AVM Virtual Network module. This example shows how to use an output that is part of an array. When the Virtual Network module creates subnets, it automatically creates a set of pre-defined outputs for them, one of which is an array that contains each subnet’s subnetResourceId. Our VM Subnet was the first one created which is position [0] in the array.
Other AVM modules may make use of arrays to store outputs. If you are unsure what type of outputs a module provides, you can always reference the Outputs section of each module’s README.md.

Storage Account

The last major component we need to add is a Storage Account. Because this Storage Account will be used as a backend storage to hold blobs for the hypothetical application that runs on our VM, we’ll also create a blob container within it using the same AVM Storage Account module.

➕ Expand Code

  1param location string = 'westus2'
  2
  3@description('Required. A password for the VM admin user.')
  4@secure()
  5param vmAdminPass string
  6
  7var addressPrefix = '10.0.0.0/16'
  8var prefix = 'VM-AVM-Ex1'
  9
 10module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 11  name: 'logAnalyticsWorkspace'
 12  params: {
 13    // Required parameters
 14    name: '${prefix}-law'
 15    // Non-required parameters
 16    location: location
 17  }
 18}
 19
 20module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
 21  name: 'natGwPublicIpDeployment'
 22  params: {
 23    // Required parameters
 24    name: '${prefix}-natgwpip'
 25    // Non-required parameters
 26    location: location
 27    diagnosticSettings: [
 28      {
 29        name: 'natGwPublicIpDiagnostics'
 30        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 31      }
 32    ]
 33  }
 34}
 35
 36module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
 37  name: 'natGatewayDeployment'
 38  params: {
 39    // Required parameters
 40    name: '${prefix}-natgw'
 41    zone: 1
 42    // Non-required parameters
 43    publicIpResourceIds: [
 44      natGwPublicIp.outputs.resourceId
 45    ]
 46  }
 47}
 48
 49module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
 50  name: 'virtualNetworkDeployment'
 51  params: {
 52    // Required parameters
 53    addressPrefixes: [
 54      addressPrefix
 55    ]
 56    name: '${prefix}-vnet'
 57    // Non-required parameters
 58    location: location
 59    diagnosticSettings: [
 60      {
 61
 62        name: 'vNetDiagnostics'
 63        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 64      }
 65    ]
 66    subnets: [
 67      {
 68        name: 'VMSubnet'
 69        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
 70        natGatewayResourceId: natGateway.outputs.resourceId
 71      }
 72    ]
 73  }
 74}
 75
 76module keyVault 'br/public:avm/res/key-vault/vault:0.12.1' = {
 77  name: 'keyVaultDeployment'
 78  params: {
 79    // Required parameters
 80    name: '${uniqueString(resourceGroup().id)}-kv'
 81    // Non-required parameters
 82    location: location
 83    diagnosticSettings: [
 84      {
 85        name: 'keyVaultDiagnostics'
 86        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 87      }
 88    ]
 89    enablePurgeProtection: false // disable purge protection for this example so we can more easily delete it
 90    secrets: [
 91      {
 92        name: 'vmAdminPassword'
 93        value: vmAdminPass
 94      }
 95    ]
 96  }
 97}
 98
 99module virtualMachine 'br/public:avm/res/compute/virtual-machine:0.13.1' = {
100  name: 'linuxVirtualMachineDeployment'
101  params: {
102    // Required parameters
103    adminUsername: 'localAdminUser'
104    adminPassword: vmAdminPass
105    imageReference: {
106      offer: '0001-com-ubuntu-server-jammy'
107      publisher: 'Canonical'
108      sku: '22_04-lts-gen2'
109      version: 'latest'
110    }
111    name: '${prefix}-vm1'
112    nicConfigurations: [
113      {
114        ipConfigurations: [
115          {
116            name: 'ipconfig01'
117            subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet
118          }
119        ]
120        nicSuffix: '-nic-01'
121      }
122    ]
123    osDisk: {
124      caching: 'ReadWrite'
125      diskSizeGB: 128
126      managedDisk: {
127        storageAccountType: 'Standard_LRS'
128      }
129    }
130
131    osType: 'Linux'
132    vmSize: 'Standard_B2s_v2'
133    zone: 0
134    // Non-required parameters
135    location: location
136  }
137}
138
139module storageAccount 'br/public:avm/res/storage/storage-account:0.19.0' = {
140  name: 'storageAccountDeployment'
141  params: {
142    // Required parameters
143    name: '${uniqueString(resourceGroup().id)}sa'
144    // Non-required parameters
145    location: location
146    skuName: 'Standard_LRS'
147    diagnosticSettings: [
148      {
149        name: 'storageAccountDiagnostics'
150        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
151      }
152    ]
153    blobServices: {
154      containers: [
155        {
156          name: 'vmstorage'
157          publicAccess: 'None'
158        }
159      ]
160    }
161  }
162}

We now have all the major components of our Architecture diagram built!

The last steps we need to take to meet our requirements is to ensure our networking resources are secure and that we are using least privileged access by leveraging Role-Based Access Control (RBAC). Let’s get to it!

Network Security Groups

We’ll add a Network Security Group (NSG) to our VM subnet. This will act as a layer 3 and layer 4 firewall for networked resources. This implementation includes an appropriate inbound rule to allow SSH traffic from the Bastion host:

➕ Expand Code

  1param location string = 'westus2'
  2
  3@description('Required. A password for the VM admin user.')
  4@secure()
  5param vmAdminPass string
  6
  7var addressPrefix = '10.0.0.0/16'
  8var prefix = 'VM-AVM-Ex1'
  9
 10module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 11  name: 'logAnalyticsWorkspace'
 12  params: {
 13    // Required parameters
 14    name: '${prefix}-law'
 15    // Non-required parameters
 16    location: location
 17  }
 18}
 19
 20module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
 21  name: 'natGwPublicIpDeployment'
 22  params: {
 23    // Required parameters
 24    name: '${prefix}-natgwpip'
 25    // Non-required parameters
 26    location: location
 27    diagnosticSettings: [
 28      {
 29        name: 'natGwPublicIpDiagnostics'
 30        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 31      }
 32    ]
 33  }
 34}
 35
 36module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
 37  name: 'natGatewayDeployment'
 38  params: {
 39    // Required parameters
 40    name: '${prefix}-natgw'
 41    zone: 1
 42    // Non-required parameters
 43    publicIpResourceIds: [
 44      natGwPublicIp.outputs.resourceId
 45    ]
 46  }
 47}
 48
 49module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
 50  name: 'virtualNetworkDeployment'
 51  params: {
 52    // Required parameters
 53    addressPrefixes: [
 54      addressPrefix
 55    ]
 56    name: '${prefix}-vnet'
 57    // Non-required parameters
 58    location: location
 59    diagnosticSettings: [
 60      {
 61        name: 'vNetDiagnostics'
 62        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 63      }
 64    ]
 65    subnets: [
 66      {
 67        name: 'VMSubnet'
 68        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
 69        natGatewayResourceId: natGateway.outputs.resourceId
 70        networkSecurityGroupResourceId: nsgVM.outputs.resourceId
 71      }
 72    ]
 73  }
 74}
 75
 76module nsgVM 'br/public:avm/res/network/network-security-group:0.5.1' = {
 77  name: 'nsgVmDeployment'
 78  params: {
 79    name: '${prefix}-NSG-VM'
 80    location: location
 81    securityRules: [
 82      {
 83        name: 'AllowBastionSSH'
 84        properties: {
 85          access: 'Allow'
 86          direction: 'Inbound'
 87          priority: 100
 88          protocol: 'Tcp'
 89          sourceAddressPrefix: 'virtualNetwork'
 90          sourcePortRange: '*'
 91          destinationAddressPrefix: '*'
 92          destinationPortRange: '22'
 93        }
 94      }
 95    ]
 96  }
 97}
 98
 99module keyVault 'br/public:avm/res/key-vault/vault:0.12.1' = {
100  name: 'keyVaultDeployment'
101  params: {
102    // Required parameters
103    name: '${uniqueString(resourceGroup().id)}-kv'
104    // Non-required parameters
105    location: location
106    diagnosticSettings: [
107      {
108        name: 'keyVaultDiagnostics'
109        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
110      }
111    ]
112    enablePurgeProtection: false // disable purge protection for this example so we can more easily delete it
113    secrets: [
114      {
115        name: 'vmAdminPassword'
116        value: vmAdminPass
117      }
118    ]
119  }
120}
121
122module virtualMachine 'br/public:avm/res/compute/virtual-machine:0.13.1' = {
123  name: 'linuxVirtualMachineDeployment'
124  params: {
125    // Required parameters
126    adminUsername: 'localAdminUser'
127    adminPassword: vmAdminPass
128    imageReference: {
129      offer: '0001-com-ubuntu-server-jammy'
130      publisher: 'Canonical'
131      sku: '22_04-lts-gen2'
132      version: 'latest'
133    }
134    name: '${prefix}-vm1'
135    nicConfigurations: [
136      {
137        ipConfigurations: [
138          {
139            name: 'ipconfig01'
140            subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet
141          }
142        ]
143        nicSuffix: '-nic-01'
144      }
145    ]
146    osDisk: {
147      caching: 'ReadWrite'
148      diskSizeGB: 128
149      managedDisk: {
150        storageAccountType: 'Standard_LRS'
151      }
152    }
153
154    osType: 'Linux'
155    vmSize: 'Standard_B2s_v2'
156    zone: 0
157    // Non-required parameters
158    location: location
159  }
160}
161
162module storageAccount 'br/public:avm/res/storage/storage-account:0.19.0' = {
163  name: 'storageAccountDeployment'
164  params: {
165    // Required parameters
166    name: '${uniqueString(resourceGroup().id)}sa'
167    // Non-required parameters
168    location: location
169    skuName: 'Standard_LRS'
170    diagnosticSettings: [
171      {
172        name: 'storageAccountDiagnostics'
173        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
174      }
175    ]
176    blobServices: {
177      containers: [
178        {
179          name: 'vmstorage'
180          publicAccess: 'None'
181        }
182      ]
183    }
184  }
185}

Disable Public Access to Storage Account

Since the Storage Account serves as a backend resource exclusively for the Virtual Machine, it will be secured as much as possible. This involves adding a Private Endpoint and disabling public internet access. AVM makes creation and assignment of Private Endpoints to resources incredibly easy. Take a look:

➕ Expand Code

  1param location string = 'westus2'
  2
  3@description('Required. A password for the VM admin user.')
  4@secure()
  5param vmAdminPass string
  6
  7var addressPrefix = '10.0.0.0/16'
  8var prefix = 'VM-AVM-Ex1'
  9
 10module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 11  name: 'logAnalyticsWorkspace'
 12  params: {
 13    // Required parameters
 14    name: '${prefix}-law'
 15    // Non-required parameters
 16    location: location
 17  }
 18}
 19
 20module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
 21  name: 'natGwPublicIpDeployment'
 22  params: {
 23    // Required parameters
 24    name: '${prefix}-natgwpip'
 25    // Non-required parameters
 26    location: location
 27    diagnosticSettings: [
 28      {
 29        name: 'natGwPublicIpDiagnostics'
 30        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 31      }
 32    ]
 33  }
 34}
 35
 36module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
 37  name: 'natGatewayDeployment'
 38  params: {
 39    // Required parameters
 40    name: '${prefix}-natgw'
 41    zone: 1
 42    // Non-required parameters
 43    publicIpResourceIds: [
 44      natGwPublicIp.outputs.resourceId
 45    ]
 46  }
 47}
 48
 49module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
 50  name: 'virtualNetworkDeployment'
 51  params: {
 52    // Required parameters
 53    addressPrefixes: [
 54      addressPrefix
 55    ]
 56    name: '${prefix}-vnet'
 57    // Non-required parameters
 58    location: location
 59    diagnosticSettings: [
 60      {
 61        name: 'vNetDiagnostics'
 62        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 63      }
 64    ]
 65    subnets: [
 66      {
 67        name: 'VMSubnet'
 68        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
 69        natGatewayResourceId: natGateway.outputs.resourceId
 70        networkSecurityGroupResourceId: nsgVM.outputs.resourceId
 71      }
 72      {
 73        name: 'PrivateEndpointSubnet'
 74        addressPrefix: cidrSubnet(addressPrefix, 24, 1) // second subnet in address space
 75      }
 76    ]
 77  }
 78}
 79
 80module nsgVM 'br/public:avm/res/network/network-security-group:0.5.1' = {
 81  name: 'nsgVmDeployment'
 82  params: {
 83    name: '${prefix}-NSG-VM'
 84    location: location
 85    securityRules: [
 86      {
 87        name: 'AllowBastionSSH'
 88        properties: {
 89          access: 'Allow'
 90          direction: 'Inbound'
 91          priority: 100
 92          protocol: 'Tcp'
 93          sourceAddressPrefix: 'virtualNetwork'
 94          sourcePortRange: '*'
 95          destinationAddressPrefix: '*'
 96          destinationPortRange: '22'
 97        }
 98      }
 99    ]
100  }
101}
102
103module keyVault 'br/public:avm/res/key-vault/vault:0.12.1' = {
104  name: 'keyVaultDeployment'
105  params: {
106    // Required parameters
107    name: '${uniqueString(resourceGroup().id)}-kv'
108    // Non-required parameters
109    location: location
110    diagnosticSettings: [
111      {
112        name: 'keyVaultDiagnostics'
113        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
114      }
115    ]
116    enablePurgeProtection: false // disable purge protection for this example so we can more easily delete it
117    secrets: [
118      {
119        name: 'vmAdminPassword'
120        value: vmAdminPass
121      }
122    ]
123  }
124}
125
126module virtualMachine 'br/public:avm/res/compute/virtual-machine:0.14.0' = {
127  name: 'linuxVirtualMachineDeployment'
128  params: {
129    // Required parameters
130    adminUsername: 'localAdminUser'
131    adminPassword: vmAdminPass
132    imageReference: {
133      offer: '0001-com-ubuntu-server-jammy'
134      publisher: 'Canonical'
135      sku: '22_04-lts-gen2'
136      version: 'latest'
137    }
138    name: '${prefix}-vm1'
139    nicConfigurations: [
140      {
141        ipConfigurations: [
142          {
143            name: 'ipconfig01'
144            subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet
145          }
146        ]
147        nicSuffix: '-nic-01'
148      }
149    ]
150    osDisk: {
151      caching: 'ReadWrite'
152      diskSizeGB: 128
153      managedDisk: {
154        storageAccountType: 'Standard_LRS'
155      }
156    }
157    osType: 'Linux'
158    vmSize: 'Standard_B2s_v2'
159    zone: 0
160    // Non-required parameters
161    location: location
162  }
163}
164
165module storageAccount 'br/public:avm/res/storage/storage-account:0.19.0' = {
166  name: 'storageAccountDeployment'
167  params: {
168    // Required parameters
169    name: '${uniqueString(resourceGroup().id)}sa'
170    // Non-required parameters
171    location: location
172    skuName: 'Standard_LRS'
173    diagnosticSettings: [
174      {
175        name: 'storageAccountDiagnostics'
176        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
177      }
178    ]
179    publicNetworkAccess: 'Disabled'
180    allowBlobPublicAccess: false
181    blobServices: {
182      containers: [
183        {
184          name: 'vmstorage'
185          publicAccess: 'None'
186        }
187      ]
188    }
189    privateEndpoints: [
190      {
191        service: 'Blob'
192        subnetResourceId: virtualNetwork.outputs.subnetResourceIds[1] // Private Endpoint Subnet
193        privateDnsZoneGroup: {
194          privateDnsZoneGroupConfigs: [
195            {
196              privateDnsZoneResourceId: privateDnsBlob.outputs.resourceId
197            }
198          ]
199        }
200      }
201    ]
202  }
203}
204
205module privateDnsBlob 'br/public:avm/res/network/private-dns-zone:0.7.1' = {
206  name: '${prefix}-privatedns-blob'
207  params: {
208    name: 'privatelink.blob.${environment().suffixes.storage}'
209    location: 'global'
210    virtualNetworkLinks: [
211      {
212        name: '${virtualNetwork.outputs.name}-vnetlink'
213        virtualNetworkResourceId: virtualNetwork.outputs.resourceId
214      }
215    ]
216  }
217}

This implementation adds a dedicated subnet for Private Endpoints following the recommended practice of isolating Private Endpoints in their own subnet.

The addition of just a few lines of code in the privateEndpoints parameter handles the complex tasks of creating the Private Endpoint, associating it with the VNet, and attaching it to the resource. AVM drastically simplifies the creation of Private Endpoints for just about every Azure Resource that supports them.

The implementation also disables all public network connectivity to the Storage Account, ensuring it only accepts traffic via the Private Endpoint.

Finally, a Private DNS zone is added and linked to the VNet, enabling the VM to resolve the Private IP address associated with the Storage Account.

Bastion

To securely access the Virtual Machine without exposing its SSH port to the public internet, we’ll create an Azure Bastion host. The Bastion Host requires a subnet with the exact name AzureBastionSubnet which cannot contain anything other than Bastion Hosts.

➕ Expand Code

  1param location string = 'westus2'
  2
  3@description('Required. A password for the VM admin user.')
  4@secure()
  5param vmAdminPass string
  6
  7var addressPrefix = '10.0.0.0/16'
  8var prefix = 'VM-AVM-Ex1'
  9
 10module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 11  name: 'logAnalyticsWorkspace'
 12  params: {
 13    // Required parameters
 14    name: '${prefix}-law'
 15    // Non-required parameters
 16    location: location
 17  }
 18}
 19
 20module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
 21  name: 'natGwPublicIpDeployment'
 22  params: {
 23    // Required parameters
 24    name: '${prefix}-natgwpip'
 25    // Non-required parameters
 26    location: location
 27    diagnosticSettings: [
 28      {
 29        name: 'natGwPublicIpDiagnostics'
 30        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 31      }
 32    ]
 33  }
 34}
 35
 36module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
 37  name: 'natGatewayDeployment'
 38  params: {
 39    // Required parameters
 40    name: '${prefix}-natgw'
 41    zone: 1
 42    // Non-required parameters
 43    publicIpResourceIds: [
 44      natGwPublicIp.outputs.resourceId
 45    ]
 46  }
 47}
 48
 49module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
 50  name: 'virtualNetworkDeployment'
 51  params: {
 52    // Required parameters
 53    addressPrefixes: [
 54      addressPrefix
 55    ]
 56    name: '${prefix}-vnet'
 57    // Non-required parameters
 58    location: location
 59    diagnosticSettings: [
 60      {
 61        name: 'vNetDiagnostics'
 62        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 63      }
 64    ]
 65    subnets: [
 66      {
 67        name: 'VMSubnet'
 68        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
 69        natGatewayResourceId: natGateway.outputs.resourceId
 70        networkSecurityGroupResourceId: nsgVM.outputs.resourceId
 71      }
 72      {
 73        name: 'PrivateEndpointSubnet'
 74        addressPrefix: cidrSubnet(addressPrefix, 24, 1) // second subnet in address space
 75      }
 76      {
 77        name: 'AzureBastionSubnet' // Azure Bastion Host requires this subnet to be named exactly "AzureBastionSubnet"
 78        addressPrefix: cidrSubnet(addressPrefix, 24, 2) // third subnet in address space
 79      }
 80    ]
 81  }
 82}
 83
 84module nsgVM 'br/public:avm/res/network/network-security-group:0.5.1' = {
 85  name: 'nsgVmDeployment'
 86  params: {
 87    name: '${prefix}-NSG-VM'
 88    location: location
 89    securityRules: [
 90      {
 91        name: 'AllowBastionSSH'
 92        properties: {
 93          access: 'Allow'
 94          direction: 'Inbound'
 95          priority: 100
 96          protocol: 'Tcp'
 97          sourceAddressPrefix: 'virtualNetwork'
 98          sourcePortRange: '*'
 99          destinationAddressPrefix: '*'
100          destinationPortRange: '22'
101        }
102      }
103    ]
104  }
105}
106
107module keyVault 'br/public:avm/res/key-vault/vault:0.12.1' = {
108  name: 'keyVaultDeployment'
109  params: {
110    // Required parameters
111    name: '${uniqueString(resourceGroup().id)}-kv'
112    // Non-required parameters
113    location: location
114    diagnosticSettings: [
115      {
116        name: 'keyVaultDiagnostics'
117        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
118      }
119    ]
120    enablePurgeProtection: false // disable purge protection for this example so we can more easily delete it
121    secrets: [
122      {
123        name: 'vmAdminPassword'
124        value: vmAdminPass
125      }
126    ]
127  }
128}
129
130module virtualMachine 'br/public:avm/res/compute/virtual-machine:0.14.0' = {
131  name: 'linuxVirtualMachineDeployment'
132  params: {
133    // Required parameters
134    adminUsername: 'localAdminUser'
135    adminPassword: vmAdminPass
136    imageReference: {
137      offer: '0001-com-ubuntu-server-jammy'
138      publisher: 'Canonical'
139      sku: '22_04-lts-gen2'
140      version: 'latest'
141    }
142    name: '${prefix}-vm1'
143    nicConfigurations: [
144      {
145        ipConfigurations: [
146          {
147            name: 'ipconfig01'
148            subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet
149          }
150        ]
151        nicSuffix: '-nic-01'
152      }
153    ]
154    osDisk: {
155      caching: 'ReadWrite'
156      diskSizeGB: 128
157      managedDisk: {
158        storageAccountType: 'Standard_LRS'
159      }
160    }
161    osType: 'Linux'
162    vmSize: 'Standard_B2s_v2'
163    zone: 0
164    // Non-required parameters
165    location: location
166  }
167}
168
169module storageAccount 'br/public:avm/res/storage/storage-account:0.19.0' = {
170  name: 'storageAccountDeployment'
171  params: {
172    // Required parameters
173    name: '${uniqueString(resourceGroup().id)}sa'
174    // Non-required parameters
175    location: location
176    skuName: 'Standard_LRS'
177    diagnosticSettings: [
178      {
179        name: 'storageAccountDiagnostics'
180        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
181      }
182    ]
183    publicNetworkAccess: 'Disabled'
184    allowBlobPublicAccess: false
185    blobServices: {
186      containers: [
187        {
188          name: 'vmstorage'
189          publicAccess: 'None'
190        }
191      ]
192    }
193    privateEndpoints: [
194      {
195        service: 'Blob'
196        subnetResourceId: virtualNetwork.outputs.subnetResourceIds[1] // Private Endpoint Subnet
197        privateDnsZoneGroup: {
198          privateDnsZoneGroupConfigs: [
199            {
200              privateDnsZoneResourceId: privateDnsBlob.outputs.resourceId
201            }
202          ]
203        }
204      }
205    ]
206  }
207}
208
209module privateDnsBlob 'br/public:avm/res/network/private-dns-zone:0.7.1' = {
210  name: '${prefix}-privatedns-blob'
211  params: {
212    name: 'privatelink.blob.${environment().suffixes.storage}'
213    location: 'global'
214    virtualNetworkLinks: [
215      {
216        name: '${virtualNetwork.outputs.name}-vnetlink'
217        virtualNetworkResourceId: virtualNetwork.outputs.resourceId
218      }
219    ]
220  }
221}
222
223// Note: Deploying a Bastion Host will automatically create a Public IP and use the subnet named "AzureBastionSubnet"
224// within our VNet. This subnet is required and must be named exactly "AzureBastionSubnet" for the Bastion Host to work.
225module bastion 'br/public:avm/res/network/bastion-host:0.6.1' = {
226  name: 'bastionDeployment'
227  params: {
228    name: '${prefix}-bastion'
229    virtualNetworkResourceId: virtualNetwork.outputs.resourceId
230    skuName: 'Basic'
231    location: location
232    diagnosticSettings: [
233      {
234        name: 'bastionDiagnostics'
235        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
236      }
237    ]
238  }
239}

This simple addition of the bastion-host AVM module completes the secure access component of our architecture. You can now access the Virtual Machine by way of the Bastion Host in the Azure Portal.

Role-Based Access Control

To complete our solution, we have one final task: to apply Role-Based Access Control (RBAC) restrictions on our services, namely the Key Vault and Storage Account. The goal is to explicitly allow only the Virtual Machine to have Create, Read, Update, or Delete (CRUD) permissions on these two services.

This is accomplished by enabling a System-assigned Managed Identity on the Virtual Machine, then granting the VM’s Managed Identity appropriate permissions on the Storage Account and Key Vault:

➕ Expand Code

  1param location string = 'westus2'
  2
  3@description('Required. A password for the VM admin user.')
  4@secure()
  5param vmAdminPass string
  6
  7var addressPrefix = '10.0.0.0/16'
  8var prefix = 'VM-AVM-Ex1'
  9
 10module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 11  name: 'logAnalyticsWorkspace'
 12  params: {
 13    // Required parameters
 14    name: '${prefix}-law'
 15    // Non-required parameters
 16    location: location
 17  }
 18}
 19
 20module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
 21  name: 'natGwPublicIpDeployment'
 22  params: {
 23    // Required parameters
 24    name: '${prefix}-natgwpip'
 25    // Non-required parameters
 26    location: location
 27    diagnosticSettings: [
 28      {
 29        name: 'natGwPublicIpDiagnostics'
 30        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 31      }
 32    ]
 33  }
 34}
 35
 36module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
 37  name: 'natGatewayDeployment'
 38  params: {
 39    // Required parameters
 40    name: '${prefix}-natgw'
 41    zone: 1
 42    // Non-required parameters
 43    publicIpResourceIds: [
 44      natGwPublicIp.outputs.resourceId
 45    ]
 46  }
 47}
 48
 49module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
 50  name: 'virtualNetworkDeployment'
 51  params: {
 52    // Required parameters
 53    addressPrefixes: [
 54      addressPrefix
 55    ]
 56    name: '${prefix}-vnet'
 57    // Non-required parameters
 58    location: location
 59    diagnosticSettings: [
 60      {
 61        name: 'vNetDiagnostics'
 62        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 63      }
 64    ]
 65    subnets: [
 66      {
 67        name: 'VMSubnet'
 68        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
 69        natGatewayResourceId: natGateway.outputs.resourceId
 70        networkSecurityGroupResourceId: nsgVM.outputs.resourceId
 71      }
 72      {
 73        name: 'PrivateEndpointSubnet'
 74        addressPrefix: cidrSubnet(addressPrefix, 24, 1) // second subnet in address space
 75      }
 76      {
 77        name: 'AzureBastionSubnet' // Azure Bastion Host requires this subnet to be named exactly "AzureBastionSubnet"
 78        addressPrefix: cidrSubnet(addressPrefix, 24, 2) // third subnet in address space
 79      }
 80    ]
 81  }
 82}
 83
 84module nsgVM 'br/public:avm/res/network/network-security-group:0.5.1' = {
 85  name: 'nsgVmDeployment'
 86  params: {
 87    name: '${prefix}-NSG-VM'
 88    location: location
 89    securityRules: [
 90      {
 91        name: 'AllowBastionSSH'
 92        properties: {
 93          access: 'Allow'
 94          direction: 'Inbound'
 95          priority: 100
 96          protocol: 'Tcp'
 97          sourceAddressPrefix: 'virtualNetwork'
 98          sourcePortRange: '*'
 99          destinationAddressPrefix: '*'
100          destinationPortRange: '22'
101        }
102      }
103    ]
104  }
105}
106
107module keyVault 'br/public:avm/res/key-vault/vault:0.12.1' = {
108  name: 'keyVaultDeployment'
109  params: {
110    // Required parameters
111    name: '${uniqueString(resourceGroup().id)}-kv'
112    // Non-required parameters
113    location: location
114    diagnosticSettings: [
115      {
116        name: 'keyVaultDiagnostics'
117        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
118      }
119    ]
120    enablePurgeProtection: false // disable purge protection for this example so we can more easily delete it
121    secrets: [
122      {
123        name: 'vmAdminPassword'
124        value: vmAdminPass
125      }
126    ]
127    roleAssignments: [
128      {
129        principalId: virtualMachine.outputs.systemAssignedMIPrincipalId
130        principalType: 'ServicePrincipal'
131        roleDefinitionIdOrName: 'Key Vault Secrets User' // Allows read access to secrets
132      }
133    ]
134  }
135}
136
137module virtualMachine 'br/public:avm/res/compute/virtual-machine:0.14.0' = {
138  name: 'linuxVirtualMachineDeployment'
139  params: {
140    // Required parameters
141    adminUsername: 'localAdminUser'
142    adminPassword: vmAdminPass
143    imageReference: {
144      offer: '0001-com-ubuntu-server-jammy'
145      publisher: 'Canonical'
146      sku: '22_04-lts-gen2'
147      version: 'latest'
148    }
149    name: '${prefix}-vm1'
150    nicConfigurations: [
151      {
152        ipConfigurations: [
153          {
154            name: 'ipconfig01'
155            subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet
156          }
157        ]
158        nicSuffix: '-nic-01'
159      }
160    ]
161    osDisk: {
162      caching: 'ReadWrite'
163      diskSizeGB: 128
164      managedDisk: {
165        storageAccountType: 'Standard_LRS'
166      }
167    }
168    osType: 'Linux'
169    vmSize: 'Standard_B2s_v2'
170    zone: 0
171    // Non-required parameters
172    location: location
173    managedIdentities: {
174      systemAssigned: true
175    }
176  }
177}
178
179module storageAccount 'br/public:avm/res/storage/storage-account:0.19.0' = {
180  name: 'storageAccountDeployment'
181  params: {
182    // Required parameters
183    name: '${uniqueString(resourceGroup().id)}sa'
184    // Non-required parameters
185    location: location
186    skuName: 'Standard_LRS'
187    diagnosticSettings: [
188      {
189        name: 'storageAccountDiagnostics'
190        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
191      }
192    ]
193    publicNetworkAccess: 'Disabled'
194    allowBlobPublicAccess: false
195    blobServices: {
196      containers: [
197        {
198          name: 'vmstorage'
199          publicAccess: 'None'
200        }
201      ]
202      roleAssignments:[
203        {
204          principalId: virtualMachine.outputs.systemAssignedMIPrincipalId
205          principalType: 'ServicePrincipal'
206          roleDefinitionName: 'Storage Blob Data Contributor' // Allows read/write/delete on blob containers
207        }
208      ]
209    }
210    privateEndpoints: [
211      {
212        service: 'Blob'
213        subnetResourceId: virtualNetwork.outputs.subnetResourceIds[1] // Private Endpoint Subnet
214        privateDnsZoneGroup: {
215          privateDnsZoneGroupConfigs: [
216            {
217              privateDnsZoneResourceId: privateDnsBlob.outputs.resourceId
218            }
219          ]
220        }
221      }
222    ]
223  }
224}
225
226module privateDnsBlob 'br/public:avm/res/network/private-dns-zone:0.7.1' = {
227  name: '${prefix}-privatedns-blob'
228  params: {
229    name: 'privatelink.blob.${environment().suffixes.storage}'
230    location: 'global'
231    virtualNetworkLinks: [
232      {
233        name: '${virtualNetwork.outputs.name}-vnetlink'
234        virtualNetworkResourceId: virtualNetwork.outputs.resourceId
235      }
236    ]
237  }
238}
239
240// Note: Deploying a Bastion Host will automatically create a Public IP and use the subnet named "AzureBastionSubnet"
241// within our VNet. This subnet is required and must be named exactly "AzureBastionSubnet" for the Bastion Host to work.
242module bastion 'br/public:avm/res/network/bastion-host:0.6.1' = {
243  name: 'bastionDeployment'
244  params: {
245    name: '${prefix}-bastion'
246    virtualNetworkResourceId: virtualNetwork.outputs.resourceId
247    skuName: 'Basic'
248    location: location
249    diagnosticSettings: [
250      {
251        name: 'bastionDiagnostics'
252        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
253      }
254    ]
255  }
256}

Info

The Azure Subscription owner will have CRUD permissions for the Storage Account but not for the Key Vault. The Key Vault requires explicit RBAC permissions assigned to a user to grant them access: Provide access to Key Vaults using RBAC. Important!: at this point, you will only be able to access the Storage Account from the Bastion Host. Remember, public internet access has been disabled!

The RBAC policies have been successfully applied using a System-assigned Managed Identity on the Virtual Machine. This identity has been granted permissions on both the Key Vault and Storage Account. Now the VM can read secrets from the Key Vault and Read, Create, or Delete blobs in the Storage Account.

In a real production environment, the principle of least privileged access should be applied, providing only the exact permissions each service needs to carry out its functions. Learn more about Microsoft’s recommendations for identity and access management.

Conclusion

In this tutorial, we’ve explored how to leverage Azure Verified Modules (AVM) to build a secure, well-architected solution in Azure. AVM modules significantly simplify the deployment of Azure resources by abstracting away much of the complexity involved in configuring individual resources.

Your final, deployable Bicep template file should now look like this:

➕ Expand Code

  1param location string = 'westus2'
  2
  3@description('Required. A password for the VM admin user.')
  4@secure()
  5param vmAdminPass string
  6
  7var addressPrefix = '10.0.0.0/16'
  8var prefix = 'VM-AVM-Ex1'
  9
 10module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.11.1' = {
 11  name: 'logAnalyticsWorkspace'
 12  params: {
 13    // Required parameters
 14    name: '${prefix}-law'
 15    // Non-required parameters
 16    location: location
 17  }
 18}
 19
 20module natGwPublicIp 'br/public:avm/res/network/public-ip-address:0.8.0' = {
 21  name: 'natGwPublicIpDeployment'
 22  params: {
 23    // Required parameters
 24    name: '${prefix}-natgwpip'
 25    // Non-required parameters
 26    location: location
 27    diagnosticSettings: [
 28      {
 29        name: 'natGwPublicIpDiagnostics'
 30        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 31      }
 32    ]
 33  }
 34}
 35
 36module natGateway 'br/public:avm/res/network/nat-gateway:1.2.2' = {
 37  name: 'natGatewayDeployment'
 38  params: {
 39    // Required parameters
 40    name: '${prefix}-natgw'
 41    zone: 1
 42    // Non-required parameters
 43    publicIpResourceIds: [
 44      natGwPublicIp.outputs.resourceId
 45    ]
 46  }
 47}
 48
 49module virtualNetwork 'br/public:avm/res/network/virtual-network:0.6.1' = {
 50  name: 'virtualNetworkDeployment'
 51  params: {
 52    // Required parameters
 53    addressPrefixes: [
 54      addressPrefix
 55    ]
 56    name: '${prefix}-vnet'
 57    // Non-required parameters
 58    location: location
 59    diagnosticSettings: [
 60      {
 61        name: 'vNetDiagnostics'
 62        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
 63      }
 64    ]
 65    subnets: [
 66      {
 67        name: 'VMSubnet'
 68        addressPrefix: cidrSubnet(addressPrefix, 24, 0) // first subnet in address space
 69        natGatewayResourceId: natGateway.outputs.resourceId
 70        networkSecurityGroupResourceId: nsgVM.outputs.resourceId
 71      }
 72      {
 73        name: 'PrivateEndpointSubnet'
 74        addressPrefix: cidrSubnet(addressPrefix, 24, 1) // second subnet in address space
 75      }
 76      {
 77        name: 'AzureBastionSubnet' // Azure Bastion Host requires this subnet to be named exactly "AzureBastionSubnet"
 78        addressPrefix: cidrSubnet(addressPrefix, 24, 2) // third subnet in address space
 79      }
 80    ]
 81  }
 82}
 83
 84module nsgVM 'br/public:avm/res/network/network-security-group:0.5.1' = {
 85  name: 'nsgVmDeployment'
 86  params: {
 87    name: '${prefix}-NSG-VM'
 88    location: location
 89    securityRules: [
 90      {
 91        name: 'AllowBastionSSH'
 92        properties: {
 93          access: 'Allow'
 94          direction: 'Inbound'
 95          priority: 100
 96          protocol: 'Tcp'
 97          sourceAddressPrefix: 'virtualNetwork'
 98          sourcePortRange: '*'
 99          destinationAddressPrefix: '*'
100          destinationPortRange: '22'
101        }
102      }
103    ]
104  }
105}
106
107module keyVault 'br/public:avm/res/key-vault/vault:0.12.1' = {
108  name: 'keyVaultDeployment'
109  params: {
110    // Required parameters
111    name: '${uniqueString(resourceGroup().id)}-kv'
112    // Non-required parameters
113    location: location
114    diagnosticSettings: [
115      {
116        name: 'keyVaultDiagnostics'
117        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
118      }
119    ]
120    enablePurgeProtection: false // disable purge protection for this example so we can more easily delete it
121    secrets: [
122      {
123        name: 'vmAdminPassword'
124        value: vmAdminPass
125      }
126    ]
127    roleAssignments: [
128      {
129        principalId: virtualMachine.outputs.systemAssignedMIPrincipalId
130        principalType: 'ServicePrincipal'
131        roleDefinitionIdOrName: 'Key Vault Secrets User' // Allows read access to secrets
132      }
133    ]
134  }
135}
136
137module virtualMachine 'br/public:avm/res/compute/virtual-machine:0.14.0' = {
138  name: 'linuxVirtualMachineDeployment'
139  params: {
140    // Required parameters
141    adminUsername: 'localAdminUser'
142    adminPassword: vmAdminPass
143    imageReference: {
144      offer: '0001-com-ubuntu-server-jammy'
145      publisher: 'Canonical'
146      sku: '22_04-lts-gen2'
147      version: 'latest'
148    }
149    name: '${prefix}-vm1'
150    nicConfigurations: [
151      {
152        ipConfigurations: [
153          {
154            name: 'ipconfig01'
155            subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet
156          }
157        ]
158        nicSuffix: '-nic-01'
159      }
160    ]
161    osDisk: {
162      caching: 'ReadWrite'
163      diskSizeGB: 128
164      managedDisk: {
165        storageAccountType: 'Standard_LRS'
166      }
167    }
168    osType: 'Linux'
169    vmSize: 'Standard_B2s_v2'
170    zone: 0
171    // Non-required parameters
172    location: location
173    managedIdentities: {
174      systemAssigned: true
175    }
176  }
177}
178
179module storageAccount 'br/public:avm/res/storage/storage-account:0.19.0' = {
180  name: 'storageAccountDeployment'
181  params: {
182    // Required parameters
183    name: '${uniqueString(resourceGroup().id)}sa'
184    // Non-required parameters
185    location: location
186    skuName: 'Standard_LRS'
187    diagnosticSettings: [
188      {
189        name: 'storageAccountDiagnostics'
190        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
191      }
192    ]
193    publicNetworkAccess: 'Disabled'
194    allowBlobPublicAccess: false
195    blobServices: {
196      containers: [
197        {
198          name: 'vmstorage'
199          publicAccess: 'None'
200        }
201      ]
202      roleAssignments:[
203        {
204          principalId: virtualMachine.outputs.systemAssignedMIPrincipalId
205          principalType: 'ServicePrincipal'
206          roleDefinitionName: 'Storage Blob Data Contributor' // Allows read/write/delete on blob containers
207        }
208      ]
209    }
210    privateEndpoints: [
211      {
212        service: 'Blob'
213        subnetResourceId: virtualNetwork.outputs.subnetResourceIds[1] // Private Endpoint Subnet
214        privateDnsZoneGroup: {
215          privateDnsZoneGroupConfigs: [
216            {
217              privateDnsZoneResourceId: privateDnsBlob.outputs.resourceId
218            }
219          ]
220        }
221      }
222    ]
223  }
224}
225
226module privateDnsBlob 'br/public:avm/res/network/private-dns-zone:0.7.1' = {
227  name: '${prefix}-privatedns-blob'
228  params: {
229    name: 'privatelink.blob.${environment().suffixes.storage}'
230    location: 'global'
231    virtualNetworkLinks: [
232      {
233        name: '${virtualNetwork.outputs.name}-vnetlink'
234        virtualNetworkResourceId: virtualNetwork.outputs.resourceId
235      }
236    ]
237  }
238}
239
240// Note: Deploying a Bastion Host will automatically create a Public IP and use the subnet named "AzureBastionSubnet"
241// within our VNet. This subnet is required and must be named exactly "AzureBastionSubnet" for the Bastion Host to work.
242module bastion 'br/public:avm/res/network/bastion-host:0.6.1' = {
243  name: 'bastionDeployment'
244  params: {
245    name: '${prefix}-bastion'
246    virtualNetworkResourceId: virtualNetwork.outputs.resourceId
247    skuName: 'Basic'
248    location: location
249    diagnosticSettings: [
250      {
251        name: 'bastionDiagnostics'
252        workspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
253      }
254    ]
255  }
256}

AVM modules provide several key advantages over writing raw Bicep templates:

Simplified Resource Configuration: AVM modules handle much of the complex configuration work behind the scenes
Built-in Recommended Practices: The modules implement many of Microsoft’s recommended practices by default
Consistent Outputs: Each module exposes a consistent set of outputs that can be easily referenced
Reduced Boilerplate Code: What would normally require hundreds of lines of Bicep code can be accomplished in a fraction of the space

As you continue your journey with Azure and AVM, remember that this approach can be applied to more complex architectures as well. The modular nature of AVM allows you to mix and match components to build solutions that meet your specific needs while adhering to Microsoft’s Well-Architected Framework.

By using AVM modules as building blocks, you can focus more on your solution architecture and less on the intricacies of individual resource configurations, ultimately leading to faster development cycles and more reliable deployments.

Clean up your environment

When you are ready, you can remove the infrastructure deployed in this example. Key Vaults are set to a soft-delete state so you will also need to purge the one we created in order to fully delete it. The following commands will remove all resources created by your deployment:

Clean up with

# Delete the resource group
Remove-AzResourceGroup -Name "avm-bicep-vmexample1" -Force

# Purge the Key Vault
Remove-AzKeyVault -VaultName "<keyVaultName>" -Location "<location>" -InRemovedState -Force

# Delete the resource group
az group delete --name 'avm-bicep-vmexample1' --yes --no-wait

# Purge the Key Vault
az keyvault purge --name '<keyVaultName>' --no-wait

Congratulations, you have successfully leveraged AVM Bicep modules to deploy resources in Azure!

Tip

We welcome your contributions and feedback to help us improve the AVM modules and the overall experience for the community!

Terraform - Solution Development

Introduction

Azure Verified Modules (AVM) for Terraform are a powerful tool that leverage the Terraform domain-specific language (DSL), industry knowledge, and an Open Source community, which altogether enable developers to quickly deploy Azure resources that follow Microsoft’s recommended practices for Azure.
In this article, we will walk through the Terraform specific considerations and recommended practices on developing your solution leveraging Azure Verified Modules. We’ll review some of the design features and trade-offs and include sample code to illustrate each discussion point.

Prerequisites

title: “Terraform Prerequisites”
description: “Learn about the prerequisites for using Terraform to deploy Azure Verified Modules or develop them.”

You will need the following tools and components to complete this guide:

Visual Studio Code (VS Code) to develop your solution.
Terraform CLI to deploy your Terraform modules. Make sure you have a recent version installed.
Azure CLI to authenticate to Azure.
Azure Subscription to deploy your resources.

Before you begin, ensure you have these tools installed in your development environment.

Planning

Good module development should start with a good plan. Let’s first review the architecture and module design prior to developing our solution.

Solution Architecture

In our design, the resource group for our solution will require appropriate tagging to comply with our corporate standards. Resources that support Diagnostic Settings must also send metric data to a Log Analytics workspace, so that the infrastructure support teams can get metric telemetry. The virtual machine will require outbound internet access to allow the application to properly function. A Key Vault will be included to store any secrets and key artifacts, and we will include a Bastion instance to allow support personnel to access the virtual machine if needed. Finally, the VM is intended to run without interaction, so we will auto-generate an SSH private key and store it in the Key Vault for the rare event of someone needing to log into the VM.

Based on this narrative, we will create the following resources:

A resource group to contain all the resources with tagging
A random string resource for use in resources with global naming (Key Vault)
A Log Analytics workspace for diagnostic data
A Key Vault with:
- Role-Based Access Control (RBAC) to allow data access
- Logging to the Log Analytics workspace
A virtual network with:
- A virtual machine subnet
- A Bastion subnet
- Network Security Group on the VM subnet allowing SSH traffic
- Logging to the Log Analytics workspace
A NAT Gateway for enabling outbound internet access
- Associated to the virtual machine subnet
A Bastion service for secure remote access to the Virtual Machine
- Logging to the Log Analytics workspace
A virtual machine resource with
- A single private IPv4 interface attached to the VM subnet
- A randomly generated admin account private key stored in the Key Vault
- Metrics sent to the log Analytics workspace

Solution template (root module) design

Since our solution template (root module) is intended to be deployed multiple times, we want to develop it in a way that provides flexibility while minimizing the amount of input necessary to deploy the solution. For these reasons, we will create our module with a small set of variables that allow for deployment differentiation while still populating solution-specific defaults to minimize input. We will also separate our content into variables.tf, outputs.tf, terraform.tf, and main.tf files to simplify future maintenance.

Based on this, our file system will take the following structure:

Module Directory
- terraform.tf - This file holds the provider definitions and versions.
- variables.tf - This file contains the input variable definitions and defaults.
- outputs.tf - This file contains the outputs and their descriptions for use by any external modules calling this root module.
- main.tf - This file contains the core module code for creating the solutions infrastructure.
- development.tfvars - This file will contain the inputs for the instance of the module that is being deployed. Content in this file will vary from instance to instance.

Note

Terraform will merge content from any file ending in a .tf extension in the module folder to create the full module content. Because of this, using different files is not required. We encourage file separation to allow for organizing code in a way that makes it easier to maintain. While the naming structure we’ve used is common, there are many other valid file naming and organization options that can be used.

In our example, we will use the following variables as inputs to allow for customization:

location - The location where our infrastructure will be deployed.
name_prefix - This will be used to preface all of the resource naming.
virtual_network_prefix - This will be used to ensure IP uniqueness for the deployment.
tags - The custom tags to use for each deployment.

Finally, we will export the following outputs:

resource_group_name - This will allow for finding this deployment if there are multiples.
virtual_machine_name - This can be used to find and login to the vm if needed.

Identifying AVM modules that match our solution

Now that we’ve determined our architecture and module configurations, we need to see what AVM modules exist for use in our solution. To do this, we will open the AVM Terraform pattern module index and check if there are any existing pattern modules that match our requirement. In this case, no pattern modules fit our needs. If this was a common pattern, we could open an issue on the AVM github repository to get assistance from the AVM project to create a pattern module matching our requirements. Since our architecture isn’t common, we’ll continue to the next step.

When a pattern module fitting our needs doesn’t exist for a solution, leveraging AVM resource modules to build our own solution is the next best option. Review the AVM Terraform published resource module index for each of the resource types included in your architecture. For each AVM module, capture a link to the module to allow for a review of the documentation details on the Terraform Registry website.

Note

Some of the published pattern modules cover multi-resource configurations that can sometimes be interpreted as a single resource. Be sure to check the pattern index for groups of resources that may be part of your architecture and that don’t exist in the resource module index. (e.g., Virtual WAN)

For our sample architecture, we have the following AVM resource modules at our disposal. Click on each module to explore its documentation on the Terraform Registry.

Develop the Solution Code

We can now begin coding our solution. We will create each element individually, to allow us to test our deployment as we build it out. This will also allow us to correct any bugs incrementally, so that we aren’t troubleshooting a large number of resources at the end.

Creating the terraform.tf file

Let’s begin by configuring the provider details necessary to build our solution. Since this is a root module, we want to include any provider and Terraform version constraints for this module. We’ll periodically come back and add any needed additional providers if our design includes a resource from a new provider.

Open up your development IDE (Visual studio code in our example) and create a file named terraform.tf in your root directory.

Add the following code to your terraform.tf file:

➕ Expand Code

1terraform {
2  required_version = "~> 1.9"
3  required_providers {
4  }
5}

Note

Always click on the “Copy to clipboard” button in the top right corner of the Code sample area in order not to have the line numbers included in the copied code.

This specifies that the required Terraform binary version to run your module can be any version between 1.9 and 2.0. This is a good compromise for allowing a range of binary versions while also ensuring support for any required features that are used as part of the module. This can include things like newly introduced functions or support for new key words.

Since we are developing our solution incrementally, we should validate our code. To do this, we will take the following steps:

Open up a terminal window if it is not already open. In some IDE’s this can be done as a function of the IDE.
Change directory to the module directory by typing cd and then the path to the module. As an example, if the module directory was named example we would run cd example.
Run terraform init to initialize your provider file.

You should now see a message indicating that Terraform has been successfully initialized. This indicates that our code is error free and we can continue on. If you get errors, examine the provider syntax for typos, missing quotes, or missing brackets.

Creating a variables.tf file

Because our module is intended to be reusable, we want to provide the capability to customize each module call with those items that will differ between them. This is done by using variables to accept inputs into the module. We’ll define these inputs in a separate file named variables.tf.

Go back to the IDE, and create a file named variables.tf in the working directory.

Add the following code to your variables.tf file to configure the inputs for our example:

➕ Expand Code

 1variable "name_prefix" {
 2  description = "Prefix for the name of the resources"
 3  type        = string
 4  default     = "example"
 5}
 6
 7variable "location" {
 8  description = "The Azure location to deploy the resources"
 9  type        = string
10  default     = "East US"
11}
12
13variable "virtual_network_cidr" {
14  description = "The CIDR prefix for the virtual network. This should be at least a /22. Example 10.0.0.0/22"
15  type        = string
16}
17
18variable "tags" {
19  description = "Tags to be applied to all resources"
20  type        = map(string)
21  default     = {}
22}

Note

Note that each variable definition includes a type definition to guide module users on how to properly define an input. Also note that it is possible to set a default value. This allows module consumers to avoid setting a value if they find the default to be acceptable.

We should now test the new content we’ve created for our module. To do this, first re-run terraform init on your command line. Note that nothing has changed and the initialization completes successfully. Since we now have module content, we will attempt to run the plan as the next step of the workflow.

Type terraform plan on your command line. Note that it now asks for us to provide a value for the var.virtual_network_cidr variable. This is because we don’t provide a default value for that input so Terraform must have a valid input before it can continue. Type 10.0.0.0/22 into the input and press enter to allow the plan to complete. You should now see a message indicating that Your infrastructure matches the configuration and that no changes are needed.

Creating a development.tfvars file

There are multiple ways to provide input to the module we’re creating. We will create a tfvars file that can be supplied during plan and apply stages to minimize the need for manual input. tfvars files are a nice way to document inputs as well as allow for deploying different versions of your module. This is useful if you have a pipeline where infrastructure code is deployed first for development, and then is deployed for QA, staging, or production with different input values.

In your IDE, create a new file named development.tfvars in your working directory.

Now add the following content to your development.tfvars file.

➕ Expand Code

1location = "westus2"
2prefix = dev
3virtual_network_cidr = "10.1.0.0/22"
4tags = {
5  environment = "development"
6  owner       = "dev-team"
7}

Note

Note that each variable has a value defined. Although, only inputs without default values are required, we include values for all of the inputs for clarity. Consider doing this in your environments so that someone looking at the tfvars files has a full picture of what values are being set.

Re-run the terraform apply, but this time, reference the .tfvars file by using the following command: terraform plan -var-file=development.tfvars. You should get a successful completion without needing to manually provide inputs.

Creating the main.tf file

Now that we’ve created the supporting files, we can start building the actual infrastructure code in our main file. We will add one AVM resource module at a time so that we can test each as we implement them.

Return to your IDE and create a new file named main.tf.

Add a resource group

In Azure, we need a resource group to hold any infrastructure resources we create. This is a simple resource that typically wouldn’t require an AVM module, but we’ll include the AVM module so we can take advantage of the Role-Based Access Control (RBAC) interface if we need to restrict access to the resource group in future versions.

First, let’s visit the Terraform registry documentation page for the resource group and explore several key sections.

Note the Provision Instructions box on the right-hand side of the page. This contains the module source and version details which allows us to copy the latest version syntax without needing to type everything ourselves.
Now review the Readme tab in the middle of the page. It contains details about all required and optional inputs, resources that are created with the module, and any outputs that are defined. If you want to explore any of these items in detail, each element has a tab that you can review as needed.
Finally, in the middle of the page, there is a drop-down menu named Examples that contains functioning examples for the AVM module. These showcase a good example of using copy/paste to bootstrap module code and then modify it for your specific purpose.

Now that we’ve explored the registry content, let’s add a resource group to our module.

First, copy the content from the Provision Instructions box into our main.tf file.

➕ Expand Code

1module "avm-res-resources-resourcegroup" {
2  source  = "Azure/avm-res-resources-resourcegroup/azurerm"
3  version = "0.2.1"
4  # insert the 2 required variables here
5}

On the modules documentation page, go to the inputs tab. Review the Required Inputs tab. These are the values that don’t have defaults and are the minimum required values to deploy the module. There are additional inputs in the Optional Inputs section that can be used to configure additional module functionality. Review these inputs and determine which values you would like to define in your AVM module call.

Now, replace the # insert the 2 required variables here comment with the following code to define the module inputs. Our main.tf code should look like the following:

➕ Expand Code

1module "avm-res-resources-resourcegroup" {
2  source  = "Azure/avm-res-resources-resourcegroup/azurerm"
3  version = "0.2.1"
4
5  name = "${var.name_prefix}-rg"
6  location = var.location
7  tags = var.tags
8}

Note

Note how we’ve used the prefix variable and Terraform interpolation syntax to dynamically name the resource group. This allows for module customization and re-use. Also note that even though we chose to use the default module name of avm-res-resources-resourcegroup, we could modify the name of the module if needed.

After saving the file, we want to test our new content. To do this, return to the command line and first run terraform init. Notice how Terraform has downloaded the module code, as well as providers that the module requires. In this case, you can see the azurerm, random, and modtm providers were downloaded.

Let’s now deploy our resource group. First, let’s run a plan operation to review what will be created. Type terraform plan -var-file=development.tfvars and press enter to initiate the plan.

Add the features block

Notice that we get an error indicating that we are Missing required argument and that for the azurerm provider, we need to provide a features argument. The addition of the resource group AVM resource requires that the azurerm provider be installed to provision resources in our module. This provider requires a features block in its provider definition that is missing in our configuration.

Return to the terraform.tf file and add the following content to it. Note how the features block is currently empty. If we needed to activate any feature flags in our module, we could add them here.

➕ Expand Code

 1terraform {
 2  required_version = "~> 1.9"
 3  required_providers {
 4  }
 5}
 6
 7provider "azurerm" {
 8  features {
 9  }
10}

Re-run terraform plan -var-file=development.tfvars now that we have updated the features block.

Set the subscription ID

Note that we once again get an error. This time, the error indicates that subscription_id is a required provider property for plan/apply operations. This is a change that was introduced as part of the version 4 release of the AzureRM provider. We need to supply the ID of the deployment subscription where our resources will be created.

First, we need to get the subscription ID value. We will use the portal for this exercise, but using the Azure CLI, PowerShell, or the resource graph will also work to retrieve this value.

Open the Azure portal.
Enter Subscriptions in the search field at the top middle of the page.
Select Subscriptions from the services menu in the search drop-down.
Select the subscription you wish to deploy to, from the list of subscriptions.
Find the Subscription ID field on the overview page and click the copy button to copy it to the clipboard.

Secondly, we need to update Terraform so that it can use the subscription ID. There are multiple ways to provide a subscription ID to the provider including adding it to the features block or using environment variables. For this scenario we’ll use environment variables to set the values so that we don’t have to re-enter them on each run. This also keeps us from storing the subscription ID in our code since it is considered a sensitive value. Select a command from the list below based on your operating system.

(Linux/MacOS) - Run the following command with your subscription ID: export ARM_SUBSCRIPTION_ID=<your ID here>
(Windows) - Run the following command with your subscription ID: set ARM_SUBSCRIPTION_ID=<your ID here>

Finally, we should now be able to complete our plan operation by re-running terraform plan -var-file=development.tfvars. Note that the plan will create three resources, two for telemetry and one for the resource group.

Deploy the resource group

We can complete testing by implementing the resource group. Run terraform apply -var-file=development.tfvars and type yes and press enter when prompted to accept the changes. Terraform will create the resource group and notify you with a Apply complete message and a summary of the resources that were added, changed, and destroyed.

Deploy the Log Analytics Workspace

We can now continue by adding the Log Analytics Workspace to our main.tf file. We will follow a workflow similar to what we did with the resource group.

Browse to the AVM Log Analytics Workspace module page in the Terraform Registry.
Copy the module content from the Provision Instructions portion of the page into the main.tf file.

This time, instead of manually supplying module inputs, we will copy module content from one of the examples to minimize the amount of typing required. In most examples, the AVM module call is located at the bottom of the example.

Navigate to the Examples drop-down menu in the documentation and select the default example from the menu. You will see a fully functioning example code which includes the module and any supporting resources. Since we only care about the workspace resource from this example, we can scroll to the bottom of the code block and find the module "log_analytics_workspace" line.
Copy the content between the module brackets with the exception of the line defining the module source. Because these examples are part of the testing methodology for the module, they use a dot reference value (../..) for the module source value which will not work in our module call. To work around this, we copied those values from the provision instructions section of the module documentation in a previous step.
Update the location and resource group name values to reference outputs from the resource group module. Using implicit references such as these allow Terraform to determine the order in which resources should be built.
Update the name field using the prefix variable to allow for customization using a similar pattern to what we used on the resource group.

The Log Analytics module content should look like the following code block. For simplicity, you can also copy this directly to avoid multiple copy/paste actions.

➕ Expand Code

 1module "avm-res-operationalinsights-workspace" {
 2  source  = "Azure/avm-res-operationalinsights-workspace/azurerm"
 3  version = "0.4.2"
 4
 5  enable_telemetry                          = true
 6  location                                  = module.avm-res-resources-resourcegroup.resource.location
 7  resource_group_name                       = module.avm-res-resources-resourcegroup.name
 8  name                                      = "${var.name_prefix}-law"
 9  log_analytics_workspace_retention_in_days = 30
10  log_analytics_workspace_sku               = "PerGB2018"
11}

Again, we will need to run terraform init to allow Terraform to initialize a copy of the AVM Log Analytics module.

Now, we can deploy the Log Analytics workspace by running terraform apply -var-file=development.tfvars, typing yes and pressing enter. Note that Terraform will only create the new Log Analytics resources since the resource group already exists. This is one of the key benefits of deploying using Infrastructure as Code (IAC) tools like Terraform.

Note

Note that we ran the terraform apply command without first running terraform plan. Because terraform apply runs a plan before prompting for the apply, we opted to shorten the instructions by skipping the explicit plan step. If you are testing in a live environment, you may want to run the plan step and save the plan as part of your governance or change control processes.

Deploy the Azure Key Vault

Our solution calls for a simple Key Vault implementation to store virtual machine secrets. We’ll follow the same workflow for deploying the Key Vault as we used for the previous resource group and Log Analytics workspace resources. However, since Key Vaults require data roles to manage secrets and keys, we will need to use the RBAC interface and a data resource to configure Role-Based Access Control (RBAC) during the deployment.

Note

For this exercise, we will provision the deployment user with data rights on the Key Vault. In your environment, you will likely want to either provide additional roles as inputs or statically assign users, or groups to the Key Vault data roles. For simplicity we also set the Key Vault to have public access enabled due to us not being able to dictate a private deployment environment. In your environment where your deployment machine will be on a private network it is recommended to restrict public access for the Key Vault.

Before we implement the AVM module for the Key Vault, we want to use a data resource to read the client details about the user context of the current Terraform deployment.

Add the following line to your main.tf file and save it.

➕ Expand Code

1data "azurerm_client_config" "this" {}

Key vaults use a global namespace which means that we will also need to add a randomization resource to allow us to randomize the name to avoid any potential name intersection issues with other Key Vault deployments. We will use Terraform’s random provider to generate the random string which we will append to the Key Vault name. Add the following code to your main module to create the random_string resource we will use for naming.

➕ Expand Code

1resource "random_string" "name_suffix" {
2  length  = 4
3  special = false
4  upper   = false
5}

Now we can continue with adding the AVM Key Vault module to our solution.

Browse to the AVM Key Vault resource module page in the Terraform Registry.
Copy the module content from the Provision Instructions portion of the page into the main.tf file.
This time, we’re going to select relevant content from the Create secret example to fill out our module.
Copy the name, location, enable_telemetry, resource_group_name, tenant_id, and role_assignments value content from the example and paste it into the new Key Vault module in your solution.
Update the name value to be "${var.prefix}-kv-${random_string.name_suffix.result}"
Update the location and resource_group_name values to the same implicit resource group module references we used in the Log Analytics workspace.
Set the enable_telemetry value to true.
Leave the tenant_id and role_assignments values to the same values that are in the example.

Our architecture calls for us to include a diagnostic settings configuration for each resource that supports it. We’ll use the diagnostic-settings example to copy this content.

Return to the documentation page and select the diagnostic-settings option from the examples drop-down.
Locate the Key Vault resource in the example’s code block and copy the diagnostic_settings value and paste it into the Key Vault module block we’re building in main.tf.
Update the name value to use our prefix variable to allow for name customization.
Update the workspace_resource_id value to be an implicit reference to the output from the previously implemented Log Analytics module (module.avm-res-operationalinsights-workspace.resource_id in our code).

Finally, we will allow public access, so that our deployer machine can add secrets to the Key Vault. If your environment doesn’t allow public access for Key Vault deployments, locate the public IP address of your deployer machine (this may be an external NAT IP for your network) and add it to the network_acls.ip_rules list value using CIDR notation.

Set the network_acls input to null in your module block for the Key Vault.

Your Key Vault module definition should now look like the following:

➕ Expand Code

 1module "avm-res-keyvault-vault" {
 2  source  = "Azure/avm-res-keyvault-vault/azurerm"
 3  version = "0.10.0"
 4
 5  enable_telemetry    = true
 6  location            = module.avm-res-resources-resourcegroup.resource.location
 7  resource_group_name = module.avm-res-resources-resourcegroup.name
 8  name                = "${var.name_prefix}-kv-${random_string.name_suffix.result}"
 9  tenant_id           = data.azurerm_client_config.this.tenant_id
10  network_acls        = null
11
12  diagnostic_settings = {
13    to_la = {
14      name                  = "${var.name_prefix}-kv-diags"
15      workspace_resource_id = module.avm-res-operationalinsights-workspace.resource_id
16    }
17  }
18
19  role_assignments = {
20    deployment_user_kv_admin = {
21      role_definition_id_or_name = "Key Vault Administrator"
22      principal_id               = data.azurerm_client_config.this.object_id
23    }
24  }
25}

Note

One of the core values of AVM is the standard configuration for interfaces across modules. The Role Assignments interface we used as part of the Key Vault deployment is a good example of this.

Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.

Deploy the NAT Gateway

Our architecture calls for a NAT Gateway to allow virtual machines to access the internet. We will use the NAT Gateway resource_id output in future modules to link the virtual machine subnet.

Browse to the AVM NAT Gateway resource module page in the Terraform Registry.
Copy the module definition and source from the Provision Instructions card from the module main page.
Copy the remaining module content from the default example excluding the subnet associations map, as we will do the association when we build the vnet.
Update the location and resource_group_nameusing implicit references from our resource group module.
Then update each of the name values to use the name_prefix variables.

Review the following code to see each of these changes.

➕ Expand Code

 1module "avm-res-network-natgateway" {
 2  source  = "Azure/avm-res-network-natgateway/azurerm"
 3  version = "0.2.1"
 4
 5  name                = "${var.name_prefix}-natgw"
 6  enable_telemetry    = true
 7  location            = module.avm-res-resources-resourcegroup.resource.location
 8  resource_group_name = module.avm-res-resources-resourcegroup.name
 9
10  public_ips = {
11    public_ip_1 = {
12      name = "${var.name_prefix}-natgw-pip"
13    }
14  }
15}

Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.

Deploy the Network Security Group

Our architecture calls for a Network Security Group (NSG) allowing SSH access to the virtual machine subnet. We will use the NSG AVM resource module to accomplish this task.

Browse to the AVM Network Security Group resource module page in the Terraform Registry.
Copy the module definition and source from the Provision Instructions card from the module main page.
Copy the remaining module content from the example_with_NSG_rule example.
Update the location and resource_group_nameusing implicit references from our resource group module.
Update the name value using the name_prefix variable interpolation as we did with the other modules.
Copy the map entry labeled rule02 from the locals nsg_rules map and paste it between two curly braces to create the security_rules attribute in the NSG module we’re building.
Make the following updates to the rule details:
1. Rename the map key to "rule01" from "rule02".
2. Update the name to use the var.prefix interpolation and SSH to describe the rule.
3. Update the destination_port_ranges list to be ["22"].

Upon completion the code for the NSG module should be as follows:

➕ Expand Code

 1module "avm-res-network-networksecuritygroup" {
 2  source  = "Azure/avm-res-network-networksecuritygroup/azurerm"
 3  version = "0.4.0"
 4  resource_group_name = module.avm-res-resources-resourcegroup.name
 5  name                = "${var.name_prefix}-vm-subnet-nsg"
 6  location            = module.avm-res-resources-resourcegroup.resource.location
 7
 8  security_rules = {
 9    "rule01" = {
10      name                       = "${var.name_prefix}-ssh"
11      access                     = "Allow"
12      destination_address_prefix = "*"
13      destination_port_ranges    = ["22"]
14      direction                  = "Inbound"
15      priority                   = 200
16      protocol                   = "Tcp"
17      source_address_prefix      = "*"
18      source_port_range          = "*"
19    }
20  }
21}

Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.

Deploy the Virtual Network

We can now continue the build-out of our architecture by configuring the virtual network (vnet) deployment. This will follow a similar pattern as the previous resource modules, but this time, we will also add some network functions to help us customize the subnet configurations.

Browse to the AVM Virtual Network resource module page in the Terraform Registry.
Copy the module definition and source from the Provision Instructions card from the module main page.
After looking through the examples, this time, we’ll use the complete example as a source to copy our content.
Copy the resource_group_name, location, name, and address_space lines and replace their values with our deployment specific variables or module references.
We’ll copy the subnets map and duplicate the subnet0 map for each subnet.
Now we will update the map key and name values for each subnet so that they are unique.
Then we’ll use the cidrsubnet function to dynamically generate the CIDR range for each subnet. You can explore the function documentation for more details on how it can be used.
We will also populate the nat_gateway object on subnet0 with the resource_id output from our NAT Gateway module.
To configure the NSG on the VM subnet we need to link it. Add a network_security_group attribute to the subnet0 definition and replace the value with the resource_id output from the NSG module.
Finally, we’ll copy the diagnostic settings from the example and update the implicit references to point to our previously deployed Log Analytics workspace.

After making these changes our virtual network module call code will be as follows:

➕ Expand Code

 1module "avm-res-network-virtualnetwork" {
 2  source  = "Azure/avm-res-network-virtualnetwork/azurerm"
 3  version = "0.8.1"
 4
 5  resource_group_name = module.avm-res-resources-resourcegroup.name
 6  location            = module.avm-res-resources-resourcegroup.resource.location
 7  name                = "${var.name_prefix}-vnet"
 8
 9  address_space = [var.virtual_network_cidr]
10
11  subnets = {
12    subnet0 = {
13      name                            = "${var.name_prefix}-vm-subnet"
14      default_outbound_access_enabled = false
15      address_prefixes = [cidrsubnet(var.virtual_network_cidr, 1, 0)]
16      nat_gateway = {
17        id = module.avm-res-network-natgateway.resource_id
18      }
19      network_security_group = {
20        id = module.avm-res-network-networksecuritygroup.resource_id
21      }
22    }
23    bastion = {
24      name                            = "AzureBastionSubnet"
25      default_outbound_access_enabled = false
26      address_prefixes = [cidrsubnet(var.virtual_network_cidr, 1, 1)]
27    }
28  }
29
30  diagnostic_settings = {
31    sendToLogAnalytics = {
32      name                           = "${var.name_prefix}-vnet-diagnostic"
33      workspace_resource_id          = module.avm-res-operationalinsights-workspace.resource_id
34      log_analytics_destination_type = "Dedicated"
35    }
36  }
37}

Note

Note how the Log Analytics workspace reference ends in resource_id. Each AVM module is required to export its Azure resource ID with the resource_id name to allow for consistent references.

Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.

Deploy the Bastion service

We want to allow for secure remote access to the virtual machine for configuration and troubleshooting tasks. We’ll use Azure Bastion to accomplish this objective following a similar workflow to our other resources.

Browse to the AVM Bastion resource module page in the Terraform Registry.
Copy the module definition and source from the Provision Instructions card from the module main page.
Copy the remaining module content from the Simple Deployment example.
Update the location and resource_group_nameusing implicit references from our resource group module.
Update the name value using the name_prefix variable interpolation as we did with the other modules.
Finally, update the subnet_id value to include an implicit reference to the bastion keyed subnet from our virtual network module.

Our architecture calls for diagnostic settings to be configured on the Azure Bastion resource. In this case, there aren’t any examples that include this configuration. However, since the diagnostic settings interface is one of the standard interfaces in Azure Verified Modules, we can just copy the interface definition from our virtual network module.

Locate the virtual network module and copy the diagnostic_settings value from it.
Paste the diagnostic_settings value into the code for our Bastion module.
Update the diagnostic setting’s name value from vnet to Bastion.

The new code we added for the Bastion resource will be as follows:

➕ Expand Code

 1module "avm-res-network-bastionhost" {
 2  source  = "Azure/avm-res-network-bastionhost/azurerm"
 3  version = "0.7.2"
 4
 5  name                = "${var.name_prefix}-bastion"
 6  resource_group_name = module.avm-res-resources-resourcegroup.name
 7  location            = module.avm-res-resources-resourcegroup.resource.location
 8  ip_configuration = {
 9    subnet_id = module.avm-res-network-virtualnetwork.subnets["bastion"].resource_id
10  }
11
12  diagnostic_settings = {
13    sendToLogAnalytics = {
14      name                           = "${var.name_prefix}-bastion-diagnostic"
15      workspace_resource_id          = module.avm-res-operationalinsights-workspace.resource_id
16      log_analytics_destination_type = "Dedicated"
17    }
18  }
19}

Note

Pay attention to the subnet_id syntax. In the virtual network module, the subnets are created as a sub-module allowing us to reference each of them using the map key that was defined in the subnets input. Again, we see the consistent output naming with the resource_id output for the sub-module.

Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.

Deploy the virtual machine

The final step in our deployment will be our application virtual machine. We’ve had good success with our workflow so far, so we’ll use it for this step as well.

Browse to the AVM Virtual Machine resource module page in the Terraform Registry.
Copy the module definition and source from the Provision Instructions card from the module main page.
Copy the remaining module content from the linux_default example.
Update the location and resource_group_nameusing implicit references from our resource group module.
To be compliant with Well Architected Framework guidance we encourage defining a zone if your region supports it. Update the zone input to 1.
Update the sku_size input to “Standard_D2s_v5”.
Update the name values using the name_prefix variable interpolation as we did with the other modules and include the output from the random_string.name_suffix resource to add uniqueness.
Set the account_credentials.key_vault_configuration.resource_id value to reference the resource_id output from the Key Vault module.
Update the private_ip_subnet_resource_id value to an implicit reference to the subnet0 subnet output from the virtual network module.

Because the default Linux example doesn’t include diagnostic settings, we need to add that content in a different way. Since the diagnostic settings interface has a standard schema, we can copy the diagnostic_settings input from our virtual network module.

Locate the virtual network module in your code and copy the diagnostic_settings map from it.
Paste the diagnostic_settings content into your virtual machine module code.
Update the name value to reflect that it applies to the virtual machine.

The new code we added for the virtual machine resource will be as follows:

➕ Expand Code

 1module "avm-res-compute-virtualmachine" {
 2  source  = "Azure/avm-res-compute-virtualmachine/azurerm"
 3  version = "0.19.1"
 4
 5  enable_telemetry    = true
 6  location            = module.avm-res-resources-resourcegroup.resource.location
 7  resource_group_name = module.avm-res-resources-resourcegroup.name
 8  name                = "${var.name_prefix}-vm"
 9  os_type             = "Linux"
10  sku_size            = "Standard_D2s_v5"
11  zone                = 1
12
13  source_image_reference = {
14    publisher = "Canonical"
15    offer     = "0001-com-ubuntu-server-focal"
16    sku       = "20_04-lts-gen2"
17    version   = "latest"
18  }
19
20  network_interfaces = {
21    network_interface_1 = {
22      name = "${var.name_prefix}-nic-${random_string.name_suffix.result}"
23      ip_configurations = {
24        ip_configuration_1 = {
25          name                          = "${var.name_prefix}-ipconfig-${random_string.name_suffix.result}"
26          private_ip_subnet_resource_id = module.avm-res-network-virtualnetwork.subnets["subnet0"].resource_id
27        }
28      }
29    }
30  }
31
32  diagnostic_settings = {
33    sendToLogAnalytics = {
34      name                           = "${var.name_prefix}-vm-diagnostic"
35      workspace_resource_id          = module.avm-res-operationalinsights-workspace.resource_id
36      log_analytics_destination_type = "Dedicated"
37    }
38  }
39}

Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.

Creating the outputs.tf file

The final piece of our module is to export any values that may need to be consumed by module users. From our architecture, we’ll export the resource group name and the virtual machine resource name.

Create an outputs.tf file in your IDE.
Create an output named resource_group_name and set the value to an implicit reference to the resource group modules name output. Include a brief description for the output.
Create an output named virtual_machine_name and set the value to an implicit reference to the virtual machine module’s name output. Include a brief description for the output.

The new code we added for the outputs will be as follows:

➕ Expand Code

1output "resource_group_name" {
2  value =  module.avm-res-resources-resourcegroup.name
3  description = "The resource group name where the resources are deployed"
4}
5
6output "virtual_machine_name" {
7    value = module.avm-res-compute-virtualmachine.name
8    description = "The name of the virtual machine"
9}

Because no new modules were created, we don’t need to run terraform init to test this change. Run terraform apply -var-file=development.tfvars to see the new outputs that have been created.

Update the terraform.tf file

It is a recommended practice to define the required versions of the providers for your module to ensure consistent behavior when it is being run. In this case we are going to be slightly permissive and allow increases in minor and patch versions to fluctuate, since those are not supposed to include breaking changes. In a production environment, you would likely want to pin on a specific version to guarantee behavior.

Run terraform init to review the providers and versions that are currently installed.
Update your terraform.tf file’s required providers field for each provider listed in the downloaded providers.

The updated code we added for the providers in the terraform.tf file will be as follows:

➕ Expand Code

 1terraform {
 2  required_version = "~> 1.9"
 3  required_providers {
 4    azapi = {
 5      source  = "azure/azapi"
 6      version = "~> 2.3"
 7    }
 8    azurerm = {
 9      source  = "hashicorp/azurerm"
10      version = "~> 4.27"
11    }
12    modtm = {
13      source  = "azure/modtm"
14      version = "~> 0.3"
15    }
16    random = {
17      source  = "hashicorp/random"
18      version = "~> 3.7"
19    }
20    time = {
21      source  = "hashicorp/time"
22      version = "~> 0.13"
23    }
24    tls = {
25      source  = "hashicorp/tls"
26      version = "~> 4.1"
27    }
28  }
29}
30
31provider "azurerm" {
32  features {
33  }
34}

Conclusion

Congratulations on successfully implementing a solution using Azure Verified Modules! You were able to build out our sample architecture using module documentation and taking advantage of features like standard interfaces and pre-defined defaults to simplify the development experience.

Note

This was a long exercise and mistakes can happen. If you’re getting errors or a resource is incomplete and you want to see the final main.tf, expand the following code block to see the full file.

➕ Expand Code

  1module "avm-res-resources-resourcegroup" {
  2  source  = "Azure/avm-res-resources-resourcegroup/azurerm"
  3  version = "0.2.1"
  4
  5  name = "${var.name_prefix}-rg"
  6  location = var.location
  7  tags = var.tags
  8}
  9
 10module "avm-res-operationalinsights-workspace" {
 11  source  = "Azure/avm-res-operationalinsights-workspace/azurerm"
 12  version = "0.4.2"
 13
 14  enable_telemetry                          = true
 15  location                                  = module.avm-res-resources-resourcegroup.resource.location
 16  resource_group_name                       = module.avm-res-resources-resourcegroup.name
 17  name                                      = "${var.name_prefix}-law"
 18  log_analytics_workspace_retention_in_days = 30
 19  log_analytics_workspace_sku               = "PerGB2018"
 20}
 21
 22data "azurerm_client_config" "this" {}
 23
 24resource "random_string" "name_suffix" {
 25  length  = 4
 26  special = false
 27  upper   = false
 28}
 29
 30module "avm-res-keyvault-vault" {
 31  source  = "Azure/avm-res-keyvault-vault/azurerm"
 32  version = "0.10.0"
 33
 34  enable_telemetry    = true
 35  location            = module.avm-res-resources-resourcegroup.resource.location
 36  resource_group_name = module.avm-res-resources-resourcegroup.name
 37  name                = "${var.name_prefix}-kv-${random_string.name_suffix.result}"
 38  tenant_id           = data.azurerm_client_config.this.tenant_id
 39  network_acls        = null
 40
 41  diagnostic_settings = {
 42    to_la = {
 43      name                  = "${var.name_prefix}-kv-diags"
 44      workspace_resource_id = module.avm-res-operationalinsights-workspace.resource_id
 45    }
 46  }
 47
 48  role_assignments = {
 49    deployment_user_kv_admin = {
 50      role_definition_id_or_name = "Key Vault Administrator"
 51      principal_id               = data.azurerm_client_config.this.object_id
 52    }
 53  }
 54}
 55
 56module "avm-res-network-natgateway" {
 57  source  = "Azure/avm-res-network-natgateway/azurerm"
 58  version = "0.2.1"
 59
 60  name                = "${var.name_prefix}-natgw"
 61  enable_telemetry    = true
 62  location            = module.avm-res-resources-resourcegroup.resource.location
 63  resource_group_name = module.avm-res-resources-resourcegroup.name
 64
 65  public_ips = {
 66    public_ip_1 = {
 67      name = "${var.name_prefix}-natgw-pip"
 68    }
 69  }
 70}
 71
 72module "avm-res-network-virtualnetwork" {
 73  source  = "Azure/avm-res-network-virtualnetwork/azurerm"
 74  version = "0.8.1"
 75
 76  resource_group_name = module.avm-res-resources-resourcegroup.name
 77  location            = module.avm-res-resources-resourcegroup.resource.location
 78  name                = "${var.name_prefix}-vnet"
 79
 80  address_space = [var.virtual_network_cidr]
 81
 82  subnets = {
 83    subnet0 = {
 84      name                            = "${var.name_prefix}-vm-subnet"
 85      default_outbound_access_enabled = false
 86      address_prefixes = [cidrsubnet(var.virtual_network_cidr, 1, 0)]
 87      nat_gateway = {
 88        id = module.avm-res-network-natgateway.resource_id
 89      }
 90      network_security_group = {
 91        id = module.avm-res-network-networksecuritygroup.resource_id
 92      }
 93    }
 94    bastion = {
 95      name                            = "AzureBastionSubnet"
 96      default_outbound_access_enabled = false
 97      address_prefixes = [cidrsubnet(var.virtual_network_cidr, 1, 1)]
 98    }
 99  }
100
101  diagnostic_settings = {
102    sendToLogAnalytics = {
103      name                           = "${var.name_prefix}-vnet-diagnostic"
104      workspace_resource_id          = module.avm-res-operationalinsights-workspace.resource_id
105      log_analytics_destination_type = "Dedicated"
106    }
107  }
108}
109
110module "avm-res-network-bastionhost" {
111  source  = "Azure/avm-res-network-bastionhost/azurerm"
112  version = "0.7.2"
113
114  name                = "${var.name_prefix}-bastion"
115  resource_group_name = module.avm-res-resources-resourcegroup.name
116  location            = module.avm-res-resources-resourcegroup.resource.location
117  ip_configuration = {
118    subnet_id = module.avm-res-network-virtualnetwork.subnets["bastion"].resource_id
119  }
120
121  diagnostic_settings = {
122    sendToLogAnalytics = {
123      name                           = "${var.name_prefix}-bastion-diagnostic"
124      workspace_resource_id          = module.avm-res-operationalinsights-workspace.resource_id
125      log_analytics_destination_type = "Dedicated"
126    }
127  }
128}
129
130module "avm-res-network-networksecuritygroup" {
131  source  = "Azure/avm-res-network-networksecuritygroup/azurerm"
132  version = "0.4.0"
133  resource_group_name = module.avm-res-resources-resourcegroup.name
134  name                = "${var.name_prefix}-vm-subnet-nsg"
135  location            = module.avm-res-resources-resourcegroup.resource.location
136
137  security_rules = {
138    "rule01" = {
139      name                       = "${var.name_prefix}-ssh"
140      access                     = "Allow"
141      destination_address_prefix = "*"
142      destination_port_ranges    = ["22"]
143      direction                  = "Inbound"
144      priority                   = 200
145      protocol                   = "Tcp"
146      source_address_prefix      = "*"
147      source_port_range          = "*"
148    }
149  }
150}
151
152module "avm-res-compute-virtualmachine" {
153  source  = "Azure/avm-res-compute-virtualmachine/azurerm"
154  version = "0.19.1"
155
156  enable_telemetry    = true
157  location            = module.avm-res-resources-resourcegroup.resource.location
158  resource_group_name = module.avm-res-resources-resourcegroup.name
159  name                = "${var.name_prefix}-vm"
160  os_type             = "Linux"
161  sku_size            = "Standard_D2s_v5"
162  zone                = 1
163
164  source_image_reference = {
165    publisher = "Canonical"
166    offer     = "0001-com-ubuntu-server-focal"
167    sku       = "20_04-lts-gen2"
168    version   = "latest"
169  }
170
171  network_interfaces = {
172    network_interface_1 = {
173      name = "${var.name_prefix}-nic-${random_string.name_suffix.result}"
174      ip_configurations = {
175        ip_configuration_1 = {
176          name                          = "${var.name_prefix}-ipconfig-${random_string.name_suffix.result}"
177          private_ip_subnet_resource_id = module.avm-res-network-virtualnetwork.subnets["subnet0"].resource_id
178        }
179      }
180    }
181  }
182
183  diagnostic_settings = {
184    sendToLogAnalytics = {
185      name                           = "${var.name_prefix}-vm-diagnostic"
186      workspace_resource_id          = module.avm-res-operationalinsights-workspace.resource_id
187      log_analytics_destination_type = "Dedicated"
188    }
189  }
190}

AVM modules provide several key advantages over writing raw Terraform templates:

Simplified Resource Configuration: AVM modules handle much of the complex configuration work behind the scenes
Built-in Recommended Practices: The modules implement many of Microsoft’s recommended practices by default
Consistent Outputs: Each module exposes a consistent set of outputs that can be easily referenced
Reduced Boilerplate Code: What would normally require hundreds of lines of Terraform code can be accomplished in a fraction of the space

Additional exercises

For additional learning, it can be helpful to experiment with modifying this solution. Here are some ideas you can try if you have time and would like to experiment further.

Use the managed_identities interface to add a system assigned managed identity to the virtual machine and give it Key Vault Administrator rights on the Key Vault.
Use the tags interface to assign tags directly to one or more resources.
Add an Azure Monitoring Agent extension to the virtual machine resource.
Add additional inputs like VM sku to your module to make it more customizable. Be sure to update the code and tfvars files to match.

Clean up your environment

Once you have completed this set of exercises, it is a good idea to clean up your resources to avoid incurring costs for them. This can be done typing terraform destroy -var-file=development.tfvars and entering yes when prompted.

Solution Development

Considerations and steps of Solution Development

Decide on the IaC language (Bicep or Terraform)
Decide on the module sourcing method (public registry, private registry, inner-sourcing)
Decide on the orchestration method (template or pipeline)
Identify the resources needed for the solution (are they all available in AVM?)
Implement, validate, deploy, test the solution

Questions to cover on this page

Pick a realistically complex solution and demonstrate how to build it using AVM modules
Best practices for coding (link to official language specific guidance AND AVM specs where/if applicable)
Best practices for input and output parameters

Next steps

To be covered in separate, future articles.

To make this solution enterprise-ready, you need to consider the following:

Deploy with DevOps tools and practices (e.g., CI/CD in Azure DevOps, GitHub Actions, etc.)
Deploy into Azure Landing Zones (ALZ)
Make sure the solution follows the recommendations of the Well-Architected Framework (WAF) and it’s compliant with and integrates into your organization’s policies and standards, e.g.:
- Security & Identity (e.g., RBAC, Entra ID, service principals, secrets management, MFA, etc.)
- Networking (e.g., Azure Firewall, NSGs, etc.)
- Monitoring (e.g., Azure Monitor, Log Analytics, etc.)
- Cost management (e.g., Azure Cost Management, budgets, etc.)
- Governance (e.g., Azure Policy, etc.)

Other recommendations

Don’t use latest, but a specific version of the module
Don’t expose secrets in output parameters/command line/logs/etc.
Don’t use hard-coded values, but use parameters and variables

Bicep Prerequisites

You will need the following tools and components to complete this guide:

Visual Studio Code (VS Code) to develop your solution.
Bicep Visual Studio Code Extension to author your Bicep template and explore modules published in the Registry.
One of the following command line tools:
- PowerShell AND Azure PowerShell
- Azure CLI to deploy your solution.
Bicep CLI
Azure Subscription to deploy your Bicep templates.

Quickstart Guide

This QuickStart guide offers step-by-step instructions for integrating Azure Verified Modules (AVM) into your solutions. It includes the initial setup, essential tools, and configurations required to deploy and manage your Azure resources efficiently using AVM.

The AVM Key Vault resource module, used as an example in this chapter, simplifies the deployment and management of Azure Key Vaults, ensuring secure storage and access to your secrets, keys, and certificates.

Leveraging Azure Verified Modules

Using AVM ensures that your infrastructure-as-code deployments follow Microsoft’s best practices and guidelines, providing a consistent and reliable foundation for your cloud solutions. AVM helps accelerate your development process, reduce the risk of misconfigurations, and enhance the security and compliance of your applications.

Using default values

The default values provided by AVM are generally safe, as they follow best practices and ensure a secure and reliable setup. However, it is important to review these values to ensure they meet your specific requirements and compliance needs. Customizing the default values may be necessary to align with your organization’s policies and the specific needs of your solution.

Exploring examples and module features

You can find examples and detailed documentation for each AVM module in their respective code repository’s README.MD file, which details features, input parameters, and outputs. The module’s documentation also provides comprehensive usage examples, covering various scenarios and configurations. Additionally, you can explore the module’s source code repository. This information will help you understand the full capabilities of the module and how to effectively integrate it into your solutions.

Bicep Quickstart Guide

Introduction

This guide explains how to use an Azure Verified Modules (AVM) in your Bicep workflow. By leveraging AVM modules, you can rapidly deploy and manage Azure infrastructure without having to write extensive code from scratch.

In this guide, you will deploy a Key Vault resource and a Personal Access Token as a secret.

This article is intended for a typical ‘infra-dev’ user (cloud infrastructure professional) who has a basic understanding of Azure and Bicep but is new to Azure Verified Modules and wants to learn how to deploy a module in the easiest way using AVM.

For additional Bicep learning resources use the Bicep documentation on the Microsoft Learn platform, or leverage the Fundamentals of Bicep learning path.

Prerequisites

title: “Bicep Prerequisites”
description: “Learn about the prerequisites for using Bicep to deploy Azure Verified Modules or develop them.”

You will need the following tools and components to complete this guide:

Visual Studio Code (VS Code) to develop your solution.
Bicep Visual Studio Code Extension to author your Bicep template and explore modules published in the Registry.
One of the following command line tools:
- PowerShell AND Azure PowerShell
- Azure CLI to deploy your solution.
Bicep CLI
Azure Subscription to deploy your Bicep templates.

Make sure you have these tools set up before proceeding.

Module Discovery

Find your module

In this scenario, you need to deploy a Key Vault resource and some of its child resources, such as a secret. Let’s find the AVM module that will help us achieve this.

There are two primary ways for locating published Bicep Azure Verified Modules:

Option 1 (preferred): Using IntelliSense in the Bicep extension of Visual Studio Code, and
Option 2: browsing the AVM Bicep module index.

Option 1: Use the Bicep Extension in VS Code

In VS Code, create a new file called main.bicep.
Start typing module, then give your module a symbolic name, such as myModule.
Use IntelliSense to select br/public.
The list of all AVM modules published in the Bicep Public Registry will show up. Use this to explore the published modules.
Note
The Bicep VSCode extension is reading metadata through this JSON file. All modules are added to this file, as part of the publication process. This lists all the modules marked as Published or Orphaned on the AVM Bicep module index pages.
Select the module you want to use and the version you want to deploy. Note how you can type full or partial module names to filter the list.
Right click on the module’s path and select Go to definition or hit F12 to see the module’s source code. You can toggle between the Bicep and the JSON view.
Hover over the module’s symbolic name to view its documentation URL. By clicking on it, you will be directed to the module’s GitHub folder in the bicep-registry-modules (BRM) repository. There, you can access the source code and documentation, as illustrated below.

Option 2: Use the AVM Bicep Module Index

Searching the Azure Verified Modules indexes is the most complete way to discover published as well as planned (proposed) modules. As shown in the video above, use the following steps to locate a specific module on the AVM website:

Open the AVM website in your favorite web browser: https://aka.ms/avm.
Expand the Module Indexes menu item and select the Bicep sub-menu item.
Select the menu item for the module type you are searching for: Resource, Pattern, or Utility.
Note
Since the Key Vault module used as an example in this guide is published as an AVM resource module, it can be found under the resource modules section in the AVM Bicep module index.
A detailed description of module classification types can be found under the related section here.
Select the Published modules link from the table of contents at the top of the page.
Use the in-page search feature of your browser. In most Windows browsers you can access it using the CTRL + F keyboard shortcut.
Enter a search term to find the module you are looking for - e.g., Key Vault.
Move through the search results until you locate the desired module. If you are unable to find a published module, return to the table of contents and expand the All modules link to search both published and proposed modules - i.e., modules that are planned, likely in development but not published yet.
After finding the desired module, click on the module’s name. This link will lead you to the module’s folder in the bicep-registry-modules (BRM) repository, where the module’s source code and documentation can be found, including usage examples.

Module details and examples

In the module’s documentation, you can find detailed information about the module’s functionality, components, input parameters, outputs and more. The documentation also provides comprehensive usage examples, covering various scenarios and configurations.

Explore the Key Vault module’s documentation for usage examples and to understand its functionality, input parameters, and outputs.

Note the mandatory and optional parameters in the Parameters section.
Review the Usage examples section. AVM modules include multiple tests that can be found under the tests folder. These tests are also used as the basis of the usage examples ensuring they are always up-to-date and deployable.

In this example, you will deploy a secret in a new Key Vault instance with minimal input. AVM provides default parameter values with security and reliability being core principles. These settings apply the recommendations of the Well Architected Framework where possible and appropriate.

Note how Example 2 does most of what you need to achieve.

Create your new solution using AVM

In this section, you will develop a Bicep template that references the AVM Key Vault module and its child resources and features. These include secret and role based access control configurations that grant permissions to a user.

Start VSCode (make sure the Bicep extension is installed) and open a folder in which you want to work.
Create a main.bicep and a dev.bicepparam file, which will hold parameters for your Key Vault deployment.
Copy the content below into your main.bicep file. We have included comments to distinguish between the two different occurrences of the names attribute.

module myKeyVault 'br/public:avm/res/key-vault/vault:0.11.0' = {
  name: // the name of the module's deployment
  params: {
    name: '<keyVaultName>' // the name of the Key Vault instance - length and character limits apply
  }
}

Note

For Azure Key Vaults, the name must be globally unique. When you deploy the Key Vault, ensure you select a name that is alphanumeric, twenty-four characters or less, and unique enough to ensure no one else has used the name for their Key Vault. If the name has been previously taken, you will get an error.

After setting the values for the required properties, the module can be deployed. This minimal configuration automatically applies the security and reliability recommendations of the Well Architected Framework where possible and appropriate. These settings can be overridden if needed.

Bicep-specific configuration

It is recommended to create a bicepconfig.json file, and enable use-recent-module-versions, which warns you to use the latest available version of the AVM module.

// This is a Bicep configuration file. It can be used to control how Bicep operates and to customize
// validation settings for the Bicep linter. The linter relies on these settings when evaluating your
// Bicep files for best practices. For further information, please refer to the official documentation at:
// https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-config
{
  "analyzers": {
    "core": {
      "rules": {
        "use-recent-module-versions": {
          "level": "warning",
          "message": "The module version is outdated. Please consider updating to the latest version."
        }
      }
    }
  }
}

Define the Key Vault instance

In this scenario - and every other real-world setup - there is more that you need to configure. You can open the module’s documentation by hovering over its symbolic name to see all of the module’s capabilities - including supported parameters.

Note

The Bicep extension facilitates code-completion, enabling you to easily locate and utilize the Azure Verified Module. This feature also provides the necessary properties for a module, allowing you to begin typing and leverage IntelliSense for completion.

Add parameters and values to the main.bicep file to customize your configuration. These parameters are used for passing in the Key Vault name and enabling purge protection. You might not want to enable the latter in a non-production environment, as it makes it harder to delete and recreate resources.

The main.bicep file will now look like this:

// the scope, the deployment deploys resources to
targetScope = 'resourceGroup'

// parameters and default values
param keyVaultName string

@description('Disable for development deployments.')
param enablePurgeProtection bool = true

// the resources to deploy
module myKeyVault 'br/public:avm/res/key-vault/vault:0.11.0' = {
  name: 'key-vault-deployment'
  params: {
    name: keyVaultName
    enablePurgeProtection: enablePurgeProtection
    // more properties are not needed, as AVM provides default values
  }
}

Note that the Key Vault instance will be deployed within a resource group scope in our example.

Create a dev.bicepparam file (this is optional) and set parameter values for your environment. You can now pass these values by referencing this file at the time of deployment (using PowerShell or Azure CLI).

using 'main.bicep'

// environment specific values
param keyVaultName = '<keyVaultName>'
param enablePurgeProtection = false

Create a secret and set permissions

Add a secret to the Key Vault instance and grant permissions to a user to work with the secret. Sample role assignments can be found in Example 3: Using large parameter set. See Parameter: roleAssignments for a list of pre-defined roles that you can reference by name instead of a GUID. This is a key benefit of using AVM, as the code is easy to read and increases the maintainability.

You can also leverage User-defined data types and simplify the parameterization of the modules instead of guessing or looking up parameters. Therefore, first import UDTs from the Key Vault and common types module and leverage the UDTs in your Bicep and parameter files.

For a role assignment, the principal ID is needed, that will be granted a role (specified by its name) on the resource. Your own ID can be found out with az ad signed-in-user show --query id.

// the scope, the deployment deploys resources to
targetScope = 'resourceGroup'

// parameters and default values
param keyVaultName string
// the PAT token is a secret and should not be stored in the Bicep(parameter) file.
// It can be passed via the commandline, if you don't use a parameter file.
@secure()
param patToken string = newGuid()

@description('Enabled by default. Disable for development deployments')
param enablePurgeProtection bool = true

import { roleAssignmentType } from 'br/public:avm/utl/types/avm-common-types:0.4.0'
// the role assignments are optional in the Key Vault module
param roleAssignments roleAssignmentType[]?

// the resources to deploy
module myKeyVault 'br/public:avm/res/key-vault/vault:0.11.0' = {
  name: 'key-vault-deployment'
  params: {
    name: keyVaultName
    enablePurgeProtection: enablePurgeProtection
    secrets: [
      {
        name: 'PAT'
        value: patToken
      }
    ]
    roleAssignments: roleAssignments
  }
}

The secrets parameter references a UDT (User-defined data type) that is part of the Key Vault module and enables code completion for easy usage. There is no need to look up what attributes the secret object might have. Start typing and tab-complete what you need from the content offered by the Bicep extension’s integration with AVM.

The bicep parameter file now looks like this:

// reference to the Bicep file to set the context
using 'main.bicep'

// environment specific values
param keyVaultName = '<keyVaultName>'
param enablePurgeProtection = false
// for security reasons, the secret value must not be stored in this file.
// You can change it later in the deployed Key Vault instance, where you also renew it after expiration.

param roleAssignments = [
  {
    principalId: '<principalId>'
    // using the name of the role instead of looking up the GUID (which can also be used)
    roleDefinitionIdOrName: 'Key Vault Secrets Officer'
  }
]

Note

The display names for roleDefinitionIdOrName can be acquired the following two ways:

From the parameters section of the module’s documentation.
From the builtInRoleNames variable in the module’s source code. To get there, hit F12 while the cursor is on the part of the module path starting with br/public:.

Boost your development with VS Code IntelliSense

Leverage the IntelliSense feature in VS Code to speed up your development process. IntelliSense provides code completion, possible parameter values and structure. It helps you write code more efficiently by providing context-aware suggestions as you type.

Here is how quickly you can deliver the solution detailed in this section:

Deploy your solution

Now that your template and parameter file is ready, you can deploy your solution to Azure. Use PowerShell or the Azure CLI to deploy your solution.

Deploy with

# Log in to Azure
Connect-AzAccount

# Select your subscription
Set-AzContext -SubscriptionId '<subscriptionId>'

# Deploy a resource group
New-AzResourceGroup -Name 'avm-quickstart-rg' -Location 'germanywestcentral'

# Invoke your deployment
New-AzResourceGroupDeployment -DeploymentName 'avm-quickstart-deployment' -ResourceGroupName 'avm-quickstart-rg' -TemplateParameterFile 'dev.bicepparam' -TemplateFile 'main.bicep'

# Log in to Azure
az login

# Select your subscription
az account set --subscription '<subscriptionId>'

# Deploy a resource group
az group create --name 'avm-quickstart-rg' --location 'germanywestcentral'

# Invoke your deployment
az deployment group create --name 'avm-quickstart' --resource-group 'avm-quickstart-rg' --template-file 'main.bicep' --parameters 'dev.bicepparam'

Use the Azure portal, Azure PowerShell, or the Azure CLI to verify that the Key Vault instance and secret have been successfully created with the correct configuration.

Clean up your environment

When you are ready, you can remove the infrastructure deployed in this example. The following commands will remove all resources created by your deployment:

Clean up with

# Delete the resource group
Remove-AzResourceGroup -Name "avm-quickstart-rg" -Force

# Purge the Key Vault
Remove-AzKeyVault -VaultName "<keyVaultName>" -Location "germanywestcentral" -InRemovedState -Force

# Delete the resource group
az group delete --name 'avm-quickstart-rg' --yes --no-wait

# Purge the Key Vault
az keyvault purge --name '<keyVaultName>' --no-wait

Congratulations, you have successfully leveraged an AVM Bicep module to deploy resources in Azure!

Tip

We welcome your contributions and feedback to help us improve the AVM modules and the overall experience for the community!

Next Steps

For developing a more advanced solution, please see the lab titled “Introduction to using Azure Verified Modules for Bicep”.

Terraform Quickstart Guide

Introduction

This guide explains how to use an Azure Verified Modules (AVM) in your Terraform workflow. With AVM modules, you can quickly deploy and manage Azure infrastructure without writing extensive code from scratch.

In this guide, you will deploy a Key Vault resource and generate and store a key.

This article is intended for a typical ‘infra-dev’ user (cloud infrastructure professional) who is new to Azure Verified Modules and wants to learn how to deploy a module in the easiest way using AVM. The user has a basic understanding of Azure and Terraform.

For additional Terraform resources, try a tutorial on the HashiCorp website or study the detailed documentation.

Prerequisites

title: “Terraform Prerequisites”
description: “Learn about the prerequisites for using Terraform to deploy Azure Verified Modules or develop them.”

You will need the following tools and components to complete this guide:

Visual Studio Code (VS Code) to develop your solution.
Terraform CLI to deploy your Terraform modules. Make sure you have a recent version installed.
Azure CLI to authenticate to Azure.
Azure Subscription to deploy your resources.

Before you begin, ensure you have these tools installed in your development environment.

Module Discovery

Find your module

In this scenario, you need to deploy a Key Vault resource and some of its child resources, such as a key. Let’s find the AVM module that will help us achieve this.

There are two primary ways for locating published Terraform Azure Verified Modules:

Searching the official Terraform Registry, and
Browsing theAVM Terraform module index.

Use the Terraform Registry

The easiest way to find published AVM Terraform modules is by searching the Terraform Registry. Follow these steps to locate a specific module, as shown in the video above.

Use your web browser to go to the HashiCorp Terraform Registry
In the search bar at the top of the screen type avm. Optionally, append additional search terms to narrow the search results. (e.g., avm key vault for AVM modules with Key Vault in the name.)
Select see all to display the full list of published modules matching your search criteria.
Find the module you wish to use and select it from the search results.

Note

It is possible to discover other unofficial modules with avm in the name using this search method. Look for the Partner tag in the module title to determine if the module is part of the official set.

Use the AVM Terraform Module Index

Searching the Azure Verified Modules indexes is the most complete way to discover published as well as planned modules - shown as proposed. As presented in the video above, use the following steps to locate a specific module on the AVM website:

Use your web browser to open the AVM website at https://aka.ms/avm.
Expand the Module Indexes menu item and select the Terraform sub-menu item.
Select the menu item for the module type you are searching for: Resource, Pattern, or Utility.
Note
Since the Key Vault module used as an example in this guide is published as an AVM resource module, it can be found under the resource modules section in the AVM Terraform module index.
A detailed description of each module classification type can be found under the related section here.
Select the Published modules link from the table of contents at the top of the page.
Use the in-page search feature of your browser (in most Windows browsers you can access it using the CTRL + F keyboard shortcut).
Enter a search term to find the module you are looking for - e.g., Key Vault.
Move through the search results until you locate the desired module. If you are unable to find a published module, return to the table of contents and expand the All modules link to search both published and proposed modules - i.e., modules that are planned, likely in development but not published yet.
After finding the desired module, click on the module’s name. This link will lead you to the official HashiCorp Terraform Registry page for the module where you can find the module’s documentation and examples.

Module details and examples

Once you have identified the AVM module in the Terraform Registry you can find detailed information about the module’s functionality, components, input parameters, outputs and more. The documentation also provides comprehensive usage examples, covering various scenarios and configurations.

Explore the Key Vault module’s documentation and usage examples to understand its functionality, input variables, and outputs.

Note the Examples drop-down list and explore each example
Review the Readme tab to see module provider minimums, a list of resources and data sources used by the module, a nicely formatted version of the inputs and outputs, and a reference to any submodules that may be called.
Explore the Inputs tab and observe how each input has a detailed description and a type definition for you to use when adding input values to your module configuration.
Explore the Outputs tab and review each of the outputs that are exported by the AVM module for use by other modules in your deployment.
Finally, review the Resources tab to get a better understanding of the resources defined in the module.

In this example, your will to deploy a secret in a new Key Vault instance without needing to provide other parameters. The AVM Key Vault resource module provides these capabilities and does so with security and reliability being core principles. The default settings of the module also apply the recommendations of the Well Architected Framework where possible and appropriate.

Note how the create-key example seems to do what you need to achieve.

Create your new solution using AVM

Now that you have found the module details, you can use the content from the Terraform Registry to speed up your development in the following ways:

Option 1: Create a solution using AVM module examples: duplicate a module example and edit it for your needs. This is useful if you are starting without any existing infrastructure and need to create supporting resources like resource groups as part of your deployment.
Option 2: Create a solution by changing the AVM module input values: add the AVM module to an existing solution that already includes other resources. This method requires some knowledge of the resource(s) being deployed so that you can make choices about optional features configured in your solution’s version of the module.

Each deployment method includes a section below so that you can choose the method which best fits your needs.

Note

Option 1: Create a solution using AVM module examples

Leverage the following steps as a template for how to leverage examples for bootstrapping your new solution code. The Key Vault resource module is used here as an example, but in practice you may choose any module that applies to your scenario.

Locate and select the Examples drop down menu in the middle of the Key Vault module page.
From the drop-down list select an example whose name most closely aligns with your scenario - e.g., create-key.
When the example page loads, read the example description to determine if this is the desired example. If it is not, return to the module main page, and select a different example until you are satisfied that the example covers the scenario you are trying to deploy. If you are unable to find a suitable example, leverage the last two steps in the option 2 instructions to modify the inputs of the selected example to match your requirements.
Scroll to the code block for the example and select the Copy button on the top right of the block to copy the content to the clipboard.

➕ Click here to copy the sample code from the video.

provider "azurerm" {
  features {}
}

terraform {
  required_version = "~> 1.9"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.71"
    }
    http = {
      source  = "hashicorp/http"
      version = "~> 3.4"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.5"
    }
  }
}

module "regions" {
  source  = "Azure/avm-utl-regions/azurerm"
  version = "0.1.0"
}

# This allows us to randomize the region for the resource group.
resource "random_integer" "region_index" {
  max = length(module.regions.regions) - 1
  min = 0
}

# This ensures you have unique CAF compliant names for our resources.
module "naming" {
  source  = "Azure/naming/azurerm"
  version = "0.3.0"
}

resource "azurerm_resource_group" "this" {
  location = module.regions.regions[random_integer.region_index.result].name
  name     = module.naming.resource_group.name_unique
}

# Get current IP address for use in KV firewall rules
data "http" "ip" {
  url = "https://api.ipify.org/"
  retry {
    attempts     = 5
    max_delay_ms = 1000
    min_delay_ms = 500
  }
}

data "azurerm_client_config" "current" {}

module "key_vault" {
  source                        = "Azure/avm-res-keyvault-vault/azurerm"
  name                          = module.naming.key_vault.name_unique
  location                      = azurerm_resource_group.this.location
  enable_telemetry              = var.enable_telemetry
  resource_group_name           = azurerm_resource_group.this.name
  tenant_id                     = data.azurerm_client_config.current.tenant_id
  public_network_access_enabled = true
  keys = {
    cmk_for_storage_account = {
      key_opts = [
        "decrypt",
        "encrypt",
        "sign",
        "unwrapKey",
        "verify",
        "wrapKey"
      ]
      key_type: "RSA"
      name     = "cmk-for-storage-account"
      key_size = 2048
    }
  }
  role_assignments = {
    deployment_user_kv_admin = {
      role_definition_id_or_name = "Key Vault Administrator"
      principal_id               = data.azurerm_client_config.current.object_id
    }
  }
  wait_for_rbac_before_key_operations = {
    create = "60s"
  }
  network_acls = {
    bypass   = "AzureServices"
    ip_rules = ["${data.http.ip.response_body}/32"]
  }
}

In your IDE - Visual Studio Code in our example - create the main.tf file for your new solution.
Paste the content from the clipboard into main.tf.
AVM examples frequently use naming and/or region selection AVM utility modules to generate deployment region and/or naming values as well as any default values for required fields. If you want to use a specific region name or other custom resource values, remove the existing region and naming module calls and replace example input values with the new desired custom input values.
Once supporting resources such as resource groups have been modified, locate the module call for the AVM module - i.e., module "keyvault".
AVM module examples use dot notation for a relative reference that is useful during module testing. However, you will need to replace the relative reference with a source reference that points to the Terraform Registry source location. In most cases, this source reference has been left as a comment in the module example to simplify replacing the existing source dot reference. Perform the following two actions to update the source:
- Delete the existing source definition that uses a dot reference - i.e., source = "../../".
- Uncomment the Terraform Registry source reference by deleting the # sign at the start of the commented source line - i.e., source = "Azure/avm-res-keyvault-vault/azurerm".
Note
If the module example does not include a commented Terraform Registry source reference, you will need to copy it from the module’s main documentation page. Use the following steps to do so:
- Use the breadcrumbs to leave the example documentation and return to the module’s primary Terraform Registry documentation page.
- Locate the Provision Instructions box on the right side of the module’s Terraform Registry page in your web browser.
- Select the second line that starts with source = from the code block - e.g., source = "Azure/avm-res-keyvault-vault/azurerm". Copy it onto the clipboard.
- Return to your code solution and Paste the clipboard’s content where you previously deleted the source dot reference - e.g., source = "../../".
AVM module examples use a variable to enable or disable the telemetry collection. Update the enable_telemetry input value to true or false. - e.g. enable_telemetry = true
Save your main.tf file changes and then proceed to the guide section for running your solution code.

Option 2: Create a solution by changing the AVM module input values

Click here to copy the sample code from the video.

module "avm-res-keyvault-vault" {
  source                        = "Azure/avm-res-keyvault-vault/azurerm"
  version                       = "0.9.1"
  name                          = "<custom_name_here>"
  resource_group_name           = azurerm_resource_group.this.name
  location                      = azurerm_resource_group.this.location
  tenant_id                     = data.azurerm_client_config.this.tenant_id

  keys = {
    cmk_for_storage_account = {
      key_opts = [
        "decrypt",
        "encrypt",
        "sign",
        "unwrapKey",
        "verify",
        "wrapKey"
      ]
      key_type: "RSA"
      name     = "cmk-for-storage-account"
      key_size = 2048
    }
  }
  role_assignments = {
    deployment_user_kv_admin = {
      role_definition_id_or_name = "Key Vault Administrator"
      principal_id               = data.azurerm_client_config.current.object_id
    }
  }
  wait_for_rbac_before_key_operations = {
    create = "60s"
  }
}

Use the following steps as a guide for the custom implementation of an AVM Module in your solution code. This instruction path assumes that you have an existing Terraform file that you want to add the AVM module to.

Locate the Provision Instructions box on the right side of the module’s Terraform Registry page in your web browser.
Select the module template code from the code block and Copy it onto the clipboard.
Switch to your IDE and Paste the contents of the clipboard into your solution’s .tf Terraform file - main.tf in our example.
Return to the module’s Terraform Registry page in the browser and select the Inputs tab.
Review each input and add the inputs with the desired target value to the solution’s code - i.e., name = "custom_name".
Once you are satisfied that you have included all required inputs and any optional inputs, Save your file and continue to the next section.

Deploy your solution

After completing your solution development, you can move to the deployment stage. Follow these steps for a basic Terraform workflow:

Open the command line and login to Azure using the Azure cli
```
az login
```
If your account has access to multiple tenants, you may need to modify the command to az login --tenant <tenant id> where “<tenant id>” is the guid for the target tenant.
After logging in, select the target subscription from the list of subscriptions that you have access to.
Change the path to the directory where your completed terraform solution files reside.
Note
Many AVM modules depend on the AzureRM 4.0 Terraform provider which mandates that a subscription id is configured. If you receive an error indicating that subscription_id is a required provider property, you will need to set a subscription id value for the provider. For Unix based systems (Linux or MacOS) you can configure this by running export ARM_SUBSCRIPTION_ID=<your subscription guid> on the command line. On Microsoft Windows, you can perform the same operation by running set ARM_SUBSCRIPTION_ID="<your subscription guid>" from the Windows command prompt or by running $env:ARM_SUBSCRIPTION_ID="<your subscription guid>" from a powershell prompt. Replace the “<your subscription id>” notation in each command with your Azure subscription’s unique id value.
Initialize your Terraform project. This command downloads the necessary providers and modules to the working directory.
```
terraform init
```
Before applying the configuration, it is good practice to validate it to ensure there are no syntax errors.
```
terraform validate
```
Create a deployment plan. This step shows what actions Terraform will take to reach the desired state defined in your configuration.
```
terraform plan
```
Review the plan to ensure that only the desired actions are in the plan output.
Apply the configuration and create the resources defined in your configuration file. This command will prompt you to confirm the deployment prior to making changes. Type yes to create your solution’s infrastructure.
```
terraform apply
```
Info
If you are confident in your changes, you can add the -auto-approve switch to bypass manual approval: terraform apply -auto-approve
Once the deployment completes, validate that the infrastructure is configured as desired.
Info
A local terraform.tfstate file and a state backup file have been created during the deployment. The use of local state is acceptable for small temporary configurations, but production or long-lived installations should use a remote state configuration where possible. Configuring remote state is out of scope for this guide, but you can find details on using an Azure storage account for this purpose in the Microsoft Learn documentation.

Clean up your environment

When you are ready, you can remove the infrastructure deployed in this example. Use the following command to delete all resources created by your deployment:

terraform destroy

Note

Most Key Vault deployment examples activate soft-delete functionality as a default. The terraform destroy command will remove the Key Vault resource but does not purge a soft-deleted vault. You may encounter errors if you attempt to re-deploy a Key Vault with the same name during the soft-delete retention window. If you wish to purge the soft-delete for this example you can run az keyvault purge -n <keyVaultName> -l <regionName> using the Azure CLI, or Remove-AzKeyVault -VaultName "<keyVaultName>" -Location "<regionName>" -InRemovedState using Azure PowerShell.

Congratulations, you have successfully leveraged Terraform and AVM to deploy resources in Azure!

Tip

We welcome your contributions and feedback to help us improve the AVM modules and the overall experience for the community!

Next Steps

For developing a more advanced solution, please see the lab titled “Introduction to using Azure Verified Modules for Terraform”.

Terraform Prerequisites

You will need the following tools and components to complete this guide:

Visual Studio Code (VS Code) to develop your solution.
Terraform CLI to deploy your Terraform modules. Make sure you have a recent version installed.
Azure CLI to authenticate to Azure.
Azure Subscription to deploy your resources.

Specifications & Definitions

Summary

This section lists AVM’s Specifications & Definitions.

Module Specifications

This section documents all the specifications for Azure Verified Modules (AVM) and their respective IaC languages.

Specifications by IaC Language

Category	Bicep			Terraform
Category	Resource	Pattern	Utility	Resource	Pattern	Utility
Contribution/Support	9	8	0	9	8	0
Telemetry	4	3	0	2	2	0
Naming/Composition	22	16	1	17	12	1
CodeStyle	2	2	0	29	29	0
Inputs/Outputs	14	11	0	8	6	0
Testing	14	13	0	10	10	0
Documentation	5	5	0	4	4	0
Release/Publishing	5	5	2	4	4	1
Summary	75	63	3	83	75	2

What changed recently?

See what specifications changed in the last 30 days...

#	ID	Last Modified (UTC)	Git History	Last Commit
1	SNFR3	2025-06-27 14:49:42	All Commits	db02f74
2	BCPNFR22	2025-06-25 18:40:52	All Commits	9ff60a0
3	BCPNFR1	2025-06-20 07:10:54	All Commits	f79f207
4	SNFR26	2025-06-17 14:13:16	All Commits	f6e12b4
5	SFR3	2025-06-13 21:30:28	All Commits	7d51e6c

How to navigate the specifications?

The “Module Specifications” section uses tags to dynamically render content based on the selected attributes, such as the IaC language, module classification, category, severity and more. The tags are defined in header of each specification page.

To make it easier for module owners and contributors to navigate the documentation, the specifications are grouped to distinct pages by the IaC language (Bicep | Terraform) and module classification ( resource | pattern | utility). The specifications on each page are further ordered by the category (e.g., Composition, CodeStyle, Testing, etc.), severity of the requirements (MUST | SHOULD | MAY) and at what stage of the module’s lifecycle the specification is typically applicable (Initial | BAU | EOL).

To find what you need, simply decide which IaC language you’d like develop in and what classification your module falls under, then navigate to the respective page to find the specifications that are relevant to you.

Info

All specifications have a 4-9 character long unique ID - a combination of letters and numbers. These letters only carry legacy meaning only leveraged by the AVM core team and are no longer used to group the specifications in any visible way. The ID is used to reference the specification in the code, documentation, and discussions.

Specification Tags

The following tags are used to qualify the specifications:

Key	Allowed Values	Multiple/Single
Language	Bicep, Terraform	Multiple
Class	Resource, Pattern, Utility	Multiple
Type	Functional, NonFunctional	Single
Category	Testing, Telemetry, Contribution/Support, Documentation, CodeStyle, Naming/Composition, Inputs/Outputs, Release/Publishing	Single
Severity	MUST, SHOULD, MAY	Single
Persona	Owner, Contributor	Multiple
Lifecycle	Initial, BAU, EOL	Single
Validation	Bicep: BCP/Manual, BCP/CI/Informational, BCP/CI/Enforced Terraform: TF/Manual, TF/CI/Informational, TF/CI/Enforced	Single per language

Each tag is a concatenation of exactly one of the keys and one of the values, e.g., Language-Bicep, Class-Resource, Type-Functional, etc. When it’s marked as Multiple, it means that the tag can have multiple values, e.g., Language-Bicep, Language-Terraform, or Persona-Owner, Persona-Contributor, etc. When it’s marked as Single, it means that the tag can have only one value, e.g., Type-Functional, Lifecycle-Initial, etc.

➕ Click here to see the definition of the Severity, Persona, Lifecycle and Validation tags...

Severity

What’s the severity or importance of this specification? See “How to read the specifications?” section for more details.

Persona

Who is this specification for? The Owner is the module owner, while the Contributor is anyone who contributes to the module.

Lifecycle

When is this specification mostly relevant?

The Initial stage is when the module is being developed first - e.g., naming related specs are labeled with Lifecycle-Initial as the naming of the module only happens once: at the beginning of their life.
The BAU (business as usual) stage is at any time during the module’s typical lifecycle - e.g., specs that describe coding standards are relevant throughout the module’s life, for any time a new module version is released.
The EOL (end of life) stage is when the module is being decommissioned - e.g., specs describing how a module should be retired are labeled with Lifecycle-EOL.

Validation

How is this specification checked/validated/enforced?

Manual means that the specification is manually enforced at the time of the module review (at the time of the first or any subsequent module version release).
CI/Informational means that the module is checked against the specification by a CI pipeline, but the failure is only informational and doesn’t block the module release.
CI/Enforced means that the specification is automatically enforced by a CI pipeline, and the failure blocks the module release.

Note: the BCP/ or TF/ prefix is required as shared (language-agnostic) specifications may have different level of validation/enforcement per each language - e.g., it is possible that a specification is enforced by a CI pipeline for Bicep modules, while it is manually enforced for Terraform modules.

Why are there language specific specifications?

While every effort is being made to standardize requirements and implementation details across all languages (and most specifications in fact, are applicable to all), it is expected that some of the specifications will be different between their respective languages to ensure we follow the best practices and leverage features of each language.

How to read the specifications?

Important

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

As you’re developing/maintaining a module as a module owner or contributor, you need to ensure that your module adheres to the specifications outlined in this section. The specifications are designed to ensure that all AVM modules are consistent, secure, and compliant with best practices.

There are 3 levels of specifications:

MUST: These are mandatory requirements that MUST be followed.
SHOULD: These are recommended requirements that SHOULD be followed, unless there are good reasons for not to.
MAY: These are optional requirements that MAY be followed at the module owner’s/contributor’s discretion.

Bicep Specifications

Specifications by Category and Module Classification

Category	Resource	Pattern	Utility
Contribution/Support	9	8	0
Telemetry	4	3	0
Naming/Composition	22	16	1
CodeStyle	2	2	0
Inputs/Outputs	14	11	0
Testing	14	13	0
Documentation	5	5	0
Release/Publishing	5	5	2
Summary	75	63	3

How to propose changes to the specifications?

Important

Any updates to existing or new specifications for Bicep must be submitted as a draft for review by the AVM core team(@Azure/avm-core-team).

What changed recently?

See what specifications changed in the last 30 days...

#	ID	Last Modified (UTC)	Git History	Last Commit
1	SNFR3	2025-06-27 14:49:42	All Commits	db02f74
2	BCPNFR22	2025-06-25 18:40:52	All Commits	9ff60a0
3	BCPNFR1	2025-06-20 07:10:54	All Commits	f79f207
4	SNFR26	2025-06-17 14:13:16	All Commits	f6e12b4
5	SFR3	2025-06-13 21:30:28	All Commits	7d51e6c

Bicep Interfaces

This chapter details the interfaces/schemas for the AVM Resource Modules features/extension resources as referenced in RMFR4 and RMFR5.

Diagnostic Settings

Important

Allowed values for logs and metric categories or category groups MUST NOT be specified to keep the module implementation evergreen for any new categories or category groups added by RPs, without module owners having to update a list of allowed values and cut a new release of their module.

Diagnostic Settings

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { diagnosticSettingFullType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The diagnostic settings of the service.')
  param diagnosticSettings diagnosticSettingFullType[]?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType<_diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = [for (diagnosticSetting, index) in (diagnosticSettings ?? []): {
    name: diagnosticSetting.?name ?? '${name}-diagnosticSettings'
    properties: {
      storageAccountId: diagnosticSetting.?storageAccountResourceId
      workspaceId: diagnosticSetting.?workspaceResourceId
      eventHubAuthorizationRuleId: diagnosticSetting.?eventHubAuthorizationRuleResourceId
      eventHubName: diagnosticSetting.?eventHubName
      metrics: [for group in (diagnosticSetting.?metricCategories ?? [ { category: 'AllMetrics' } ]): {
        category: group.category
        enabled: group.?enabled ?? true
        timeGrain: null
      }]
      logs: [for group in (diagnosticSetting.?logCategoriesAndGroups ?? [ { categoryGroup: 'allLogs' } ]): {
        categoryGroup: group.?categoryGroup
        category: group.?category
        enabled: group.?enabled ?? true
      }]
      marketplacePartnerId: diagnosticSetting.?marketplacePartnerResourceId
      logAnalyticsDestinationType: diagnosticSetting.?logAnalyticsDestinationType
    }
    scope: >singularMainResourceType<
  }]

  diagnosticSettings: [
    {
      name: 'diagSetting1'
      logCategoriesAndGroups: [
        {
          category: 'AzurePolicyEvaluationDetails'
        }
        {
          category: 'AuditEvent'
        }
      ]
      metricCategories: [
        {
          category: 'AllMetrics'
        }
      ]
      logAnalyticsDestinationType: 'Dedicated'
      workspaceResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}'
      storageAccountResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}'
      eventHubAuthorizationRuleResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}/eventhubs/{eventHubName}/authorizationrules/{authorizationRuleName}'
      eventHubName: '{eventHubName}'
      marketplacePartnerResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{partnerResourceProvider}/{partnerResourceType}/{partnerResourceName}'
    }
  ]

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { diagnosticSettingMetricsOnlyType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The diagnostic settings of the service.')
  param diagnosticSettings diagnosticSettingMetricsOnlyType[]?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType<_diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = [for (diagnosticSetting, index) in (diagnosticSettings ?? []): {
    name: diagnosticSetting.?name ?? '${name}-diagnosticSettings'
    properties: {
      storageAccountId: diagnosticSetting.?storageAccountResourceId
      workspaceId: diagnosticSetting.?workspaceResourceId
      eventHubAuthorizationRuleId: diagnosticSetting.?eventHubAuthorizationRuleResourceId
      eventHubName: diagnosticSetting.?eventHubName
      metrics: [for group in (diagnosticSetting.?metricCategories ?? [ { category: 'AllMetrics' } ]): {
        category: group.category
        enabled: group.?enabled ?? true
        timeGrain: null
      }]
      marketplacePartnerId: diagnosticSetting.?marketplacePartnerResourceId
      logAnalyticsDestinationType: diagnosticSetting.?logAnalyticsDestinationType
    }
    scope: >singularMainResourceType<
  }]

  diagnosticSettings: [
    {
      name: 'diagSetting1'
      metricCategories: [
        {
          category: 'AllMetrics'
        }
      ]
      logAnalyticsDestinationType: 'Dedicated'
      workspaceResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}'
      storageAccountResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}'
      eventHubAuthorizationRuleResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}/eventhubs/{eventHubName}/authorizationrules/{authorizationRuleName}'
      eventHubName: '{eventHubName}'
      marketplacePartnerResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{partnerResourceProvider}/{partnerResourceType}/{partnerResourceName}'
    }
  ]

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { diagnosticSettingLogsOnlyType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The diagnostic settings of the service.')
  param diagnosticSettings diagnosticSettingLogsOnlyType[]?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType<_diagnosticSettings 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = [for (diagnosticSetting, index) in (diagnosticSettings ?? []): {
    name: diagnosticSetting.?name ?? '${name}-diagnosticSettings'
    properties: {
      storageAccountId: diagnosticSetting.?storageAccountResourceId
      workspaceId: diagnosticSetting.?workspaceResourceId
      eventHubAuthorizationRuleId: diagnosticSetting.?eventHubAuthorizationRuleResourceId
      eventHubName: diagnosticSetting.?eventHubName
      logs: [for group in (diagnosticSetting.?logCategoriesAndGroups ?? [ { categoryGroup: 'allLogs' } ]): {
        categoryGroup: group.?categoryGroup
        category: group.?category
        enabled: group.?enabled ?? true
      }]
      marketplacePartnerId: diagnosticSetting.?marketplacePartnerResourceId
      logAnalyticsDestinationType: diagnosticSetting.?logAnalyticsDestinationType
    }
    scope: >singularMainResourceType<
  }]

  diagnosticSettings: [
    {
      name: 'diagSetting1'
      logCategoriesAndGroups: [
        {
          category: 'AzurePolicyEvaluationDetails'
        }
        {
          category: 'AuditEvent'
        }
      ]
      logAnalyticsDestinationType: 'Dedicated'
      workspaceResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}'
      storageAccountResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}'
      eventHubAuthorizationRuleResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}/eventhubs/{eventHubName}/authorizationrules/{authorizationRuleName}'
      eventHubName: '{eventHubName}'
      marketplacePartnerResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{partnerResourceProvider}/{partnerResourceType}/{partnerResourceName}'
    }
  ]

Note

In the provided example for Diagnostic Settings, both logs and metrics are enabled for the associated resource. However, it is IMPORTANT to note that certain resources may not support both diagnostic setting types/categories. In such cases, the resource configuration MUST be modified accordingly to ensure proper functionality and compliance with system requirements.

Role Assignments

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { roleAssignmentType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. Array of role assignments to create.')
  param roleAssignments roleAssignmentType[]?
  
  // ============= //
  //   Variables   //
  // ============= //
  
  var builtInRoleNames = {
    // Add other relevant built-in roles here for your resource as per BCPNFR5
    Contributor: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
    Owner: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')
    Reader: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')
    'Role Based Access Control Administrator (Preview)': subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f58310d9-a9f6-439a-9e8d-f62e7b41a168')
    'User Access Administrator': subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '18d7d88d-d35e-4fb5-a5c3-7773c20a72d9')
  }
  
  var formattedRoleAssignments = [
    for (roleAssignment, index) in (roleAssignments ?? []): union(roleAssignment, {
      roleDefinitionId: builtInRoleNames[?roleAssignment.roleDefinitionIdOrName] ?? (contains(roleAssignment.roleDefinitionIdOrName, '/providers/Microsoft.Authorization/roleDefinitions/')
            ? roleAssignment.roleDefinitionIdOrName
            : subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleAssignment.roleDefinitionIdOrName))
    })
  ]
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType<_roleAssignments 'Microsoft.Authorization/roleAssignments@2022-04-01' = [
    for (roleAssignment, index) in (formattedRoleAssignments ?? []): {
      name: roleAssignment.?name ?? guid(>singularMainResourceType<.id, roleAssignment.principalId, roleAssignment.roleDefinitionId)
      properties: {
        roleDefinitionId: roleAssignment.roleDefinitionId
        principalId: roleAssignment.principalId
        description: roleAssignment.?description
        principalType: roleAssignment.?principalType
        condition: roleAssignment.?condition
        conditionVersion: !empty(roleAssignment.?condition) ? (roleAssignment.?conditionVersion ?? '2.0') : null // Must only be set if condtion is set
        delegatedManagedIdentityResourceId: roleAssignment.?delegatedManagedIdentityResourceId
      }
      scope: >singularMainResourceType<
    }
  ]

  roleAssignments: [
    {
      roleDefinitionIdOrName: 'Owner'
      principalId: nestedDependencies.outputs.managedIdentityPrincipalId
      principalType: 'ServicePrincipal'
    }
    {
      roleDefinitionIdOrName: 'b24988ac-6180-42a0-ab88-20f7382dd24c'
      principalId: nestedDependencies.outputs.managedIdentityPrincipalId
      principalType: 'ServicePrincipal'
    }
    {
      roleDefinitionIdOrName: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')
      principalId: nestedDependencies.outputs.managedIdentityPrincipalId
      principalType: 'ServicePrincipal'
    }
    {
      name: guid('Custom role assignment name seed')
      roleDefinitionIdOrName: 'Storage Blob Data Reader'
      principalId: '00000000-0000-0000-0000-000000000000'
      principalType: 'Group'
      description: 'Group with read-only access'
      condition: '@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:ContainerName] StringEqualsIgnoreCase 'foo_storage_container''
      conditionVersion: '2.0'
    }
  ]

Details on child, extension and cross-referenced resources:

Modules MUST support Role Assignments on child, extension and cross-referenced resources as well as the primary resource via parameters/variables

Resource Locks

  // ============== //
  //   Parameters   //
  // ============== //
  
  import { lockType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The lock settings of the service.')
  param lock lockType?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType<_lock 'Microsoft.Authorization/locks@2020-05-01' = if (!empty(lock ?? {}) && lock.?kind != 'None') {
    name: lock.?name ?? 'lock-${name}'
    properties: {
      level: lock.?kind ?? ''
      notes: lock.?notes ?? (lock.?kind == 'CanNotDelete'
        ? 'Cannot delete resource or child resources.'
        : 'Cannot delete or modify the resource or child resources.')
    }
    scope: >singularMainResourceType<
  }

  lock: {
    kind: 'CanNotDelete'
    name: 'myCustomLockName'
    notes: 'This is a custom lock note.'
  }

Details on child and extension resources:

Locks SHOULD be able to be set for child resources of the primary resource in resource modules

Details on cross-referenced resources:

Locks MUST be automatically applied to cross-referenced resources if the primary resource has a lock applied.
- This MUST also be able to be turned off for each of the cross-referenced resources by the module consumer via a parameter/variable if they desire

An example of this is a Key Vault module that has a Private Endpoints enabled. If a lock is applied to the Key Vault via the lock parameter/variable then the lock should also be applied to the Private Endpoint automatically, unless the privateEndpointLock/private_endpoint_lock (example name) parameter/variable is set to None

Managed Identities

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { managedIdentityAllType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The managed identity definition for this resource.')
  param managedIdentities managedIdentityAllType?
  
  // ============= //
  //   Variables   //
  // ============= //
  
  var formattedUserAssignedIdentities = reduce(map((managedIdentities.?userAssignedResourceIds ?? []), (id) => { '${id}': {} }), {}, (cur, next) => union(cur, next)) // Converts the flat array to an object like { '${id1}': {}, '${id2}': {} }
  var identity = !empty(managedIdentities) ? {
    type: (managedIdentities.?systemAssigned ?? false) ? (!empty(managedIdentities.?userAssignedResourceIds ?? {}) ? 'SystemAssigned,UserAssigned' : 'SystemAssigned') : (!empty(managedIdentities.?userAssignedResourceIds ?? {}) ? 'UserAssigned' : null)
    userAssignedIdentities: !empty(formattedUserAssignedIdentities) ? formattedUserAssignedIdentities : null
  } : null
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType< '>providerNamespace</>resourceType<@>apiVersion<' = {
    name: name
    identity: identity
    properties: {
      ... // other properties
    }
  }
  
  // =========== //
  //   Outputs   //
  // =========== //
  
  @description('The principal ID of the system assigned identity.')
  output systemAssignedMIPrincipalId string? = >singularMainResourceType<.?identity.?principalId

  managedIdentities: {
    systemAssigned: true
    userAssignedResourceIds: [
      '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'
      '/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroupName2}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName2}'
    ]
  }

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { managedIdentityOnlySysAssignedType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The managed identity definition for this resource.')
  param managedIdentities managedIdentityOnlySysAssignedType?
  
  // ============= //
  //   Variables   //
  // ============= //
  
  var identity = !empty(managedIdentities)
    ? {
        type: (managedIdentities.?systemAssigned ?? false) ? 'SystemAssigned' : null
      }
    : null
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType< '>providerNamespace</>resourceType<@>apiVersion<' = {
    name: name
    identity: identity
    properties: {
      ... // other properties
    }
  }
  
  // =========== //
  //   Outputs   //
  // =========== //
  
  @description('The principal ID of the system assigned identity.')
  output systemAssignedMIPrincipalId string? = >singularMainResourceType<.?identity.?principalId

  managedIdentities: {
    systemAssigned: true
  }

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { managedIdentityOnlyUserAssignedType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The managed identity definition for this resource.')
  param managedIdentities managedIdentityOnlyUserAssignedType?
  
  // ============= //
  //   Variables   //
  // ============= //
  
  var formattedUserAssignedIdentities = reduce(map((managedIdentities.?userAssignedResourceIds ?? []), (id) => { '${id}': {} }), {}, (cur, next) => union(cur, next)) // Converts the flat array to an object like { '${id1}': {}, '${id2}': {} }
  var identity = !empty(managedIdentities)
    ? {
        type: !empty(managedIdentities.?userAssignedResourceIds ?? {}) ? 'UserAssigned' : 'None'
        userAssignedIdentities: !empty(formattedUserAssignedIdentities) ? formattedUserAssignedIdentities : null
      }
    : null
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType< '>providerNamespace</>resourceType<@>apiVersion<' = {
    name: name
    identity: identity
    properties: {
      ... // other properties
    }
  }

  managedIdentities: {
    userAssignedResourceIds: [
      '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'
      '/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroupName2}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName2}'
    ]
  }

Reason for differences in User Assigned data type in languages:

We do not foresee the Managed Identity Resource Provider team to ever add additional properties within the empty object ({}) value required on the input of a User Assigned Managed Identity.
In Bicep we therefore have removed the need for this to be declared and just converted it to a simple array of Resource IDs

Private Endpoints

E.g., for services that only have one private endpoint type.

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { privateEndpointSingleServiceType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. Configuration details for private endpoints. For security reasons, it is recommended to use private endpoints whenever possible.')
  param privateEndpoints privateEndpointSingleServiceType[]?
  
  var enableReferencedModulesTelemetry = false // resource module
  
  // ============= //
  //   Resources   //
  // ============= //
  
  module >singularMainResourceType<_privateEndpoints 'br/public:avm/res/network/private-endpoint:>version<' = [for (privateEndpoint, index) in (privateEndpoints ?? []): {
    name: '${uniqueString(deployment().name, location)}->singularMainResourceType<-PrivateEndpoint-${index}'
    scope: resourceGroup(
      split(privateEndpoint.?resourceGroupResourceId ?? resourceGroup().id, '/')[2],
      split(privateEndpoint.?resourceGroupResourceId ?? resourceGroup().id, '/')[4]
    )
    params: {
      // Variant 1: A default service can be assumed (i.e., for services that only have one private endpoint type)
      name: privateEndpoint.?name ?? 'pep-${last(split(>singularMainResourceType<.id, '/'))}-${privateEndpoint.?service ?? '>defaultServiceName<'}-${index}'
      privateLinkServiceConnections: privateEndpoint.?isManualConnection != true ? [
        {
          name: privateEndpoint.?privateLinkServiceConnectionName ?? '${last(split(>singularMainResourceType<.id, '/'))}-${privateEndpoint.?service ?? '>defaultServiceName<'}-${index}'
          properties: {
            privateLinkServiceId: >singularMainResourceType<.id
            groupIds: [
              privateEndpoint.?service ?? '>defaultServiceName<'
            ]
          }
        }
      ] : null
      manualPrivateLinkServiceConnections: privateEndpoint.?isManualConnection == true ? [
        {
          name: privateEndpoint.?privateLinkServiceConnectionName ?? '${last(split(>singularMainResourceType<.id, '/'))}-${privateEndpoint.?service ?? '>defaultServiceName<'}-${index}'
          properties: {
            privateLinkServiceId: >singularMainResourceType<.id
            groupIds: [
              privateEndpoint.?service ?? '>defaultServiceName<'
            ]
            requestMessage: privateEndpoint.?manualConnectionRequestMessage ?? 'Manual approval required.'
          }
        }
      ] : null
      subnetResourceId: privateEndpoint.subnetResourceId
      enableTelemetry: enableReferencedModulesTelemetry // resource module
      enableTelemetry: privateEndpoint.?enableTelemetry ?? enableTelemetry // pattern / utility module
      location: privateEndpoint.?location ?? reference(split(privateEndpoint.subnetResourceId, '/subnets/')[0], '2020-06-01', 'Full').location
      lock: privateEndpoint.?lock ?? lock
      privateDnsZoneGroup: privateEndpoint.?privateDnsZoneGroup
      roleAssignments: privateEndpoint.?roleAssignments
      tags: privateEndpoint.?tags ?? tags
      customDnsConfigs: privateEndpoint.?customDnsConfigs
      ipConfigurations: privateEndpoint.?ipConfigurations
      applicationSecurityGroupResourceIds: privateEndpoint.?applicationSecurityGroupResourceIds
      customNetworkInterfaceName: privateEndpoint.?customNetworkInterfaceName
    }
  }]
  
  @description('The private endpoints of the resource.')
  output privateEndpoints privateEndpointOutputType[] = [
    for (pe, index) in (privateEndpoints ?? []): {
      name: >singularMainResourceType<_privateEndpoints[index].outputs.name
      resourceId: >singularMainResourceType<_privateEndpoints[index].outputs.resourceId
      groupId: >singularMainResourceType<_privateEndpoints[index].outputs.?groupId!
      customDnsConfigs: >singularMainResourceType<_privateEndpoints[index].outputs.customDnsConfigs
      networkInterfaceResourceIds: >singularMainResourceType<_privateEndpoints[index].outputs.networkInterfaceResourceIds
    }
  ]
  
  // =============== //
  //   Definitions   //
  // =============== //
  
  @export()
  type privateEndpointOutputType = {
    @description('The name of the private endpoint.')
    name: string
  
    @description('The resource ID of the private endpoint.')
    resourceId: string
  
    @description('The group Id for the private endpoint Group.')
    groupId: string?
  
    @description('The custom DNS configurations of the private endpoint.')
    customDnsConfigs: {
      @description('FQDN that resolves to private endpoint IP address.')
      fqdn: string?
  
      @description('A list of private IP addresses of the private endpoint.')
      ipAddresses: string[]
    }[]
  
    @description('The IDs of the network interfaces associated with the private endpoint.')
    networkInterfaceResourceIds: string[]
  }

  privateEndpoints: {
    {
      name: 'myPeName'
      privateLinkServiceConnectionName: 'myPrivateLinkConnectionName'
      lock: 'CanNotDelete'
      tags: {
        'hidden-title': 'This is visible in the resource name'
      }
      subnetResourceId: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRg/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mysubnet'
      resourceGroupResourceId: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRg'
      applicationSecurityGroupResourceIds: [
        '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRg/providers/Microsoft.Network/applicationSecurityGroups/myAsg'
      ]
      privateDnsZoneGroup: {
        privateDnsZoneGroupConfigs: [
          {
            name: 'config'
            privateDnsZoneResourceId: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRg/providers/Microsoft.Network/privateDnsZones/myZone'
          }
        ]
      }
      customDnsConfigs: [
        {
          fqdn: 'fqdn1.example.com'
          ipAddresses: [
            '10.0.0.1',
            '10.0.0.2'
          ]
        }
      ]
      networkInterfaceName: 'nic1'
      ipConfigurations: [
        {
          name: 'ipconfig1'
          groupId: 'vault'
          memberName: 'default'
          privateIpAddress: '10.0.0.7'
        }
      ]
      roleAssignments: [
        {
          roleDefinitionIdOrName: 'Owner'
          principalId: '11111111-1111-1111-1111-111111111111'
          principalType: 'ServicePrincipal'
        }
        {
          roleDefinitionIdOrName: subscriptionResourceId('Microsoft.Authorization/roleDefinitions','acdd72a7-3385-48ef-bd42-f606fba81ae7')
          principalId: '11111111-1111-1111-1111-111111111111'
          principalType: 'ServicePrincipal'
        }
      ]
    }
  }

E.g., for services that have more than one private endpoint type, like a Storage Account (blob, file, etc.)

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  import { privateEndpointMultiServiceType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. Configuration details for private endpoints. For security reasons, it is recommended to use private endpoints whenever possible.')
  param privateEndpoints privateEndpointMultiServiceType[]?
  
  var enableReferencedModulesTelemetry = false // resource module
  
  // ============= //
  //   Resources   //
  // ============= //
  
  module >singularMainResourceType<_privateEndpoints 'br/public:avm/res/network/private-endpoint:>version<' = [for (privateEndpoint, index) in (privateEndpoints ?? []): {
    name: '${uniqueString(deployment().name, location)}->singularMainResourceType<-PrivateEndpoint-${index}'
    scope: resourceGroup(
      split(privateEndpoint.?resourceGroupResourceId ?? resourceGroup().id, '/')[2],
      split(privateEndpoint.?resourceGroupResourceId ?? resourceGroup().id, '/')[4]
    )
    params: {
      // Variant 2: A default service cannot be assumed (i.e., for services that have more than one private endpoint type, like Storage Account)
      name: privateEndpoint.?name ?? 'pep-${last(split(>singularMainResourceType<.id, '/'))}-${privateEndpoint.service}-${index}'
      privateLinkServiceConnections: privateEndpoint.?isManualConnection != true ? [
        {
          name: privateEndpoint.?privateLinkServiceConnectionName ?? '${last(split(>singularMainResourceType<.id, '/'))}-${privateEndpoint.service}-${index}'
          properties: {
            privateLinkServiceId: >singularMainResourceType<.id
            groupIds: [
              privateEndpoint.service
            ]
          }
        }
      ] : null
      manualPrivateLinkServiceConnections: privateEndpoint.?isManualConnection == true ? [
        {
          name: privateEndpoint.?privateLinkServiceConnectionName ?? '${last(split(>singularMainResourceType<.id, '/'))}-${privateEndpoint.service}-${index}'
          properties: {
            privateLinkServiceId: >singularMainResourceType<.id
            groupIds: [
              privateEndpoint.service
            ]
            requestMessage: privateEndpoint.?manualConnectionRequestMessage ?? 'Manual approval required.'
          }
        }
      ] : null
      subnetResourceId: privateEndpoint.subnetResourceId
      enableTelemetry: enableReferencedModulesTelemetry // resource module
      enableTelemetry: privateEndpoint.?enableTelemetry ?? enableTelemetry // pattern / utility module
      location: privateEndpoint.?location ?? reference(split(privateEndpoint.subnetResourceId, '/subnets/')[0], '2020-06-01', 'Full').location
      lock: privateEndpoint.?lock ?? lock
      privateDnsZoneGroup: privateEndpoint.?privateDnsZoneGroup
      roleAssignments: privateEndpoint.?roleAssignments
      tags: privateEndpoint.?tags ?? tags
      customDnsConfigs: privateEndpoint.?customDnsConfigs
      ipConfigurations: privateEndpoint.?ipConfigurations
      applicationSecurityGroupResourceIds: privateEndpoint.?applicationSecurityGroupResourceIds
      customNetworkInterfaceName: privateEndpoint.?customNetworkInterfaceName
    }
  }]
  
  @description('The private endpoints of the resource.')
  output privateEndpoints privateEndpointOutputType[] = [
    for (pe, index) in (privateEndpoints ?? []): {
      name: >singularMainResourceType<_privateEndpoints[index].outputs.name
      resourceId: >singularMainResourceType<_privateEndpoints[index].outputs.resourceId
      groupId: >singularMainResourceType<_privateEndpoints[index].outputs.?groupId!
      customDnsConfigs: >singularMainResourceType<_privateEndpoints[index].outputs.customDnsConfigs
      networkInterfaceResourceIds: >singularMainResourceType<_privateEndpoints[index].outputs.networkInterfaceResourceIds
    }
  ]
  
  // =============== //
  //   Definitions   //
  // =============== //
  
  @export()
  type privateEndpointOutputType = {
    @description('The name of the private endpoint.')
    name: string
  
    @description('The resource ID of the private endpoint.')
    resourceId: string
  
    @description('The group Id for the private endpoint Group.')
    groupId: string?
  
    @description('The custom DNS configurations of the private endpoint.')
    customDnsConfigs: {
      @description('FQDN that resolves to private endpoint IP address.')
      fqdn: string?
  
      @description('A list of private IP addresses of the private endpoint.')
      ipAddresses: string[]
    }[]
  
    @description('The IDs of the network interfaces associated with the private endpoint.')
    networkInterfaceResourceIds: string[]
  }

  privateEndpoints: {
    {
      name: 'myPeName'
      privateLinkServiceConnectionName: 'myPrivateLinkConnectionName'
      lock: 'CanNotDelete'
      tags: {
        'hidden-title': 'This is visible in the resource name'
      }
      service: 'blob'
      subnetResourceId: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRg/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mysubnet'
      resourceGroupResourceId: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRg'
      applicationSecurityGroupResourceIds: [
        '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRg/providers/Microsoft.Network/applicationSecurityGroups/myAsg'
      ]
      privateDnsZoneGroup: {
        privateDnsZoneGroupConfigs: [
          {
            name: 'config'
            privateDnsZoneResourceId: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRg/providers/Microsoft.Network/privateDnsZones/myZone'
          }
        ]
      }
      customDnsConfigs: [
        {
          fqdn: 'fqdn1.example.com'
          ipAddresses: [
            '10.0.0.1',
            '10.0.0.2'
          ]
        }
      ]
      networkInterfaceName: 'nic1'
      ipConfigurations: [
        {
          name: 'ipconfig1'
          groupId: 'blob'
          memberName: 'default'
          privateIpAddress: '10.0.0.7'
        }
      ]
      roleAssignments: [
        {
          roleDefinitionIdOrName: 'Owner'
          principalId: '11111111-1111-1111-1111-111111111111'
          principalType: 'ServicePrincipal'
        }
        {
          roleDefinitionIdOrName: subscriptionResourceId('Microsoft.Authorization/roleDefinitions','acdd72a7-3385-48ef-bd42-f606fba81ae7')
          principalId: '11111111-1111-1111-1111-111111111111'
          principalType: 'ServicePrincipal'
        }
      ]
    }
  }

Notes:

The properties defined in the schema above are the minimum amount of properties expected to be exposed for Private Endpoints in AVM Resource Modules.
- A module owner MAY chose to expose additional properties of the Private Endpoint resource
  - However, module owners considering this SHOULD contact the AVM core team first to consult on how the property should be exposed to avoid future breaking changes to the schema that may be enforced upon them
Module owners MAY chose to define a list of allowed value for the ‘service’ (a.k.a. groupIds) property
- However, they should do so with caution as should a new service appear for their resource module, a new release will need to be cut to add this new service to the allowed values
  - Whereas not specifying allowed values will allow flexibility from day 0 without the need for any changes and releases to be made

Customer Managed Keys

  // ============== //
  //   Parameters   //
  // ============== //
  
  import { customerManagedKeyType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The customer managed key definition.')
  param customerManagedKey customerManagedKeyType?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource cMKKeyVault 'Microsoft.KeyVault/vaults@2023-02-01' existing = if (!empty(customerManagedKey.?keyVaultResourceId)) {
    name: last(split((customerManagedKey.?keyVaultResourceId!), '/'))
    scope: resourceGroup(
      split(customerManagedKey.?keyVaultResourceId!, '/')[2],
      split(customerManagedKey.?keyVaultResourceId!, '/')[4]
    )
  
    resource cMKKey 'keys@2023-02-01' existing = if (!empty(customerManagedKey.?keyVaultResourceId) && !empty(customerManagedKey.?keyName)) {
      name: customerManagedKey.?keyName!
    }
  }
  
  resource cMKUserAssignedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' existing = if (!empty(customerManagedKey.?userAssignedIdentityResourceId)) {
    name: last(split(customerManagedKey.?userAssignedIdentityResourceId!, '/'))
    scope: resourceGroup(
      split(customerManagedKey.?userAssignedIdentityResourceId!, '/')[2],
      split(customerManagedKey.?userAssignedIdentityResourceId!, '/')[4]
    )
  }
  
  resource >singularMainResourceType< '>providerNamespace</>resourceType<@>apiVersion<' = {
    name: '>exampleResource<'
    properties: {
      ... // other properties
      encryption: !empty(customerManagedKey)
        ? {
            keySource: 'Microsoft.KeyVault'
            keyVaultProperties: {
              keyVaultUri: cMKKeyVault.properties.vaultUri
              keyName: customerManagedKey!.keyName
              keyVersion: !empty(customerManagedKey.?keyVersion)
                ? customerManagedKey!.keyVersion
                : last(split(cMKKeyVault::cMKKey.properties.keyUriWithVersion, '/'))
              keyIdentifier: !empty(customerManagedKey.?keyVersion)
                ? '${cMKKeyVault::cMKKey.properties.keyUri}/${customerManagedKey!.keyVersion}'
                : cMKKeyVault::cMKKey.properties.keyUriWithVersion
              identityClientId: !empty(customerManagedKey.?userAssignedIdentityResourceId)
                ? cMKUserAssignedIdentity.properties.clientId
                : null
              identity: !empty(customerManagedKey.?userAssignedIdentityResourceId)
                ? {
                    userAssignedIdentity: cMKUserAssignedIdentity.id
                  }
                : null
            }
          }
        : null
    }
  }

  customerManagedKey: {
    keyVaultResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/vaults/{keyVaultName}'
    keyName: '{keyName}'
    keyVersion: '{keyVersion}'
    userAssignedIdentityResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{uamiName}'
  }

  // ============== //
  //   Parameters   //
  // ============== //
  import { customerManagedKeyWithAutoRotateType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Optional. The customer managed key definition.')
  param customerManagedKey customerManagedKeyWithAutoRotateType?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource cMKKeyVault 'Microsoft.KeyVault/vaults@2023-02-01' existing = if (!empty(customerManagedKey.?keyVaultResourceId)) {
    name: last(split((customerManagedKey.?keyVaultResourceId!), '/'))
    scope: resourceGroup(
      split(customerManagedKey.?keyVaultResourceId!, '/')[2],
      split(customerManagedKey.?keyVaultResourceId!, '/')[4]
    )
  
    resource cMKKey 'keys@2023-02-01' existing = if (!empty(customerManagedKey.?keyVaultResourceId) && !empty(customerManagedKey.?keyName)) {
      name: customerManagedKey.?keyName!
    }
  }
  
  resource cMKUserAssignedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' existing = if (!empty(customerManagedKey.?userAssignedIdentityResourceId)) {
    name: last(split(customerManagedKey.?userAssignedIdentityResourceId!, '/'))
    scope: resourceGroup(
      split(customerManagedKey.?userAssignedIdentityResourceId!, '/')[2],
      split(customerManagedKey.?userAssignedIdentityResourceId!, '/')[4]
    )
  }
  
  resource >singularMainResourceType< '>providerNamespace</>resourceType<@>apiVersion<' = {
    name: '>exampleResource<'
    properties: {
      ... // other properties
      encryption: !empty(customerManagedKey)
        ? {
            keySource: 'Microsoft.KeyVault'
            keyVaultProperties: {
              keyVaultUri: cMKKeyVault.properties.vaultUri
              keyName: customerManagedKey!.keyName
              keyVersion: !empty(customerManagedKey.?keyVersion)
                ? customerManagedKey!.keyVersion
                : (customerManagedKey.?autoRotationEnabled ?? true)
                  ? null
                  : last(split(cMKKeyVault::cMKKey.properties.keyUriWithVersion, '/'))
              keyIdentifier: !empty(customerManagedKey.?keyVersion)
                ? '${cMKKeyVault::cMKKey.properties.keyUri}/${customerManagedKey!.keyVersion}'
                : (customerManagedKey.?autoRotationEnabled ?? true)
                  ? cMKKeyVault::cMKKey.properties.keyUri
                  : cMKKeyVault::cMKKey.properties.keyUriWithVersion
              identityClientId: !empty(customerManagedKey.?userAssignedIdentityResourceId)
                ? cMKUserAssignedIdentity.properties.clientId
                : null
              identity: !empty(customerManagedKey.?userAssignedIdentityResourceId)
                ? {
                    userAssignedIdentity: cMKUserAssignedIdentity.id
                  }
                : null
            }
          }
        : null
    }
  }

  customerManagedKey: {
    keyVaultResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/vaults/{keyVaultName}'
    keyName: '{keyName}'
    autoRotationEnabled: {autoRotationEnabled}
    userAssignedIdentityResourceId: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{uamiName}'
  }

Secrets export (DEPRECATED)

Important

Since version Bicep 0.35.1, it is possible to export secrets securely using the secure() annotation.

As this approach is fairly simple compared with the below workaround it is highly recommended to use it instead.

Example

@secure()
@description('The primary connection string of the service bus namespace.')
output primaryConnectionString string = listkeys(
  '${serviceBusNamespace.id}/AuthorizationRules/RootManageSharedAccessKey',
  '2024-01-01'
).primaryConnectionString

@secure()
@description('The primary key of the service bus namespace.')
output primaryKey string = listkeys(
  '${serviceBusNamespace.id}/AuthorizationRules/RootManageSharedAccessKey',
  '2024-01-01'
).primaryKey

Secrets used inside a module can be exported to a Key Vault reference provided as per the below schema.
This implementation provides a secure way around the current limitation of Bicep on providing a secure template output (that can be used for secrets).

The user MUST

provide the resource Id to a Key Vault. The principal used for the deployment MUST be allowed to set secrets in this Key Vault.
provide a name for each secret they want to store (opt-in). The module will suggest which secrets are available via the implemented user-defined type.

The module returns an output table where the key is the name of the secret the user provided, and the value contains both the secret’s resource Id and URI.

Important

The feature MUST be implemented as per the below schema. Diversions are only allowed in places marked as >text< to ensure a consistent user experience across modules.

User Defined Type, Parameter & Resource Example

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  @description('Optional. Key vault reference and secret settings for the module\'s secrets export.')
  param secretsExportConfiguration secretsExportConfigurationType?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  module secretsExport 'modules/keyVaultExport.bicep' = if (secretsExportConfiguration != null) {
    name: '${uniqueString(deployment().name, location)}-secrets-kv'
    scope: resourceGroup(
      split(secretsExportConfiguration.?keyVaultResourceId, '/')[2],
      split(secretsExportConfiguration.?keyVaultResourceId, '/')[4]
    )
    params: {
      keyVaultName: last(split(secretsExportConfiguration.?keyVaultResourceId, '/'))
      secretsToSet: union(
        [],
        contains(secretsExportConfiguration!, '>secretToExport1<Name')
          ? [
              {
                name: secretsExportConfiguration!.?>secretToExport1<Name
                value: >secretReference1< // e.g., >singularMainResourceType<.listKeys().primaryMasterKey
              }
            ]
          : [],
        contains(secretsExportConfiguration!, '>secretToExport2<Name')
          ? [
              {
                name: secretsExportConfiguration!.?>secretToExport2<Name
                value:>secretReference2<  // e.g., >singularMainResourceType<.listKeys().secondaryMasterKey
              }
            ]
          : []
          // (...)
      )
    }
  }
  
  // =========== //
  //   Outputs   //
  // =========== //
  
  import { secretsOutputType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('A hashtable of references to the secrets exported to the provided Key Vault. The key of each reference is each secret\'s name.')
  output exportedSecrets secretsOutputType = (secretsExportConfiguration != null)
    ? toObject(secretsExport.outputs.secretsSet, secret => last(split(secret.secretResourceId, '/')), secret => secret)
    : {}
  
  // =============== //
  //   Definitions   //
  // =============== //
  
  @export()
  type secretsExportConfigurationType = {
    @description('Required. The resource ID of the key vault where to store the secrets of this module.')
    keyVaultResourceId: string
  
    @description('Optional. The >secretToExport1< secret name to create.')
    >secretToExport1<Name: string?
  
    @description('Optional. The >secretToExport2< secret name to create.')
    >secretToExport2<Name: string?
  
    // (...)
  }

Input Example with Values

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  @description('Optional. Key vault reference and secret settings for the module\'s secrets export.')
  param secretsExportConfiguration secretsExportConfigurationType?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  module secretsExport 'modules/keyVaultExport.bicep' = if (secretsExportConfiguration != null) {
    name: '${uniqueString(deployment().name, location)}-secrets-kv'
    scope: resourceGroup(
      split(secretsExportConfiguration.?keyVaultResourceId, '/')[2],
      split(secretsExportConfiguration.?keyVaultResourceId, '/')[4]
    )
    params: {
      keyVaultName: last(split(secretsExportConfiguration.?keyVaultResourceId, '/'))
      secretsToSet: union(
        [],
        contains(secretsExportConfiguration!, '>secretToExport1<Name')
          ? [
              {
                name: secretsExportConfiguration!.?>secretToExport1<Name
                value: >secretReference1< // e.g., >singularMainResourceType<.listKeys().primaryMasterKey
              }
            ]
          : [],
        contains(secretsExportConfiguration!, '>secretToExport2<Name')
          ? [
              {
                name: secretsExportConfiguration!.?>secretToExport2<Name
                value:>secretReference2<  // e.g., >singularMainResourceType<.listKeys().secondaryMasterKey
              }
            ]
          : []
          // (...)
      )
    }
  }
  
  // =========== //
  //   Outputs   //
  // =========== //
  
  import { secretsOutputType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('A hashtable of references to the secrets exported to the provided Key Vault. The key of each reference is each secret\'s name.')
  output exportedSecrets secretsOutputType = (secretsExportConfiguration != null)
    ? toObject(secretsExport.outputs.secretsSet, secret => last(split(secret.secretResourceId, '/')), secret => secret)
    : {}
  
  // =============== //
  //   Definitions   //
  // =============== //
  
  @export()
  type secretsExportConfigurationType = {
    @description('Required. The resource ID of the key vault where to store the secrets of this module.')
    keyVaultResourceId: string
  
    @description('Optional. The >secretToExport1< secret name to create.')
    >secretToExport1<Name: string?
  
    @description('Optional. The >secretToExport2< secret name to create.')
    >secretToExport2<Name: string?
  
    // (...)
  }

[modules/keyVaultExport.bicep] file

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  @description('Required. The name of the Key Vault to set the secrets in.')
  param keyVaultName string
  
  import { secretToSetType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('Required. The secrets to set in the Key Vault.')
  param secretsToSet secretToSetType[]
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource keyVault 'Microsoft.KeyVault/vaults@2022-07-01' existing = {
    name: keyVaultName
  }
  
  resource secrets 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = [
    for secret in secretsToSet: {
      name: secret.name
      parent: keyVault
      properties: {
        value: secret.value
      }
    }
  ]
  
  // =========== //
  //   Outputs   //
  // =========== //
  
  import { secretSetOutputType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('The references to the secrets exported to the provided Key Vault.')
  output secretsSet secretSetOutputType[] = [
    #disable-next-line outputs-should-not-contain-secrets // Only returning the references, not a secret value
    for index in range(0, length(secretsToSet ?? [])): {
      secretResourceId: secrets[index].id
      secretUri: secrets[index].properties.secretUri
      secretUriWithVersion: secrets[index].properties.secretUriWithVersion
    }
  ]

Output Usage Example

When using a module that implements the above interface, you can access its outputs for example in the following ways:

  
  // ============== //
  //   Parameters   //
  // ============== //
  
  @description('Optional. Key vault reference and secret settings for the module\'s secrets export.')
  param secretsExportConfiguration secretsExportConfigurationType?
  
  // ============= //
  //   Resources   //
  // ============= //
  
  module secretsExport 'modules/keyVaultExport.bicep' = if (secretsExportConfiguration != null) {
    name: '${uniqueString(deployment().name, location)}-secrets-kv'
    scope: resourceGroup(
      split(secretsExportConfiguration.?keyVaultResourceId, '/')[2],
      split(secretsExportConfiguration.?keyVaultResourceId, '/')[4]
    )
    params: {
      keyVaultName: last(split(secretsExportConfiguration.?keyVaultResourceId, '/'))
      secretsToSet: union(
        [],
        contains(secretsExportConfiguration!, '>secretToExport1<Name')
          ? [
              {
                name: secretsExportConfiguration!.?>secretToExport1<Name
                value: >secretReference1< // e.g., >singularMainResourceType<.listKeys().primaryMasterKey
              }
            ]
          : [],
        contains(secretsExportConfiguration!, '>secretToExport2<Name')
          ? [
              {
                name: secretsExportConfiguration!.?>secretToExport2<Name
                value:>secretReference2<  // e.g., >singularMainResourceType<.listKeys().secondaryMasterKey
              }
            ]
          : []
          // (...)
      )
    }
  }
  
  // =========== //
  //   Outputs   //
  // =========== //
  
  import { secretsOutputType } from 'br/public:avm/utl/types/avm-common-types:>version<'
  @description('A hashtable of references to the secrets exported to the provided Key Vault. The key of each reference is each secret\'s name.')
  output exportedSecrets secretsOutputType = (secretsExportConfiguration != null)
    ? toObject(secretsExport.outputs.secretsSet, secret => last(split(secret.secretResourceId, '/')), secret => secret)
    : {}
  
  // =============== //
  //   Definitions   //
  // =============== //
  
  @export()
  type secretsExportConfigurationType = {
    @description('Required. The resource ID of the key vault where to store the secrets of this module.')
    keyVaultResourceId: string
  
    @description('Optional. The >secretToExport1< secret name to create.')
    >secretToExport1<Name: string?
  
    @description('Optional. The >secretToExport2< secret name to create.')
    >secretToExport2<Name: string?
  
    // (...)
  }

Which returns a JSON-formatted output like:

  {
    "exportedSecrets": {
      "Type": "Object",
      "Value": {
        ">secretToExportName1<": {
          "secretResourceId": "/subscriptions/<subId>/resourceGroups/<rgName>providers/Microsoft.KeyVault/vaults/<vaultName>/secrets/>secretToExportName1<",
          "secretUri": "https://<vaultName>.vault.azure.net/secrets/>secretToExportName1<"
        },
        ">secretToExportName2<": {
          "secretResourceId": "/subscriptions/<subId>/resourceGroups/<rgName>providers/Microsoft.KeyVault/vaults/<vaultName>/secrets/>secretToExportName2<",
          "secretUri": "https://<vaultName>.vault.azure.net/secrets/>secretToExportName2<"
        }
      }
    },
    "specificSecret": {
      "Type": "String",
      "Value": "/subscriptions/<subId>/resourceGroups/<rgName>providers/Microsoft.KeyVault/vaults/<vaultName>/secrets/>secretToExportName1<"
    },
    "exportedSecretResourceIds": {
      "Type": "Array",
      "Value": [
        "/subscriptions/<subId>/resourceGroups/<rgName>providers/Microsoft.KeyVault/vaults/<vaultName>/secrets/>secretToExportName1<",
        "/subscriptions/<subId>/resourceGroups/<rgName>providers/Microsoft.KeyVault/vaults/<vaultName>/secrets/>secretToExportName2<"
      ]
    }
  }

Azure Monitor Alerts

Note

This interface is a SHOULD instead of a MUST and therefore the AVM core team have not mandated a interface schema to use.

Zonal & zone-redundant resources

Many Azure resources can be deployed into specific availability zones. Depending on whether a resource is ‘zonal’ (i.e., deploys a single instance into a single zone) or ‘zone-redundant’ (i.e., spreads multiple of its instances across the configured zones), implementing a different interface is required. Simply put, the zone of a zonal resource must be a required parameter (but give the user the option to ‘opt-out’), while zone-redundant resources must span all available zones by default, but still give the user the option to ‘opt-out’. Please note that the support for Availability Zones may differ from region to region.

  // ============== //
  //   Parameters   //
  // ============== //
  
  @description('Required. If set to 1, 2 or 3, the availability zone is hardcoded to that value. If set to -1, no zone is defined. Note that the availability zone numbers here are the logical availability zone in your Azure subscription. Different subscriptions might have a different mapping of the physical zone and logical zone. To understand more, please refer to [Physical and logical availability zones](https://learn.microsoft.com/en-us/azure/reliability/availability-zones-overview?tabs=azure-cli#physical-and-logical-availability-zones).')
  @allowed([
    -1
    1
    2
    3
  ])
  param availabilityZone int
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType< '>providerNamespace</>resourceType<@>apiVersion<' = {
    name: '>exampleResource<'
    properties: {
      ... // other properties
      zones: availabilityZone != -1 ? array(string(availabilityZone)) : null // If expecting an array
      // Or
      availabilityZone: availabilityZone != -1 ? string(availabilityZone) : null // If expecting a single value
    }
  }

  availabilityZone: -1 // Deploy into no zone
  availabilityZone: 1 // Deploy into zone 1

  // ============== //
  //   Parameters   //
  // ============== //
  
  @description('Optional. The list of Availability zones to use for the zone-redundant resources.')
  @allowed([
    1
    2
    3
  ])
  param availabilityZones int[] = [1, 2, 3]
  
  // ============= //
  //   Resources   //
  // ============= //
  
  resource >singularMainResourceType< '>providerNamespace</>resourceType<@>apiVersion<' = {
    name: '>exampleResource<'
    properties: {
      ... // other properties
      zones: map(availabilityZones, zone => '${zone}')
    }
  }

  availabilityZones: [] // Deploy into no zone
  availabilityZones: [1, 2] // Deploy into zone 1 & 2

Bicep Pattern Module Specifications

Contribution / Support

The content below is listed based on the following tags

Category-Contribution/SupportClass-PatternLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR8	Module Owner(s) GitHub	MUST	Owner	Initial
2	SNFR20	GitHub Teams Only	MUST	Owner	Initial
3	SNFR9	AVM & PG Teams GitHub Repo Permissions	MUST	Owner	Initial
4	SNFR10	MIT Licensing	MUST	Owner	Initial
5	SNFR11	Issues Response Times	MUST	OwnerContributor	BAU
6	SNFR12	Versions Supported	MUST	Owner	BAU
7	SNFR23	GitHub Repo Labels	MUST	Owner	BAU
8	BCPNFR15	AVM Module Issue template file	MUST	Owner	BAU

➕ See Specifications for this category

See origin...

ID: SNFR8 - Category: Contribution/Support - Module Owner(s) GitHub

A module MUST have an owner that is defined and managed by a GitHub Team in the Azure GitHub organization.

Today this is only Microsoft FTEs, but everyone is welcome to contribute. The module just MUST be owned by a Microsoft FTE (today) so we can enforce and provide the long-term support required by this initiative.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

See origin...

ID: SNFR20 - Category: Contribution/Support - GitHub Teams Only

All GitHub repositories that AVM module are published from and hosted within MUST only assign GitHub repository permissions to GitHub teams only.

Each module MUST have separate GitHub teams assigned for module owners AND module contributors respectively. These GitHub teams MUST be created in the Azure organization in GitHub.

There MUST NOT be any GitHub repository permissions assigned to individual users.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

The @Azure prefix in the last column of the tables linked above represents the “Azure” GitHub organization all AVM-related repositories exist in. DO NOT include this segment in the team’s name!

Important

Non-FTE / external contributors (subject matter experts that aren’t Microsoft employees) can’t be members of the teams described in this chapter, hence, they won’t gain any extra permissions on AVM repositories, therefore, they need to work in forks.

Naming Convention

The naming convention for the GitHub teams MUST follow the below pattern:

<hyphenated module name>-module-owners-<bicep/tf> - to be assigned as the GitHub repository’s Module Owners team
<hyphenated module name>-module-contributors-<bicep/tf> - to be assigned as the GitHub repository’s Module Contributors team

Note

The naming convention for Bicep modules is slightly different than the naming convention for their respective GitHub teams.

Segments:

<hyphenated module name> == the AVM Module’s name, with each segment separated by dashes, i.e., avm-res-<resource provider>-<ARM resource type>
- See RMNFR1 for AVM Resource Module Naming
- See PMNFR1 for AVM Pattern Module Naming
module-owners or module-contributors == the role the GitHub Team is assigned to
<bicep/tf> == the language the module is written in

Examples:

avm-res-compute-virtualmachine-module-owners-bicep
avm-res-compute-virtualmachine-module-contributors-tf

Add Team Members

All officially documented module owner(s) MUST be added to the -module-owners- team. The -module-owners- team MUST NOT have any other members.

Any additional module contributors whom the module owner(s) agreed to work with MUST be added to the -module-contributors- team.

Unless explicitly requested and agreed, members of the AVM core team or any PG teams MUST NOT be added to the -module-owners- or -module-contributors- teams as permissions for them are granted through the teams described in SNFR9.

Grant Permissions - Bicep

Team memberships

Note

In case of Bicep modules, permissions to the BRM repository (the repo of the Bicep Registry) are granted via assigning the -module-owners- and -module-contributors- teams to parent teams that already have the required level access configured. While it is the module owner’s responsibility to initiate the addition of their teams to the respective parents, only the AVM core team can approve this parent-child relationship.

Module owners MUST create their -module-owners- and -module-contributors- teams and as part of the provisioning process, they MUST request the addition of these teams to their respective parent teams (see the table below for details).

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<hyphenated module name>-module-owners-bicep`	AVM Bicep Module Owners - <module name>	Write	Assignment to the `avm-technical-reviewers-bicep` parent team.	Need to work in a fork.
`<hyphenated module name>-module-contributors-bicep`	AVM Bicep Module Contributors - <module name>	Triage	`avm-module-contributors-bicep` parent team.	Need to work in a fork.

Examples - GitHub teams required for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

avm-res-network-virtualnetwork-module-owners-bicep –> assign to the avm-technical-reviewers-bicep parent team.
avm-res-network-virtualnetwork-module-contributors-bicep –> assign to the avm-module-contributors-bicep parent team.

Tip

Direct link to create a new GitHub team and assign it to its parent: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Follow the guidance above (see the Permissions granted through column in the table above).
Team visibility: Visible
Team notifications: Enabled

CODEOWNERS file

As part of the “initial Pull Request” (that publishes the first version of the module), module owners MUST add an entry to the CODEOWNERS file in the BRM repository (here).

Note

Through this approach, the AVM core team will grant review permission to module owners as part of the standard PR review process.

Every CODEOWNERS entry (line) MUST include the following segments separated by a single whitespace character:

Path of the module, relative to the repo’s root, e.g.: /avm/res/network/virtual-network/
The -module-owners-team, with the @Azure/ prefix, e.g., @Azure/avm-res-network-virtualnetwork-module-owners-bicep
The GitHub team of the AVM Bicep reviewers, with the @Azure/ prefix, i.e., @Azure/avm-module-reviewers-bicep

Example - CODEOWNERS entry for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

/avm/res/network/virtual-network/ @Azure/avm-res-network-virtualnetwork-module-owners-bicep @Azure/avm-module-reviewers-bicep

Grant Permissions - Terraform

Module owners MUST assign the -module-owners-and -module-contributors- teams the necessary permissions on their Terraform module repository per the guidance below.

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<module name>-module-owners-tf`	AVM Terraform Module Owners - <module name>	Admin	Direct assignment to repo	Module owner can decide whether they want to work in a branch local to the repo or in a fork.
`<module name>-module-contributors-tf`	AVM Terraform Module Contributors - <module name>	Write	Direct assignment to repo	Need to work in a fork.

Tip

Direct link to create a new GitHub team: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Do not assign the team to any parent team.
Team visibility: Visible
Team notifications: Enabled

See origin...

ID: SNFR9 - Category: Contribution/Support - AVM & PG Teams GitHub Repo Permissions

A module owner MUST make the following GitHub teams in the Azure GitHub organization admins on the GitHub repo of the module in question:

Bicep

@Azure/avm-core-team-technical-bicep = AVM Core Team
@Azure/bicep-admins = Bicep PG team

Note

These required GitHub teams are already associated to the BRM repository and have the required permissions.

Terraform

@Azure/avm-core-team-technical-terraform = AVM Core Team
@Azure/terraform-avm = Terraform PG

Important

Module owners MUST assign these GitHub teams as admins on the GitHub repo of the module in question.

For detailed steps, please follow this guidance.

See origin...

ID: SNFR10 - Category: Contribution/Support - MIT Licensing

A module MUST be published with the MIT License in the Azure GitHub organization.

See origin...

ID: SNFR11 - Category: Contribution/Support - Issues Response Times

A module owner MUST respond to logged issues as defined in the support statement. See Module Support for more information.

See origin...

ID: SNFR12 - Category: Contribution/Support - Versions Supported

Only the latest released version of a module MUST be supported.

For example, if an AVM Resource Module is used in an AVM Pattern Module that was working but now is not. The first step by the AVM Pattern Module owner should be to upgrade to the latest version of the AVM Resource Module test and then if not fixed, troubleshoot and fix forward from the that latest version of the AVM Resource Module onwards.

This avoids AVM Module owners from having to maintain multiple major release versions.

See origin...

ID: SNFR23 - Category: Contribution/Support - GitHub Repo Labels

GitHub repositories where modules are held MUST use the below labels and SHOULD not use any additional labels:

➕ AVM Standard GitHub Labels

These labels are available in a CSV file from here

Name	Description	HEX
AZD 🧑‍💻	These modules are requested/used by the AZD team.	`E0BFFA`
Needs: Attention 👋	Reply has been added to issue, maintainer to review	`E99695`
Needs: Immediate Attention ‼️	Immediate attention of module owner / AVM team is needed	`FF0000`
Needs: Author Feedback 👂	Awaiting feedback from the issue/PR author	`F18A07`
Needs: External Changes ⚒️	When an issue/PR requires changes that are outside of the control of the module. e.g. to an RP.	`DE389D`
Needs: More Evidence ⚖	We are looking for more evidence to make a decision on this	`F64872`
Needs: Triage 🔍	Maintainers need to triage still	`FBCA04`
Needs: Module Owner 📣	In the AVM repository: this module needs an owner to develop or maintain it. In the BRM repository: the module owner needs to review a PR.	`FF0019`
Needs: Module Contributor 📣	This module needs secondary owner(s) or contributor(s) to develop or maintain it	`C95474`
Needs: Core Team 🧞‍♂️	This item needs the AVM Core Team to review it	`DB4503`
Status: Awaiting Release To Be Cut ✂️	This is fixed in the main branch but not in the latest release, will be fixed with next release cut	`800080`
Status: Do Not Merge ⛔	Do not merge PRs with this label attached as they are not ready or aligned to future direction etc.	`8B4513`
Status: External Contribution 🌍	This is being worked on by someone outside of the AVM module owners/contributors or AVM core team	`D8FA2C`
Status: Fixed ✅	Auto label applied when issue fixed by merged PR	`90EE90`
Status: Help Wanted 🆘	Extra attention is needed	`FF4500`
Status: In Triage 🔍	Picked up for triaging by an AVM core team member	`D4AF37`
Status: In PR 👉	This is when an issue is due to be fixed in an open PR	`EDEDED`
Status: Invalid ❌	This doesn't seem right	`E4E669`
Status: Long Term ⏳	We will do it, but will take a longer amount of time due to complexity/priorities	`B60205`
Status: No Recent Activity 💤	When an issue/PR has not been modified for X amount of days	`808080`
Status: Won't Fix 💔	This will not be worked on	`FFFFFF`
Status: Owners Identified 🤘	This module has its owners identified	`FBEF2A`
Status: Module Available 🟢	The module is published	`C8E6C9`
Status: Module Deprecated 🔴	This is a request to deprecate a module	`000000`
Status: Module Orphaned 🟡	The module has no owner and is therefore orphaned at this time	`F4A460`
Status: Ready For Repository Creation 📝	This module is approved and the owner is ready for the repository to be created (Terraform)	`136A41`
Status: Repository Created 📄	This module has had it's repository created and configured ready for owner contribution (Terraform)	`27AB03`
Status: Response Overdue 🚩	When an issue/PR has not been responded to for X amount of days	`850000`
Status: Looking For Assistance 🦆	This item is looking for anyone to help develop the code and submit a PR for resolution	`03FCC2`
Type: Bug 🐛	Something isn't working	`D73A4A`
Type: CI 🚀	This issue is related to the AVM CI	`74CFB0`
Type: Documentation 📄	Improvements or additions to documentation	`0075CA`
Type: Duplicate 🤲	This issue or pull request already exists	`CFD3D7`
Type: Feature Request ➕	New feature or request	`A2EEEF`
Type: Hygiene 🧹	things related to testing, issue triage etc.	`17016A`
Type: New Module Proposal 💡	A new module for AVM is being proposed	`ADD8E6`
Type: Question/Feedback 🙋‍♀️	Further information is requested or just some feedback	`CB6BA2`
Type: Security Bug 🔒	This is a security bug	`FFFF00`
Type: AVM 🅰️ ✌️ ⓜ️	This is an AVM related issue	`F0FFFF`
Language: Terraform 🌐	This is related to the Terraform IaC language	`7740B6`
Language: Bicep 💪	This is related to the Bicep IaC language	`1D73B3`
Class: Resource Module 📦	This is a resource module	`D3D3D3`
Class: Pattern Module 📦	This is a pattern module	`A9A9A9`
Class: Utility Module 📦	This is a utility module	`CAD1DE`
Class: Child Module 📦	This is a child module	`5E5186`

To help apply these to a module GitHub repository you can use the below PowerShell script:

➕ Set-AvmGitHubLabels.ps1

For most scenario this is the command you’ll need to call the below PowerShell script with, replacing the value for RepositoryName:

  Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -CreateCsvLabelExports $false -NoUserPrompts $true

```shell
# Linux / MacOs
# For Windows replace $PWD with your the local path or your repository
#
docker run -it -v $PWD:/repo -w /repo mcr.microsoft.com/powershell pwsh -Command '
    #Invoke-WebRequest -Uri "https://azure.github.io/Azure-Verified-Modules/scripts/Set-AvmGitHubLabels.ps1" -OutFile "Set-AvmGitHubLabels.ps1"
    $gh_version = "2.44.1"
    Invoke-WebRequest -Uri "https://github.com/cli/cli/releases/download/v2.44.1/gh_2.44.1_linux_amd64.tar.gz" -OutFile "gh_$($gh_version)_linux_amd64.tar.gz"
    apt-get update && apt-get install -y git
    tar -xzf "gh_$($gh_version)_linux_amd64.tar.gz"
    ls -lsa
    mv "gh_$($gh_version)_linux_amd64/bin/gh" /usr/local/bin/
    rm "gh_$($gh_version)_linux_amd64.tar.gz" && rm -rf "gh_$($gh_version)_linux_amd64"
    gh --version
    ls -lsa
    gh auth login
    $OrgProject = "Azure/terraform-azurerm-avm-res-kusto-cluster"
    gh auth status
    ./Set-AvmGitHubLabels.ps1 -RepositoryName $OrgProject -CreateCsvLabelExports $false -NoUserPrompts $true

  '
```

By default this script will only update and append labels on the repository specified. However, this can be changed by setting the parameter -UpdateAndAddLabelsOnly to $false, which will remove all the labels from the repository first and then apply the AVM labels from the CSV only.

Make sure you elevate your privilege to admin level or the labels will not be applied to your repository. Go to repos.opensource.microsoft.com/orgs/Azure/repos/ to request admin access before running the script.

Full Script:

These Set-AvmGitHubLabels.ps1 can be downloaded from here.

  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "", Justification = "Coloured output required in this script")]
  
  <#
  .SYNOPSIS
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
  .DESCRIPTION
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
    By default, the script will remove all pre-existing labels and apply the AVM labels. However, this can be changed by using the -RemoveExistingLabels parameter and setting it to $false. The tool will also output the labels that exist in the repository before and after the script has run to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter.
  
    The AVM labels to be created are documented here: TBC
  
  .NOTES
    Please ensure you have specified the GitHub repositry correctly. The script will prompt you to confirm the repository name before proceeding.
  
  .COMPONENT
    You must have the GitHub CLI installed and be authenticated to a GitHub account with access to the repository you are applying the labels to before running this script.
  
  .LINK
    TBC
  
  .Parameter RepositoryName
    The name of the GitHub repository to apply the labels to.
  
  .Parameter RemoveExistingLabels
    If set to $true, the default value, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will not remove any pre-existing labels.
  
  .Parameter UpdateAndAddLabelsOnly
    If set to $true, the default value, the script will only update and add labels to the repository specified in -RepositoryName. If set to $false, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
  .Parameter OutputDirectory
    The directory to output the pre-existing and post-existing labels to in a CSV file. The default value is the current directory.
  
  .Parameter CreateCsvLabelExports
    If set to $true, the default value, the script will output the pre-existing and post-existing labels to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter. If set to $false, the script will not output the pre-existing and post-existing labels to a CSV file.
  
  .Parameter GitHubCliLimit
    The maximum number of labels to return from the GitHub CLI. The default value is 999.
  
  .Parameter LabelsToApplyCsvUri
    The URI to the CSV file containing the labels to apply to the GitHub repository. The default value is https://raw.githubusercontent.com/jtracey93/label-source/main/avm-github-labels.csv.
  
  .Parameter NoUserPrompts
    If set to $true, the default value, the script will not prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
    This is useful for running the script in automation workflows
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and remove all pre-existing labels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false -CreateCsvLabelExports $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name. Finally, use a custom CSV file hosted on the internet to create the labels from.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false -CreateCsvLabelExports $false -LabelsToApplyCsvUri "https://example.com/csv/avm-github-labels.csv"
  
  #>
  
  #Requires -PSEdition Core
  
  [CmdletBinding()]
  param (
    [Parameter(Mandatory = $true)]
    [string]$RepositoryName,
  
    [Parameter(Mandatory = $false)]
    [bool]$RemoveExistingLabels = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$UpdateAndAddLabelsOnly = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$CreateCsvLabelExports = $true,
  
    [Parameter(Mandatory = $false)]
    [string]$OutputDirectory = (Get-Location),
  
    [Parameter(Mandatory = $false)]
    [int]$GitHubCliLimit = 999,
  
    [Parameter(Mandatory = $false)]
    [string]$LabelsToApplyCsvUri = "https://azure.github.io/Azure-Verified-Modules/governance/avm-standard-github-labels.csv",
  
    [Parameter(Mandatory = $false)]
    [bool]$NoUserPrompts = $false
  )
  
  # Check if the GitHub CLI is installed
  $GitHubCliInstalled = Get-Command gh -ErrorAction SilentlyContinue
  if ($null -eq $GitHubCliInstalled) {
    throw "The GitHub CLI is not installed. Please install the GitHub CLI and try again."
  }
  Write-Host "The GitHub CLI is installed..." -ForegroundColor Green
  
  # Check if GitHub CLI is authenticated
  $GitHubCliAuthenticated = gh auth status
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubCliAuthenticated -ForegroundColor Red
    throw "Not authenticated to GitHub. Please authenticate to GitHub using the GitHub CLI, `gh auth login`, and try again."
  }
  Write-Host "Authenticated to GitHub..." -ForegroundColor Green
  
  # Check if GitHub repository name is valid
  $GitHubRepositoryNameValid = $RepositoryName -match "^[a-zA-Z0-9-]+/[a-zA-Z0-9-]+$"
  if ($false -eq $GitHubRepositoryNameValid) {
    throw "The GitHub repository name $RepositoryName is not valid. Please check the repository name and try again. The format must be <OrgName>/<RepoName>"
  }
  
  # List GitHub repository provided and check it exists
  $GitHubRepository = gh repo view $RepositoryName
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubRepository -ForegroundColor Red
    throw "The GitHub repository $RepositoryName does not exist. Please check the repository name and try again."
  }
  Write-Host "The GitHub repository $RepositoryName exists..." -ForegroundColor Green
  
  # PRE - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($RemoveExistingLabels -or $UpdateAndAddLabelsOnly) {
    Write-Host "Getting the current GitHub repository (pre) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels -and $CreateCsvLabelExports -eq $true) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Pre-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (pre) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # Remove all pre-existing labels if -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels
  if ($null -ne $GitHubRepositoryLabels) {
    $GitHubRepositoryLabelsJson = $GitHubRepositoryLabels | ConvertFrom-Json
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $false -and $UpdateAndAddLabelsOnly -eq $false) {
      $RemoveExistingLabelsConfirmation = Read-Host "Are you sure you want to remove all $($GitHubRepositoryLabelsJson.Count) pre-existing labels from $($RepositoryName)? (Y/N)"
      if ($RemoveExistingLabelsConfirmation -eq "Y") {
        Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
        $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
          Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
          gh label delete -R $RepositoryName $_.name --yes
        }
      }
    }
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $true -and $UpdateAndAddLabelsOnly -eq $false) {
      Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
        Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
        gh label delete -R $RepositoryName $_.name --yes
      }
    }
  }
  if ($null -eq $GitHubRepositoryLabels) {
    Write-Host "No pre-existing labels to remove or not selected to be removed from $RepositoryName..." -ForegroundColor Magenta
  }
  
  # Check LabelsToApplyCsvUri is valid and contains a CSV content
  Write-Host "Checking $LabelsToApplyCsvUri is valid..." -ForegroundColor Yellow
  $LabelsToApplyCsvUriValid = $LabelsToApplyCsvUri -match "^https?://"
  if ($false -eq $LabelsToApplyCsvUriValid) {
    throw "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is not valid. Please check the URI and try again. The format must be a valid URI."
  }
  Write-Host "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is valid..." -ForegroundColor Green
  
  # Create AVM lables from the AVM labels CSV file stored on the web using the convertfrom-csv cmdlet
  $avmLabelsCsv = Invoke-WebRequest -Uri $LabelsToApplyCsvUri | ConvertFrom-Csv
  
  # Check if the AVM labels CSV file contains the following columns: Name, Description, HEX
  $avmLabelsCsvColumns = $avmLabelsCsv | Get-Member -MemberType NoteProperty | Select-Object -ExpandProperty Name
  $avmLabelsCsvColumnsValid = $avmLabelsCsvColumns -contains "Name" -and $avmLabelsCsvColumns -contains "Description" -and $avmLabelsCsvColumns -contains "HEX"
  if ($false -eq $avmLabelsCsvColumnsValid) {
    throw "The labels CSV file does not contain the required columns: Name, Description, HEX. Please check the CSV file and try again. It contains the following columns: $avmLabelsCsvColumns"
  }
  Write-Host "The labels CSV file contains the required columns: Name, Description, HEX" -ForegroundColor Green
  
  # Create the AVM labels in the GitHub repository
  Write-Host "Creating/Updating the $($avmLabelsCsv.Count) AVM labels in $RepositoryName..." -ForegroundColor Yellow
  $avmLabelsCsv | ForEach-Object {
    if ($GitHubRepositoryLabelsJson.name -contains $_.name) {
      Write-Host "The label $($_.name) already exists in $RepositoryName. Updating the label to ensure description and color are consitent..." -ForegroundColor Magenta
      gh label create -R $RepositoryName "$($_.name)" -c $_.HEX -d $($_.Description) --force
    }
    else {
      Write-Host "The label $($_.name) does not exist in $RepositoryName. Creating label $($_.name) in $RepositoryName..." -ForegroundColor Cyan
      gh label create -R $RepositoryName "$($_.Name)" -c $_.HEX -d $($_.Description) --force
    }
  }
  
  # POST - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($CreateCsvLabelExports -eq $true) {
    Write-Host "Getting the current GitHub repository (post) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Post-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (post) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # If -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels check that only the avm labels exist in the repository
  if ($RemoveExistingLabels -eq $true -and ($RemoveExistingLabelsConfirmation -eq "Y" -or $NoUserPrompts -eq $true) -and $UpdateAndAddLabelsOnly -eq $false) {
    Write-Host "Checking that only the AVM labels exist in $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
    $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
      if ($avmLabelsCsv.Name -notcontains $_.name) {
        throw "The label $($_.name) exists in $RepositoryName but is not in the CSV file."
      }
    }
    Write-Host "Only the CSV labels exist in $RepositoryName..." -ForegroundColor Green
  }
  
  Write-Host "The CSV labels have been created/updated in $RepositoryName..." -ForegroundColor Green

See origin...

ID: BCPNFR15 - Category: Contribution/Support - AVM Module Issue template file

Module owners MUST add an entry to the AVM Module Issue template file in the BRM repository (here). When the module is deprecated, this entry MUST be removed from the file.

Note

Through this approach, the AVM core team will allow raising a bug or feature request for a module, only after the module gets merged to the BRM repository.

The module name entry MUST be added to the dropdown list with id module-name-dropdown as an option, in alphabetical order.

Important

Module owners MUST ensure that the module name is added in alphabetical order, to simplify selecting the right module name when raising an AVM module issue.

Example - AVM Module Issue template module name entry for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

- type: dropdown
  id: module-name-dropdown
  attributes:
    label: Module Name
    description: Which existing AVM module is this issue related to?
    options:
      ...
      - "avm/res/network/virtual-network"
      ...

Telemetry

The content below is listed based on the following tags

Category-TelemetryClass-PatternLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SFR3	Deployment/Usage Telemetry	MUST	Owner	Initial
2	SFR4	Telemetry Enablement Flexibility	MUST	Owner	Initial
3	BCPFR4	Telemetry Enablement	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SFR3 - Category: Telemetry - Deployment/Usage Telemetry

Important

We will maintain a set of CSV files in the AVM Central Repo (Azure/Azure-Verified-Modules) with the required TelemetryId prefixes to enable checks to utilize this list to ensure the correct IDs are used. To see the formatted content of these CSV files with additional information, please visit the AVM Module Indexes page.

These will also be provided as a comment on the module proposal, once accepted, from the AVM core team.

Modules MUST provide the capability to collect deployment/usage telemetry as detailed in Telemetry further.

To highlight that AVM modules use telemetry, an information notice MUST be included in the footer of each module’s README.md file with the below content. (See more details on this requirement, here.)

Telemetry Information Notice

Note

The following information notice is automatically added at the bottom of the README.md file of the module when

Bicep: Using the utilities/tools/Set-AVMModule.ps1 utility
Terraform: Executing the make docs command with the note and header ## Data Collection being placed in the module’s _footer.md beforehand

### Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the [repository](https://aka.ms/avm/telemetry). There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at <https://go.microsoft.com/fwlink/?LinkID=824704>. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Bicep

Important

The value you need to use for your module is defined in the related module index. You can look it up on the index pages for Resource Modules, Pattern Modules and Utility Modules.

The ARM deployment name used for the telemetry MUST follow the pattern and MUST be no longer than 64 characters in length: 46d3xbcp.<res/ptn>.<(short) module name>.<version>.<uniqueness>

<res/ptn> == AVM Resource or Pattern Module
<(short) module name> == The AVM Module’s, possibly shortened, name including the resource provider and the resource type, without;
- The prefixes: avm-res-
- The prefixes: avm-ptn-
<version> == The AVM Module’s MAJOR.MINOR version (only) with . (periods) replaced with - (hyphens), to allow simpler splitting of the ARM deployment name
<uniqueness> == This section of the ARM deployment name is to be used to ensure uniqueness of the deployment name.
- This is to cater for the following scenarios:
  - The module is deployed multiple times to the same:
    - Location/Region
    - Scope (Tenant, Management Group,Subscription, Resource Group)

Note

Due to the 64-character length limit of Azure deployment names, the <(short) module name> segment has a length limit of 36 characters, so if the module name is longer than that, it MUST be truncated to 36 characters. If any of the semantic version’s segments are longer than 1 character, it further restricts the number of characters that can be used for naming the module.

An example deployment name for the AVM Virtual Machine Resource Module would be: 46d3xbcp.res.compute-virtualmachine.1-2-3.eum3

An example deployment name for a shortened module name would be: 46d3xbcp.res.desktopvirtualization-appgroup.1-2-3.eum3

Tip

Terraform: Terraform uses a telemetry provider, the configuration of which is the same for every module and is included in the template repo.

General: See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

Terraform

To enable telemetry data collection for Terraform modules, the modtm telemetry provider MUST be used. This lightweight telemetry provider sends telemetry data to Azure Application Insights via a HTTP POST front end service.

The modtm telemetry provider is included in all Terraform modules and is enabled by default through the main.telemetry.tf file being automatically distributed from the template repo.

The modtm provider MUST be listed under the required_providers section in the module’s terraform.tf file using the following entry. This is also validated by the linter.

terraform {
  required_providers {
    # .. other required providers as needed
    modtm = {
      source = "Azure/modtm"
      version = "~> 0.3"
    }
  }
}

See origin...

ID: SFR4 - Category: Telemetry - Telemetry Enablement Flexibility

The telemetry enablement MUST be on/enabled by default, however this MUST be able to be disabled by a module consumer by setting the below parameter/variable value to false:

Bicep: enableTelemetry
Terraform: enable_telemetry

Note

Whenever a module references AVM modules that implement the telemetry parameter (e.g., a pattern module that uses AVM resource modules), the telemetry parameter value MUST be passed through to these modules. This is necessary to ensure a consumer can reliably enable & disable the telemetry feature for all used modules.

This general specification can be modified for some use-cases, that are language specific:

Bicep

For cross-references in resource modules, the spec BCPFR7 also applies.

Terraform

Currently, no further requirements apply.

See origin...

ID: BCPFR4 - Category: Composition - Telemetry Enablement

To comply with specifications outlined in SFR3 & SFR4 you MUST incorporate the following code snippet into your modules. Place this code sample in the “top level” main.bicep file; it is not necessary to include it in any nested Bicep files (child modules).

  @description('Optional. Location for all resources.')
  param location string = resourceGroup().location
  
  @description('Optional. Enable/Disable usage telemetry for module.')
  param enableTelemetry bool = true
  
  #disable-next-line no-deployments-resources
  resource avmTelemetry 'Microsoft.Resources/deployments@2024-03-01' = if (enableTelemetry) {
    name: take('46d3xbcp.res.compute-virtualmachine.${replace('-..--..-', '.', '-')}.${substring(uniqueString(deployment().name, location), 0, 4)}', 64)
    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'
          }
        }
      }
    }
  }

Naming / Composition

The content below is listed based on the following tags

Category-Naming/CompositionClass-PatternLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SFR1	Preview Services	MUST	Owner	BAU
2	SFR2	WAF Aligned	SHOULD	Owner	BAU
3	SFR5	Availability Zones	MUST	Owner	Initial
4	SFR6	Data Redundancy	MUST	Owner	Initial
5	SNFR25	Resource Naming	MUST	Owner	Initial
6	PMFR1	Resource Group Creation	MAY	OwnerContributor	BAU
7	PMNFR1	Module Naming	MUST	Owner	Initial
8	PMNFR2	Use Resource Modules to Build a Pattern Module	MUST	OwnerContributor	BAU
9	PMNFR3	Use other Pattern Modules to Build a Pattern Module	MUST	OwnerContributor	BAU
10	BCPFR1	Cross-Referencing Modules	MAY	OwnerContributor	BAU
11	BCPFR2	Role Assignments Role Definition Mapping	MUST	OwnerContributor	BAU
12	BCPFR6	Cross-Referencing Child-Modules	MUST	OwnerContributor	BAU
13	BCPNFR19	User-defined types - Naming	MUST	OwnerContributor	BAU
14	BCPNFR5	Role Assignments Role Definition Mapping Limits	SHOULD	OwnerContributor	BAU
15	BCPNFR6	Role Assignments Role Definition Mapping Compulsory Roles	MUST	OwnerContributor	BAU
16	BCPNFR14	Versioning	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SFR1 - Category: Composition - Preview Services

Modules MAY create/adopt public preview services and features at their discretion.

Preview API versions MAY be used when:

The resource/service/feature is GA but the only API version available for the GA resource/service/feature is a preview version
- For example, Diagnostic Settings (Microsoft.Insights/diagnosticSettings) the latest version of the API available with GA features, like Category Groups etc., is 2021-05-01-preview
- Otherwise the latest “non-preview” version of the API SHOULD be used

Preview services and features, SHOULD NOT be promoted and exposed, unless they are supported by the respective PG, and it’s documented publicly.

However, they MAY be exposed at the module owners discretion, but the following rules MUST be followed:

The description of each of the parameters/variables used for the preview service/feature MUST start with:
- “THIS IS A <PARAMETER/VARIABLE> USED FOR A PREVIEW SERVICE/FEATURE, MICROSOFT MAY NOT PROVIDE SUPPORT FOR THIS, PLEASE CHECK THE PRODUCT DOCS FOR CLARIFICATION”

See origin...

ID: SFR2 - Category: Composition - WAF Aligned

Modules SHOULD set defaults in input parameters/variables to align to high priority/impact/severity recommendations, where appropriate and applicable, in the following frameworks and resources:

Well-Architected Framework (WAF)
Reliability Hub
Azure Proactive Resiliency Library (APRL)
- Only Product Group (PG) verified
Microsoft Defender for Cloud (MDFC)

They SHOULD NOT align to these recommendations when it requires an external dependency/resource to be deployed and configured and then associated to the resources in the module.

Alignment SHOULD prioritize best-practices and security over cost optimization, but MUST allow for these to be overridden by a module consumer easily, if desired.

Tip

Read the FAQ of What does AVM mean by “WAF Aligned”? for more detailed information and examples.

See origin...

ID: SFR5 - Category: Composition - Availability Zones

Modules that deploy zone-redundant resources MUST enable the spanning across as many zones as possible by default, typically all 3.

Modules that deploy zonal resources MUST provide the ability to specify a zone for the resources to be deployed/pinned to. However, they MUST NOT default to a particular zone by default, e.g. 1 in an effort to make the consumer aware of the zone they are selecting to suit their architecture requirements.

For both scenarios the modules MUST expose these configuration options via configurable parameters/variables.

Note

For information on the differences between zonal and zone-redundant services, see Availability zone service and regional support

See origin...

ID: SFR6 - Category: Composition - Data Redundancy

Modules that deploy resources or patterns that support data redundancy SHOULD enable this to the highest possible value by default, e.g. RA-GZRS. When a resource or pattern doesn’t provide the ability to specify data redundancy as a simple property, e.g. GRS etc., then the modules MUST provide the ability to enable data redundancy for the resources or pattern via parameters/variables.

For example, a Storage Account module can simply set the sku.name property to Standard_RAGZRS. Whereas a SQL DB or Cosmos DB module will need to expose more properties, via parameters/variables, to allow the specification of the regions to replicate data to as per the consumers requirements.

Note

For information on the data redundancy options in Azure, see Cross-region replication in Azure

See origin...

ID: SNFR25 - Category: Composition - Resource Naming

Module owners MUST set the default resource name prefix for child, extension, and interface resources to the associated abbreviation for the specific resource as documented in the following CAF article Abbreviation examples for Azure resources, if specified and documented. This reduces the amount of input values a module consumer MUST provide by default when using the module.

For example, a Private Endpoint that is being deployed as part of a resource module, via the mandatory interfaces, MUST set the Private Endpoint’s default name to begin with the prefix of pep-.

Module owners MUST also provide the ability for these default names, including the prefixes, to be overridden via a parameter/variable if the consumer wishes to.

Furthermore, as per RMNFR2, Resource Modules MUST not have a default value specified for the name of the primary resource and therefore the name MUST be provided and specified by the module consumer.

The name provided MAY be used by the module owner to generate the rest of the default name for child, extension, and interface resources if they wish to. For example, for the Private Endpoint mentioned above, the full default name that can be overridden by the consumer, MAY be pep-<primary-resource-name>.

Tip

If the resource does not have a documented abbreviation in Abbreviation examples for Azure resources, then the module owner is free to use a sensible prefix instead.

See origin...

ID: PMFR1 - Category: Composition - Resource Group Creation

A Pattern Module MAY create Resource Group(s).

See origin...

ID: PMNFR1 - Category: Naming - Module Naming

Pattern Modules MUST follow the below naming conventions (all lower case):

Bicep Pattern Module Naming

Naming convention: avm/ptn/<hyphenated grouping/category name>/<hyphenated pattern module name>
Example: avm/ptn/compute/app-tier-vmss or avm/ptn/avd-lza/management-plane or avm/ptn/3-tier/web-app
Segments:
- ptn defines this as a pattern module
- <hyphenated grouping/category name> is a hierarchical grouping of pattern modules by category, with each word separated by dashes, such as:
  - project name, e.g., avd-lza,
  - primary resource provider, e.g., compute or network, or
  - architecture, e.g., 3-tier
- <hyphenated pattern module name> is a term describing the module’s function, with each word separated by dashes, e.g., app-tier-vmss = Application Tier VMSS; management-plane = Azure Virtual Desktop Landing Zone Accelerator Management Plane

Terraform Pattern Module Naming

Naming convention:
- avm-ptn-<pattern module name> (Module name for registry)
- terraform-<provider>-avm-ptn-<pattern module name> (GitHub repository name to meet registry naming requirements)
Example: avm-ptn-apptiervmss or avm-ptn-avd-lza-managementplane
Segments:
- <provider> is the logical abstraction of various APIs used by Terraform. In most cases, this is going to be azurerm or azuread for resource modules.
- ptn defines this as a pattern module
- <pattern module name> is a term describing the module’s function, e.g., apptiervmss = Application Tier VMSS; avd-lza-managementplane = Azure Virtual Desktop Landing Zone Accelerator Management Plane

See origin...

ID: PMNFR2 - Category: Composition - Use Resource Modules to Build a Pattern Module

A Pattern Module SHOULD be built from AVM Resources Modules to establish a standardized code base and improve maintainability. If a valid reason exists, a pattern module MAY contain native resources (“vanilla” code) where it’s necessary. A Pattern Module MUST NOT contain references to non-AVM modules.

Valid reasons for not using a Resource Module for a resource required by a Pattern Module include but are not limited to:

When using a Resource Module would result in hitting scaling limitations and/or would reduce the capabilities of the Pattern Module due to the limitations of Azure Resource Manager.
Developing a Pattern Module under time constraint, without having all required Resource Modules readily available.

Note

In the latter case, the Pattern Module SHOULD be updated to use the Resource Module when the required Resource Module becomes available, to avoid accumulating technical debt. Ideally, all required Resource Modules SHOULD be developed first, and then leveraged by the Pattern Module.

See origin...

ID: PMNFR3 - Category: Composition - Use other Pattern Modules to Build a Pattern Module

A Pattern Module MAY contain and be built using other AVM Pattern Modules. A Pattern Module MUST NOT contain references to non-AVM modules.

See origin...

ID: BCPFR1 - Category: Composition - Cross-Referencing Modules

Module owners MAY cross-references other modules to build either Resource or Pattern modules.

However, they MUST be referenced only by a public registry reference to a pinned version e.g. br/public:avm/[res|ptn|utl]/<publishedModuleName>:>version<. They MUST NOT use local parent path references to a module e.g. ../../xxx/yyy.bicep.

The only exception to this rule are child modules as documented in BCPFR6.

Modules MUST NOT contain references to non-AVM modules.

See origin...

ID: BCPFR2 - Category: Composition - Role Assignments Role Definition Mapping

Module owners MAY define common RBAC Role Definition names and IDs within a variable to allow consumers to define a RBAC Role Definition by their name rather than their ID, this should be self contained within the module themselves.

However, they MUST use only the official RBAC Role Definition name within the variable and nothing else.

To meet the requirements of BCPFR2, BCPNFR5 and BCPNFR6 you MUST use the below code sample in your AVM Modules to achieve this.

  @description('''Required. You can provide either the display name (note not all roles are supported, check module documentation) of the role definition, or its fully qualified ID in the following format: `/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11`.''')
  param roleDefinitionIdOrName string
  
  var builtInRbacRoleNames = {
    Owner: '/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635'
    Contributor: '/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c'
    Reader: '/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7'
    'Role Based Access Control Administrator (Preview)': '/providers/Microsoft.Authorization/roleDefinitions/f58310d9-a9f6-439a-9e8d-f62e7b41a168'
    'User Access Administrator': '/providers/Microsoft.Authorization/roleDefinitions/18d7d88d-d35e-4fb5-a5c3-7773c20a72d9'
    //Other RBAC Role Definitions Names & IDs can be added here as needed for your module
  }
  
  var roleDefinitionIdMappedResult = (contains(builtInRbacRoleNames, roleDefinitionIdOrName) ? builtInRbacRoleNames[roleDefinitionIdOrName] : roleDefinitionIdOrName)
  
  resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    //Other properties removed for ease of reading
    properties: {
      roleDefinitionId: roleDefinitionIdMappedResult
      //Other properties removed for ease of reading
    }
  }

See origin...

ID: BCPFR6 - Cross-Referencing Child-Modules

Parent templates MUST reference all their direct child-templates to allow for an end-to-end deployment experience.
For example, the SQL server template must reference its child database module and encapsulate it in a loop to allow for the deployment of multiple databases.

@description('Optional. The databases to create in the server')
param databases databaseType[]?

resource server 'Microsoft.Sql/servers@(...)' = { (...) }

module server_databases 'database/main.bicep' = [for (database, index) in (databases ?? []): {
  name: '${uniqueString(deployment().name, location)}-Sql-DB-${index}'
  params: {
    serverName: server.name
    (...)
  }
}]

See origin...

ID: BCPNFR19 - User-defined types - Naming

User-defined types (UDTs) MUST always end with the suffix (...)Type to make them obvious to users. In addition it is recommended to extend the suffix to (...)OutputType if a UDT is exclusively used for outputs.

type subnet = { ... } // Wrong
type subnetType = { ... } // Correct
type subnetOutputType = { ... } // Correct, if used only for outputs

Since User-defined types (UDTs) MUST always be singular as per BCPNFR18, their naming should reflect this and also be singular.

type subnetsType = { ... } // Wrong
type subnetType = { ... } // Correct

See origin...

ID: BCPNFR5 - Category: Composition - Role Assignments Role Definition Mapping Limits

As per BCPFR2, module owners MAY define common RBAC Role Definition names and IDs within a variable to allow consumers to define a RBAC Role Definition by their name rather than their ID.

Module owners SHOULD NOT map every RBAC Role Definition within this variable as it can cause the module to bloat in size and cause consumption issues later when stitched together with other modules due to the 4MB ARM Template size limit.

Therefore module owners SHOULD only map the most applicable and common RBAC Role Definition names for their module and SHOULD NOT exceed 15 RBAC Role Definitions in the variable.

Important

Remember if the RBAC Role Definition name is not included in the variable this does not mean it cannot be declared, used and assigned to an identity via an RBAC Role Assignment as part of a module, as any RBAC Role Definition can be specified via its ID without being in the variable.

Tip

Review the Bicep Contribution Guide’s ‘RBAC Role Definition Name Mapping’ section for a code sample to achieve this requirement.

See origin...

ID: BCPNFR6 - Category: Composition - Role Assignments Role Definition Mapping Compulsory Roles

Module owners MUST include the following roles in the variable for RBAC Role Definition names:

Owner - ID: 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor - ID: b24988ac-6180-42a0-ab88-20f7382dd24c
Reader - ID: acdd72a7-3385-48ef-bd42-f606fba81ae7
User Access Administrator - ID: 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9
Role Based Access Control Administrator (Preview) - ID: f58310d9-a9f6-439a-9e8d-f62e7b41a168

Tip

Review the Bicep Contribution Guide’s ‘RBAC Role Definition Name Mapping’ section for a code sample to achieve this requirement.

See origin...

ID: BCPNFR14 - Category: Composition - Versioning

To meet SNFR17 and depending on the changes you make, you may need to bump the version in the version.json file.

  {
    "$schema": "https://aka.ms/bicep-registry-module-version-file-schema#",
    "version": "0.1",
    "pathFilters": [
        "./main.json"
    ]
  }

The version value is in the form of MAJOR.MINOR. The PATCH version will be incremented by the CI automatically when publishing the module to the Public Bicep Registry once the corresponding pull request is merged. Therefore, contributions that would only require an update of the patch version, can keep the version.json file intact.

For example, the version value should be:

0.1 for new modules, so that they can be released as v0.1.0.
1.0 once the module owner signs off the module is stable enough for it’s first Major release of v1.0.0.
0.x for all feature updates between the first release v0.1.0 and the first Major release of v1.0.0.

Inputs / Outputs

The content below is listed based on the following tags

Category-Inputs/OutputsClass-PatternLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR14	Data Types	SHOULD	OwnerContributor	BAU
2	SNFR22	Parameters/Variables for Resource IDs	MUST	OwnerContributor	BAU
3	SNFR26	Output - Parameters - Decorators	MUST	OwnerContributor	BAU
4	PMNFR5	Parameter/Variable Naming	SHOULD	OwnerContributor	BAU
5	BCPNFR1	Complex data types - General	MUST	OwnerContributor	BAU
6	BCPNFR9	Inputs - Decorators	MUST	OwnerContributor	BAU
7	BCPNFR18	User-defined types - Specification	MUST	OwnerContributor	BAU
8	BCPNFR19	User-defined types - Naming	MUST	OwnerContributor	BAU
9	BCPNFR20	User-defined types - Export	MUST	OwnerContributor	BAU
10	BCPNFR21	User-defined types - Decorators	MUST	OwnerContributor	BAU
11	BCPNFR7	Parameter Requirement Types	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR14 - Category: Inputs - Data Types

A module SHOULD use either: simple data types. e.g., string, int, bool.

Complex data types (objects, arrays, maps) when the language-compliant schema is defined.

See origin...

ID: SNFR22 - Category: Inputs - Parameters/Variables for Resource IDs

A module parameter/variable that requires a full Azure Resource ID as an input value, e.g. /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/vaults/{keyVaultName}, MUST contain ResourceId/resource_id in its parameter/variable name to assist users in knowing what value to provide at a glance of the parameter/variable name.

Example for the property workspaceId for the Diagnostic Settings resource. In Bicep its parameter name should be workspaceResourceId and the variable name in Terraform should be workspace_resource_id.

workspaceId is not descriptive enough and is ambiguous as to which ID is required to be input.

See origin...

ID: SNFR26 - Output-Parameters - Decorators

Output parameters MUST implement:

Decorators in Bicep such as description & secure (if sensitive)
Arguments in Terraform such as description & sensitive (if sensitive)

Output parameters

@description('The resourceId of your resource.')
output sampleResourceId string = sampleResource.id

@description('The key of your resource.')
@secure()
output sampleResourceKey string = sampleResource.key

# Resource output
output "foo" {
  description = "MyResource foo attribute"
  value = azurerm_resource_myresource.foo
}

# Output of a sensitive attribute
output "bar" {
  description = "MyResource bar attribute"
  value     = azurerm_resource_myresource.bar
  sensitive = true
}

See origin...

ID: PMNFR5 - Category: Inputs - Parameter/Variable Naming

Parameter/variable input names SHOULD contain the resource to which they pertain. E.g., virtualMachineSku/virtualmachine_sku

See origin...

ID: BCPNFR1 - Category: Inputs - Complex data types - General

To simplify the consumption experience for module consumers when interacting with complex data types input parameters, mainly objects and arrays, the Bicep features of Resource-Derived Types or User-Defined Types MUST be used and declared.

Tip

User-Defined Types are GA in Bicep as of version v0.21.1, Resource-Derived Types are GA as of version v0.34.1, please ensure you have this version(s) installed as a minimum.

Resource-Derived Types and User-Defined Types allow intellisense support in supported IDEs (e.g. Visual Studio Code) for complex input parameters using objects and array of objects.

v0.x Exemption

While we allow the release of major versions, starting with v1.0.0, retrofitting Resource-Derived Types and User-Defined Types for all modules will take a considerable amount of time.

Therefore, the addition of these features is currently NOT mandated/enforced. However, all modules MUST implement Resource-Derived Types and User-Defined Types prior to the release of their v1.0.0 version.

See origin...

ID: BCPNFR9 - Inputs - Decorators

Similar to BCPNFR21, input parameters MUST implement decorators such as description & secure (if sensitive).

Further, input parameters SHOULD implement decorators like allowed, minValue, maxValue, minLength & maxLength (and others if available) as they have a big positive impact on the module’s usability.

@description('Optional. The threshold of your resource.')
@minValue(1)
@maxValue(10)
param threshold: int?
@description('Required. The SKU of your resource.')
@allowed([
'Basic'
'Premium'
'Standard'
])
param sku string

See origin...

ID: BCPNFR18 - User-defined types - Specification

User-defined types (UDTs) MUST always be singular and non-nullable. The configuration of either should instead be done directly at the parameter or output that uses the type.

For example, instead of

param subnets subnetsType
type subnetsType = { ... }[]?

the type should be defined like

param subnets subnetType[]?
type subnetType = { ... }

The primary reason for this requirement is clarity. If not defined directly at the parameter or output, a user would always be required to check the type to understand how e.g., a parameter is expected.

See origin...

ID: BCPNFR19 - User-defined types - Naming

type subnet = { ... } // Wrong
type subnetType = { ... } // Correct
type subnetOutputType = { ... } // Correct, if used only for outputs

Since User-defined types (UDTs) MUST always be singular as per BCPNFR18, their naming should reflect this and also be singular.

type subnetsType = { ... } // Wrong
type subnetType = { ... } // Correct

See origin...

ID: BCPNFR20 - User-defined types - Export

User-defined types (UDTs) SHOULD always be exported via the @export() annotation in every template they’re implemented in.

@export()
type subnetType = { ... }

Doing so has the benefit that other (e.g., parent) modules can import them and as such reduce code duplication. Also, if the module itself is published, users of the Public Bicep Registry can import the types independently of the module itself. One example where this can be useful is a pattern module that may re-use the same interface when referencing a module from the registry.

See origin...

ID: BCPNFR21 - User-defined types - Decorators

Similar to BCPNFR9, User-defined types (UDTs) MUST implement decorators such as description & secure (if sensitive). This is true for every property of the UDT, as well as the UDT itself.

Further, User-defined types SHOULD implement decorators like allowed, minValue, maxValue, minLength & maxLength (and others if available) as they have a big positive impact on the module’s usability.

@description('My type''s description.')
type myType = {
  @description('Optional. The threshold of your resource.')
  @minValue(1)
  @maxValue(10)
  threshold: int?

  @description('Required. The SKU of your resource.')
  sku: ('Basic' | 'Premium' | 'Standard')
}

See origin...

ID: BCPNFR7 - Category: Inputs - Parameter Requirement Types

Modules will have lots of parameters that will differ in their requirement type (required, optional, etc.). To help consumers understand what each parameter’s requirement type is, module owners MUST add the requirement type to the beginning of each parameter’s description. Below are the requirement types with a definition and example for the description decorator:

Parameter Requirement Type	Definition	Example Description Decorator
Required	The parameter value must be provided. The parameter does not have a default value and hence the module expects and requires an input.	`@description('Required. <PARAMETER DESCRIPTION HERE...>')`
Conditional	The parameter value can be optional or required based on a condition, mostly based on the value provided to other parameters. Should contain a sentence starting with ‘Required if (…).’ to explain the condition.	`@description('Conditional. <PARAMETER DESCRIPTION HERE...>')`
Optional	The parameter value is not mandatory. The module provides a default value for the parameter.	`@description('Optional. <PARAMETER DESCRIPTION HERE...>')`
Generated	The parameter value is generated within the module and should not be specified as input in most cases. A common example of this is the `utcNow()` function that is only supported as the input for a parameter value, and not inside a variable.	`@description('Generated. <PARAMETER DESCRIPTION HERE...>')`

Testing

The content below is listed based on the following tags

Category-TestingClass-PatternLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR1	Prescribed Tests	MUST	OwnerContributor	BAU
2	SNFR2	E2E Testing	MUST	OwnerContributor	BAU
3	SNFR3	AVM Compliance Tests	MUST	OwnerContributor	Initial
4	SNFR4	Unit Tests	SHOULD	OwnerContributor	BAU
5	SNFR5	Upgrade Tests	SHOULD	OwnerContributor	BAU
6	SNFR6	Static Analysis/Linting Tests	MUST	OwnerContributor	BAU
7	SNFR7	Idempotency Tests	MUST	OwnerContributor	BAU
8	SNFR24	Testing Child, Extension & Interface Resources	MUST	OwnerContributor	BAU
9	BCPNFR10	Test Bicep File Naming	MUST	OwnerContributor	BAU
10	BCPNFR11	Test Tooling	MUST	OwnerContributor	BAU
11	BCPNFR12	Deployment Test Naming	MUST	OwnerContributor	BAU
12	BCPNFR13	Test file metadata	MUST	OwnerContributor	BAU
13	BCPNFR16	Post-deployment tests	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR1 - Category: Testing - Prescribed Tests

Modules MUST use the prescribed tooling and testing frameworks defined in the language specific specs.

See origin...

ID: SNFR2 - Category: Testing - E2E Testing

Modules MUST implement end-to-end (deployment) testing that create actual resources to validate that module deployments work. In Bicep tests are sourced from the directories in /tests/e2e. In Terraform, these are in /examples.

Each test MUST run and complete without user inputs successfully, for automation purposes.

Each test MUST also destroy/clean-up its resources and test dependencies following a run.

Tip

To see a directory and file structure for a module, see the language specific contribution guide.

Resources/Dependencies Required for E2E Tests

It is likely that to complete E2E tests, a number of resources will be required as dependencies to enable the tests to pass successfully. Some examples:

When testing the Diagnostic Settings interface for a Resource Module, you will need an existing Log Analytics Workspace to be able to send the logs to as a destination.
When testing the Private Endpoints interface for a Resource Module, you will need an existing Virtual Network, Subnet and Private DNS Zone to be able to complete the Private Endpoint deployment and configuration.

Module owners MUST:

Create the required resources that their module depends upon in the test file/directory
- They MUST either use:
  - Simple/native resource declarations/definitions in their respective IaC language,
    OR
  - Another already published AVM Module that MUST be pinned to a specific published version.
    - They MUST NOT use any local directory path references or local copies of AVM modules in their own modules test directory.

➕ Terraform & Bicep Log Analytics Workspace examples using simple/native declarations for use in E2E tests

Terraform

resource "azurerm_resource_group" "example" {
  name     = "rsg-test-001"
  location = "West Europe"
}

resource "azurerm_log_analytics_workspace" "example" {
  name                = "law-test-001"
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  sku                 = "PerGB2018"
  retention_in_days   = 30
}

Bicep

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2021-12-01-preview' = {
  name: 'law-test-001'
  location: resourceGroup().location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
    retentionInDays: 30
  }
}

Skipping Deployments (SHOULD NOT)

Deployment tests are an important part of a module’s validation and a staple of AVM’s CI environment. However, there are situations where certain e2e-test-deployments cannot be performed against AVM’s test environment (e.g., if a special configuration/registration (such as certain AI models) is required). For these cases, the CI offers the possibility to ‘skip’ specific test cases by placing a file named .e2eignore in their test folder.

Note

A skipped test case is still added to the ‘Usage Examples’ section of the module’s readme and should be manually validated in regular intervals.

Details for use in E2E tests

You MUST add a note to the tests metadata description, which explains the excemption.

If you require that a test is skipped and add an “.e2eignore” file (e.g. \<module\>/tests/e2e/\<testname\>/.e2eignore) to a pull request, a member of the AVM Core Technical Bicep Team must approve set pull request. The content of the file is logged the module’s workflow runs and transparently communicates why the test case is skipped during the deployment validation stage. It iss hence important to specify the reason for skipping the deployment in this file.

Sample filecontent:

The test is skipped, as only one instance of this service can be deployed to a subscription.

Note

For resource modules, the ‘defaults’ and ‘waf-aligned’ tests can’t be skipped.

The deployment of a test can be skipped by adding a .e2eignore file into a test folder (e.g. /examples/<testname>).

See origin...

ID: SNFR3 - Category: Testing - AVM Compliance Tests

Modules MUST pass all tests that ensure compliance to AVM specifications. These tests MUST pass before a module version can be published.

Important

Please note these are still under development at this time and will be published and available soon for module owners.

Module owners MUST request a manual GitHub Pull Request review, prior to their first release of version 0.1.0 of their module, from the related GitHub Team: @Azure/avm-core-team-technical-bicep, OR @Azure/avm-core-team-technical-terraform.

See origin...

ID: SNFR4 - Category: Testing - Unit Tests

Modules SHOULD implement unit testing to ensure logic and conditions within parameters/variables/locals are performing correctly. These tests MUST pass before a module version can be published.

Unit Tests test specific module functionality, without deploying resources. Used on more complex modules. In Bicep and Terraform these live in tests/unit.

See origin...

ID: SNFR5 - Category: Testing - Upgrade Tests

Modules SHOULD implement upgrade testing to ensure new features are implemented in a non-breaking fashion on non-major releases.

See origin...

ID: SNFR6 - Category: Testing - Static Analysis/Linting Tests

Modules MUST use static analysis, e.g., linting, security scanning (PSRule, tflint, etc.). These tests MUST pass before a module version can be published.

There may be differences between languages in linting rules standards, but the AVM core team will try to close these and bring them into alignment over time.

See origin...

ID: SNFR7 - Category: Testing - Idempotency Tests

Modules MUST implement idempotency end-to-end (deployment) testing. E.g. deploying the module twice over the top of itself.

Modules SHOULD pass the idempotency test, as we are aware that there are some exceptions where they may fail as a false-positive or legitimate cases where a resource cannot be idempotent.

For example, Virtual Machine Image names must be unique on each resource creation/update.

See origin...

ID: SNFR24 - Category: Testing - Testing Child, Extension & Interface Resources

Module owners MUST test that child and extension resources and those Bicep or Terreform interface resources that are supported by their modules, are validated in E2E tests as per SNFR2 to ensure they deploy and are configured correctly.

These MAY be tested in a separate E2E test and DO NOT have to be tested in each E2E test.

See origin...

ID: BCPNFR10 - Category: Testing - Test Bicep File Naming

Module owners MUST name their test .bicep files in the /tests/e2e/<defaults/waf-aligned/max/etc.> directories: main.test.bicep as the test framework (CI) relies upon this name.

See origin...

ID: BCPNFR11 - Category: Testing - Test Tooling

Module owners MUST use the below tooling for unit/linting/static/security analysis tests. These are also used in the AVM Compliance Tests.

PSRule for Azure
Pester
- Some tests are provided as part of the AVM Compliance Tests, but you are free to also use Pester for your own tests.

See origin...

ID: BCPNFR12 - Category: Testing - Deployment Test Naming

Module owners MUST invoke the module in their test using the syntax:

module testDeployment '../../../main.bicep' =

Example 1: Working example with a single deployment

module testDeployment '../../../main.bicep' = {
  scope: resourceGroup
  name: '${uniqueString(deployment().name, location)}-test-${serviceShort}'
  params: {
    (...)
  }
}

Example 2: Working example using a deployment loop

@batchSize(1)
module testDeployment '../../main.bicep' = [for iteration in [ 'init', 'idem' ]: {
  scope: resourceGroup
  name: '${uniqueString(deployment().name, location)}-test-${serviceShort}-${iteration}'
  params: {
    (...)
  }
}]

The syntax is used by the ReadMe-generating utility to identify, pull & format usage examples.

See origin...

ID: BCPNFR13 - Category: Testing - Test file metadata

By default, the ReadMe-generating utility will create usage examples headers based on each e2e folder’s name.
Module owners MAY provide a custom name & description by specifying the metadata blocks name & description in their main.test.bicep test files.

For example:

metadata name = 'Using Customer-Managed-Keys with System-Assigned identity'
metadata description = 'This instance deploys the module using Customer-Managed-Keys using a System-Assigned Identity. This required the service to be deployed twice, once as a pre-requisite to create the System-Assigned Identity, and once to use it for accessing the Customer-Managed-Key secret.'

would lead to a header in the module’s readme.md file along the lines of

### Example 1: _Using Customer-Managed-Keys with System-Assigned identity_

This instance deploys the module using Customer-Managed-Keys using a System-Assigned Identity. This required the service to be deployed twice, once as a pre-requisite to create the System-Assigned Identity, and once to use it for accessing the Customer-Managed-Key secret.

See origin...

ID: BCPNFR16 - Category: Testing - Post-deployment tests

For each test case in the e2e folder, you can optionally add post-deployment Pester tests that are executed once the corresponding deployment completed and before the removal logic kicks in.

To leverage the feature you MUST:

Use Pester as a test framework in each test file
Name the file with the suffix "*.tests.ps1"
Place each test file the e2e test’s folder or any subfolder (e.g., e2e/max/myTest.tests.ps1 or e2e/max/tests/myTest.tests.ps1)

Implement an input parameter TestInputData in the following way:

param (
    [Parameter(Mandatory = $false)]
    [hashtable] $TestInputData = @{}
)

Through this parameter you can make use of every output the main.test.bicep file returns, as well as the path to the test template file in case you want to extract data from it directly.

For example, with an output such as output resourceId string = testDeployment[1].outputs.resourceId defined in the main.test.bicep file, the $TestInputData would look like:

$TestInputData = @{
  DeploymentOutputs    = @{
    resourceId = @{
      Type  = "String"
      Value = "/subscriptions/***/resourceGroups/dep-***-keyvault.vaults-kvvpe-rg/providers/Microsoft.KeyVault/vaults/***kvvpe001"
    }
  }
  ModuleTestFolderPath = "/home/runner/work/bicep-registry-modules/bicep-registry-modules/avm/res/key-vault/vault/tests/e2e/private-endpoint"
}

A full test file may look like:

➕ Pester post-deployment test file example

param (
    [Parameter(Mandatory = $false)]
    [hashtable] $TestInputData = @{}
)

Describe 'Validate private endpoint deployment' {

    Context 'Validate sucessful deployment' {

        It "Private endpoints should be deployed in resource group" {

            $keyVaultResourceId = $TestInputData.DeploymentOutputs.resourceId.Value
            $testResourceGroup = ($keyVaultResourceId -split '\/')[4]
            $deployedPrivateEndpoints = Get-AzPrivateEndpoint -ResourceGroupName $testResourceGroup
            $deployedPrivateEndpoints.Count | Should -BeGreaterThan 0
        }
    }
}

Documentation

The content below is listed based on the following tags

Category-DocumentationClass-PatternLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR15	Automatic Documentation Generation	MUST	OwnerContributor	BAU
2	SNFR16	Examples/E2E	MUST	OwnerContributor	BAU
3	BCPNFR2	Module Documentation Generation	MUST	OwnerContributor	BAU
4	BCPNFR3	Usage Example formats	MUST	OwnerContributor	BAU
5	BCPNFR4	Parameter Input Examples	MAY	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR15 - Category: Documentation - Automatic Documentation Generation

README documentation MUST be automatically/programmatically generated. MUST include the sections as defined in the language specific requirements BCPNFR2, TFNFR2.

See origin...

ID: SNFR16 - Category: Documentation - Examples/E2E

An examples/e2e directory MUST exist to provide named scenarios for module deployment.

See origin...

ID: BCPNFR2 - Category: Documentation - Module Documentation Generation

Note

This script/tool is currently being developed by the AVM team and will be made available very soon.

Bicep modules documentation MUST be automatically generated via the provided script/tooling from the AVM team, providing the following headings:

Title
Description
Navigation
Resource Types
Usage Examples
Parameters
Outputs
Cross-referenced modules

See origin...

ID: BCPNFR3 - Category: Documentation - Usage Example formats

Usage examples for Bicep modules MUST be provided in the following formats:

Bicep file (orchestration module style) - .bicep

module <resourceName> 'br/public:avm/[res|ptn|utl]/<publishedModuleName>:>version<' = {
  name: '${uniqueString(deployment().name, location)}-test-<uniqueIdentifier>'
  params: { (...) }
}

JSON / ARM Template Parameter Files - .json

{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": { (...) }
}

Note

The above formats are currently automatically taken & generated from the tests/e2e tests. It is enough to run the Set-ModuleReadMe or Set-AVMModule functions (from the utilities folder) to update the usage examples in the readme(s).

Note

Bicep Parameter Files (.bicepparam) are being reviewed and considered by the AVM team for the usability and features at this time and will likely be added in the future.

See origin...

ID: BCPNFR4 - Category: Documentation - Parameter Input Examples

Bicep modules MAY provide parameter input examples for parameters using the metadata.example property via the @metadata() decorator.

Example:

@metadata({
  example: 'uksouth'
})
@description('Optional. Location for all resources.')
param location string = resourceGroup().location

@metadata({
  example: '''
  {
    keyName: 'myKey'
    keyVaultResourceId: '/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/my-rg/providers/Microsoft.KeyVault/vaults/myvault'
    keyVersion: '6d143c1a0a6a453daffec4001e357de0'
    userAssignedIdentityResourceId '/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/my-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity'
  }
  '''
})
@description('Optional. The customer managed key definition.')
param customerManagedKey customerManagedKeyType

It is planned that these examples are automatically added to the module readme’s parameter descriptions when running either the Set-ModuleReadMe or Set-AVMModule scripts (available in the utilities folder).

Release / Publishing

The content below is listed based on the following tags

Category-Release/PublishingClass-PatternLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR17	Semantic Versioning	MUST	OwnerContributor	BAU
2	SNFR18	Breaking Changes	SHOULD	OwnerContributor	BAU
3	SNFR19	Registries Targeted	MUST	OwnerContributor	BAU
4	SNFR21	Cross Language Collaboration	SHOULD	OwnerContributor	BAU
5	BCPNFR22	Bicep Module Changelog	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR17 - Category: Release - Semantic Versioning

Important

You cannot specify the patch version for Bicep modules in the public Bicep Registry, as this is automatically incremented by 1 each time a module is published. You can only set the Major and Minor versions.

See the Bicep Contribution Guide for more information.

Modules MUST use semantic versioning (aka semver) for their versions and releases in accordance with: Semantic Versioning 2.0.0

For example all modules should be released using a semantic version that matches this pattern: X.Y.Z

X == Major Version
Y == Minor Version
Z == Patch Version

Module versioning before first Major version release `1.0.0`

Initially modules MUST be released as version 0.1.0 and incremented via Minor and Patch versions only until the AVM Core Team are confident the AVM specifications are mature enough and appropriate CI test coverage is in place, plus the module owner is happy the module has been “road tested” and is now stable enough for its first Major release of version 1.0.0.
Note
Releasing as version 0.1.0 initially and only incrementing Minor and Patch versions allows the module owner to make breaking changes more easily and frequently as it’s still not an official Major/Stable release. 👍
Until first Major version 1.0.0 is released, given a version number X.Y.Z:
- X Major version MUST NOT be bumped.
- Y Minor version MUST be bumped when introducing breaking changes (which would normally bump Major after 1.0.0 release) or feature updates (same as it will be after 1.0.0 release).
- Z Patch version MUST be bumped when introducing non-breaking, backward compatible bug fixes (same as it will be after 1.0.0 release).

See origin...

ID: SNFR18 - Category: Release - Breaking Changes

A module SHOULD avoid breaking changes, e.g., deprecating inputs vs. removing. If you need to implement changes that cause a breaking change, the major version should be increased.

Info

Modules that have not been released as 1.0.0 may introduce breaking changes, as explained in the previous ID SNFR17. That means that you have to introduce non-breaking and breaking changes with a minor version jump, as long as the module has not reached version 1.0.0.

There are, however, scenarios where you want to include breaking changes into a commit and not create a new major version. If you want to introduce breaking changes as part of a minor update, you can do so. In this case, it is essential to keep the change backward compatible, so that the existing code will continue to work. At a later point, another update can increase the major version and remove the code introduced for the backward compatibility.

Tip

See the language specific examples to find out how you can deal with deprecations in AVM modules.

Bicep

See origin...

ID: SNFR19 - Category: Publishing - Registries Targeted

Modules MUST be published to their respective language public registries.

Bicep = Bicep Public Module Registry
- Within the avm directory
Terraform = HashiCorp Terraform Registry

Tip

See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

See origin...

ID: SNFR21 - Category: Publishing - Cross Language Collaboration

When the module owners of the same Resource or Pattern AVM module are not the same individual or team for all languages, each languages team SHOULD collaborate with their sibling language team for the same module to ensure consistency where possible.

See origin...

ID: BCPNFR22 - Category: Publishing - Changelog

When a module to be published (i.e., that has a version.json file) is changed, an entry MUST be created in the CHANGELOG.md file in the module folder. A link to the latest version of the changelog file has to be included at the top of the file, just below the # Changelog line. It is surrounded by empty lines.

# Changelog

The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/<ptn|res|utl>/<namespace/modulename[/submodulePath]>/CHANGELOG.md).

For each new version, an entry MUST be created above all existing versions in the CHANGELOG.md file of the module.

## <version>

### Changes

- This changed
- And this also

### Breaking Changes

- None

Each version’s entry:

MUST contain two sections: Changes and Breaking Changes. At least one of them must have a meaningful entry and sections must not be left empty. A - None may be added as content for a section.
MUST exist only once.
All versions appear in descending order, which puts the most recent changes at the top.

What SHOULD be listed in the (Breaking) Changes section:

Relevant changes for the module
Changes in tests do not need to be added

Note

The versioning is following the SNFR17 - Semantic Versioning spec.

Example content of the CHANGELOG.md

A CHANGELOG.md file in the module’s root folder MUST start with the # Changelog header, followed by an empty line and a link to the latest published version of the changelog file, followed by another empty line. A section for each published version follows. Newer versions are placed above older versions.

# Changelog

The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/aad/domain-service/CHANGELOG.md).

## 0.2.1

### Changes

- Updated the referenced AVM common types

### Breaking Changes

- None

## 0.2.0

### Changes

- Implemented the minCPU parameter
- Updated the referenced VirtualNetwork module
- Updated the referenced AVM common types

### Breaking Changes

- The minCPU parameter is mandatory

## 0.1.0

### Changes

- Initial Release

### Breaking Changes

- None

Each bullet point should start with a capital letter.

Manual Editing

It is possible to modify the changelog content any time, e.g., to add missing versions, which will not create a new release of the module itself. Please note the following requirements in all cases:

All versions in the file, need to be valid and available as published version
Every version needs the two sections ## Changes and ## Breaking Changes with content

Note

Azure Verified Modules are artifacts in the Microsoft Container Registry (MCR). Every version of a module exists as a tag in the Container Registry and can be listed as tags for each module https://mcr.microsoft.com/v2/bicep/avm/(res|ptn|utl)/<namespace/modulename>/tags/list

Code Style

The content below is listed based on the following tags

Category-CodeStyleClass-PatternLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	BCPNFR8	Code Styling - lower camelCasing	SHOULD	OwnerContributor	BAU
2	BCPNFR17	Code Styling - Type casting	SHOULD	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: BCPNFR8 - Category: Composition - Code Styling - lower camelCasing

Module owners SHOULD use lower camelCasing for naming the following:

Parameters
Variables
Outputs
User Defined Types
Resources (symbolic names)
Modules (symbolic names)

For example: camelCasingExample (lowercase first word (entirely), with capital of first letter of all other words and rest of word in lowercase)

See origin...

ID: BCPNFR17 - Category: Composition - Code Styling - Type casting

To improve the usability of primitive module properties declared as strings, you SHOULD declare them using a type which better represents them, and apply any required casting in the module on behalf of the user.

For reference, please refer to the following examples:

Boolean as String

@allowed([
  'false'
  'true'
])
param myParameterValue string = 'false'

resource myResource '(...)' = {
  (...)
  properties: {
    myParameter: myParameterValue
  }
}

param myParameterValue string = false

resource myResource '(...)' = {
  (...)
  properties: {
    myParameter: string(myParameterValue)
  }
}

Integer Array as String Array

@allowed([
  '1'
  '2'
  '3'
])
param zones array

resource myResource '(...)' = {
  (...)
  properties: {
    zones: zones
  }
}

@allowed([
  1
  2
  3
])
param zones int[]

resource myResource '(...)' = {
  (...)
  properties: {
    zones: map(zones, zone => string(zone))
  }
}

Bicep Resource Module Specifications

Contribution / Support

The content below is listed based on the following tags

Category-Contribution/SupportClass-ResourceLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR8	Module Owner(s) GitHub	MUST	Owner	Initial
2	SNFR20	GitHub Teams Only	MUST	Owner	Initial
3	SNFR9	AVM & PG Teams GitHub Repo Permissions	MUST	Owner	Initial
4	SNFR10	MIT Licensing	MUST	Owner	Initial
5	SNFR11	Issues Response Times	MUST	OwnerContributor	BAU
6	SNFR12	Versions Supported	MUST	Owner	BAU
7	SNFR23	GitHub Repo Labels	MUST	Owner	BAU
8	PMNFR4	Missing Resource Module(s)	MUST	OwnerContributor	BAU
9	BCPNFR15	AVM Module Issue template file	MUST	Owner	BAU

➕ See Specifications for this category

See origin...

ID: SNFR8 - Category: Contribution/Support - Module Owner(s) GitHub

A module MUST have an owner that is defined and managed by a GitHub Team in the Azure GitHub organization.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

See origin...

ID: SNFR20 - Category: Contribution/Support - GitHub Teams Only

All GitHub repositories that AVM module are published from and hosted within MUST only assign GitHub repository permissions to GitHub teams only.

Each module MUST have separate GitHub teams assigned for module owners AND module contributors respectively. These GitHub teams MUST be created in the Azure organization in GitHub.

There MUST NOT be any GitHub repository permissions assigned to individual users.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

Important

Naming Convention

The naming convention for the GitHub teams MUST follow the below pattern:

<hyphenated module name>-module-owners-<bicep/tf> - to be assigned as the GitHub repository’s Module Owners team
<hyphenated module name>-module-contributors-<bicep/tf> - to be assigned as the GitHub repository’s Module Contributors team

Note

The naming convention for Bicep modules is slightly different than the naming convention for their respective GitHub teams.

Segments:

<hyphenated module name> == the AVM Module’s name, with each segment separated by dashes, i.e., avm-res-<resource provider>-<ARM resource type>
- See RMNFR1 for AVM Resource Module Naming
- See PMNFR1 for AVM Pattern Module Naming
module-owners or module-contributors == the role the GitHub Team is assigned to
<bicep/tf> == the language the module is written in

Examples:

avm-res-compute-virtualmachine-module-owners-bicep
avm-res-compute-virtualmachine-module-contributors-tf

Add Team Members

All officially documented module owner(s) MUST be added to the -module-owners- team. The -module-owners- team MUST NOT have any other members.

Any additional module contributors whom the module owner(s) agreed to work with MUST be added to the -module-contributors- team.

Grant Permissions - Bicep

Team memberships

Note

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<hyphenated module name>-module-owners-bicep`	AVM Bicep Module Owners - <module name>	Write	Assignment to the `avm-technical-reviewers-bicep` parent team.	Need to work in a fork.
`<hyphenated module name>-module-contributors-bicep`	AVM Bicep Module Contributors - <module name>	Triage	`avm-module-contributors-bicep` parent team.	Need to work in a fork.

Examples - GitHub teams required for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

avm-res-network-virtualnetwork-module-owners-bicep –> assign to the avm-technical-reviewers-bicep parent team.
avm-res-network-virtualnetwork-module-contributors-bicep –> assign to the avm-module-contributors-bicep parent team.

Tip

Direct link to create a new GitHub team and assign it to its parent: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Follow the guidance above (see the Permissions granted through column in the table above).
Team visibility: Visible
Team notifications: Enabled

CODEOWNERS file

As part of the “initial Pull Request” (that publishes the first version of the module), module owners MUST add an entry to the CODEOWNERS file in the BRM repository (here).

Note

Through this approach, the AVM core team will grant review permission to module owners as part of the standard PR review process.

Every CODEOWNERS entry (line) MUST include the following segments separated by a single whitespace character:

Path of the module, relative to the repo’s root, e.g.: /avm/res/network/virtual-network/
The -module-owners-team, with the @Azure/ prefix, e.g., @Azure/avm-res-network-virtualnetwork-module-owners-bicep
The GitHub team of the AVM Bicep reviewers, with the @Azure/ prefix, i.e., @Azure/avm-module-reviewers-bicep

Example - CODEOWNERS entry for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

/avm/res/network/virtual-network/ @Azure/avm-res-network-virtualnetwork-module-owners-bicep @Azure/avm-module-reviewers-bicep

Grant Permissions - Terraform

Module owners MUST assign the -module-owners-and -module-contributors- teams the necessary permissions on their Terraform module repository per the guidance below.

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<module name>-module-owners-tf`	AVM Terraform Module Owners - <module name>	Admin	Direct assignment to repo	Module owner can decide whether they want to work in a branch local to the repo or in a fork.
`<module name>-module-contributors-tf`	AVM Terraform Module Contributors - <module name>	Write	Direct assignment to repo	Need to work in a fork.

Tip

Direct link to create a new GitHub team: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Do not assign the team to any parent team.
Team visibility: Visible
Team notifications: Enabled

See origin...

ID: SNFR9 - Category: Contribution/Support - AVM & PG Teams GitHub Repo Permissions

A module owner MUST make the following GitHub teams in the Azure GitHub organization admins on the GitHub repo of the module in question:

Bicep

@Azure/avm-core-team-technical-bicep = AVM Core Team
@Azure/bicep-admins = Bicep PG team

Note

These required GitHub teams are already associated to the BRM repository and have the required permissions.

Terraform

@Azure/avm-core-team-technical-terraform = AVM Core Team
@Azure/terraform-avm = Terraform PG

Important

Module owners MUST assign these GitHub teams as admins on the GitHub repo of the module in question.

For detailed steps, please follow this guidance.

See origin...

ID: SNFR10 - Category: Contribution/Support - MIT Licensing

A module MUST be published with the MIT License in the Azure GitHub organization.

See origin...

ID: SNFR11 - Category: Contribution/Support - Issues Response Times

A module owner MUST respond to logged issues as defined in the support statement. See Module Support for more information.

See origin...

ID: SNFR12 - Category: Contribution/Support - Versions Supported

Only the latest released version of a module MUST be supported.

This avoids AVM Module owners from having to maintain multiple major release versions.

See origin...

ID: SNFR23 - Category: Contribution/Support - GitHub Repo Labels

GitHub repositories where modules are held MUST use the below labels and SHOULD not use any additional labels:

➕ AVM Standard GitHub Labels

These labels are available in a CSV file from here

Name	Description	HEX
AZD 🧑‍💻	These modules are requested/used by the AZD team.	`E0BFFA`
Needs: Attention 👋	Reply has been added to issue, maintainer to review	`E99695`
Needs: Immediate Attention ‼️	Immediate attention of module owner / AVM team is needed	`FF0000`
Needs: Author Feedback 👂	Awaiting feedback from the issue/PR author	`F18A07`
Needs: External Changes ⚒️	When an issue/PR requires changes that are outside of the control of the module. e.g. to an RP.	`DE389D`
Needs: More Evidence ⚖	We are looking for more evidence to make a decision on this	`F64872`
Needs: Triage 🔍	Maintainers need to triage still	`FBCA04`
Needs: Module Owner 📣	In the AVM repository: this module needs an owner to develop or maintain it. In the BRM repository: the module owner needs to review a PR.	`FF0019`
Needs: Module Contributor 📣	This module needs secondary owner(s) or contributor(s) to develop or maintain it	`C95474`
Needs: Core Team 🧞‍♂️	This item needs the AVM Core Team to review it	`DB4503`
Status: Awaiting Release To Be Cut ✂️	This is fixed in the main branch but not in the latest release, will be fixed with next release cut	`800080`
Status: Do Not Merge ⛔	Do not merge PRs with this label attached as they are not ready or aligned to future direction etc.	`8B4513`
Status: External Contribution 🌍	This is being worked on by someone outside of the AVM module owners/contributors or AVM core team	`D8FA2C`
Status: Fixed ✅	Auto label applied when issue fixed by merged PR	`90EE90`
Status: Help Wanted 🆘	Extra attention is needed	`FF4500`
Status: In Triage 🔍	Picked up for triaging by an AVM core team member	`D4AF37`
Status: In PR 👉	This is when an issue is due to be fixed in an open PR	`EDEDED`
Status: Invalid ❌	This doesn't seem right	`E4E669`
Status: Long Term ⏳	We will do it, but will take a longer amount of time due to complexity/priorities	`B60205`
Status: No Recent Activity 💤	When an issue/PR has not been modified for X amount of days	`808080`
Status: Won't Fix 💔	This will not be worked on	`FFFFFF`
Status: Owners Identified 🤘	This module has its owners identified	`FBEF2A`
Status: Module Available 🟢	The module is published	`C8E6C9`
Status: Module Deprecated 🔴	This is a request to deprecate a module	`000000`
Status: Module Orphaned 🟡	The module has no owner and is therefore orphaned at this time	`F4A460`
Status: Ready For Repository Creation 📝	This module is approved and the owner is ready for the repository to be created (Terraform)	`136A41`
Status: Repository Created 📄	This module has had it's repository created and configured ready for owner contribution (Terraform)	`27AB03`
Status: Response Overdue 🚩	When an issue/PR has not been responded to for X amount of days	`850000`
Status: Looking For Assistance 🦆	This item is looking for anyone to help develop the code and submit a PR for resolution	`03FCC2`
Type: Bug 🐛	Something isn't working	`D73A4A`
Type: CI 🚀	This issue is related to the AVM CI	`74CFB0`
Type: Documentation 📄	Improvements or additions to documentation	`0075CA`
Type: Duplicate 🤲	This issue or pull request already exists	`CFD3D7`
Type: Feature Request ➕	New feature or request	`A2EEEF`
Type: Hygiene 🧹	things related to testing, issue triage etc.	`17016A`
Type: New Module Proposal 💡	A new module for AVM is being proposed	`ADD8E6`
Type: Question/Feedback 🙋‍♀️	Further information is requested or just some feedback	`CB6BA2`
Type: Security Bug 🔒	This is a security bug	`FFFF00`
Type: AVM 🅰️ ✌️ ⓜ️	This is an AVM related issue	`F0FFFF`
Language: Terraform 🌐	This is related to the Terraform IaC language	`7740B6`
Language: Bicep 💪	This is related to the Bicep IaC language	`1D73B3`
Class: Resource Module 📦	This is a resource module	`D3D3D3`
Class: Pattern Module 📦	This is a pattern module	`A9A9A9`
Class: Utility Module 📦	This is a utility module	`CAD1DE`
Class: Child Module 📦	This is a child module	`5E5186`

To help apply these to a module GitHub repository you can use the below PowerShell script:

➕ Set-AvmGitHubLabels.ps1

For most scenario this is the command you’ll need to call the below PowerShell script with, replacing the value for RepositoryName:

  Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -CreateCsvLabelExports $false -NoUserPrompts $true

```shell
# Linux / MacOs
# For Windows replace $PWD with your the local path or your repository
#
docker run -it -v $PWD:/repo -w /repo mcr.microsoft.com/powershell pwsh -Command '
    #Invoke-WebRequest -Uri "https://azure.github.io/Azure-Verified-Modules/scripts/Set-AvmGitHubLabels.ps1" -OutFile "Set-AvmGitHubLabels.ps1"
    $gh_version = "2.44.1"
    Invoke-WebRequest -Uri "https://github.com/cli/cli/releases/download/v2.44.1/gh_2.44.1_linux_amd64.tar.gz" -OutFile "gh_$($gh_version)_linux_amd64.tar.gz"
    apt-get update && apt-get install -y git
    tar -xzf "gh_$($gh_version)_linux_amd64.tar.gz"
    ls -lsa
    mv "gh_$($gh_version)_linux_amd64/bin/gh" /usr/local/bin/
    rm "gh_$($gh_version)_linux_amd64.tar.gz" && rm -rf "gh_$($gh_version)_linux_amd64"
    gh --version
    ls -lsa
    gh auth login
    $OrgProject = "Azure/terraform-azurerm-avm-res-kusto-cluster"
    gh auth status
    ./Set-AvmGitHubLabels.ps1 -RepositoryName $OrgProject -CreateCsvLabelExports $false -NoUserPrompts $true

  '
```

Full Script:

These Set-AvmGitHubLabels.ps1 can be downloaded from here.

  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "", Justification = "Coloured output required in this script")]
  
  <#
  .SYNOPSIS
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
  .DESCRIPTION
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
    By default, the script will remove all pre-existing labels and apply the AVM labels. However, this can be changed by using the -RemoveExistingLabels parameter and setting it to $false. The tool will also output the labels that exist in the repository before and after the script has run to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter.
  
    The AVM labels to be created are documented here: TBC
  
  .NOTES
    Please ensure you have specified the GitHub repositry correctly. The script will prompt you to confirm the repository name before proceeding.
  
  .COMPONENT
    You must have the GitHub CLI installed and be authenticated to a GitHub account with access to the repository you are applying the labels to before running this script.
  
  .LINK
    TBC
  
  .Parameter RepositoryName
    The name of the GitHub repository to apply the labels to.
  
  .Parameter RemoveExistingLabels
    If set to $true, the default value, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will not remove any pre-existing labels.
  
  .Parameter UpdateAndAddLabelsOnly
    If set to $true, the default value, the script will only update and add labels to the repository specified in -RepositoryName. If set to $false, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
  .Parameter OutputDirectory
    The directory to output the pre-existing and post-existing labels to in a CSV file. The default value is the current directory.
  
  .Parameter CreateCsvLabelExports
    If set to $true, the default value, the script will output the pre-existing and post-existing labels to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter. If set to $false, the script will not output the pre-existing and post-existing labels to a CSV file.
  
  .Parameter GitHubCliLimit
    The maximum number of labels to return from the GitHub CLI. The default value is 999.
  
  .Parameter LabelsToApplyCsvUri
    The URI to the CSV file containing the labels to apply to the GitHub repository. The default value is https://raw.githubusercontent.com/jtracey93/label-source/main/avm-github-labels.csv.
  
  .Parameter NoUserPrompts
    If set to $true, the default value, the script will not prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
    This is useful for running the script in automation workflows
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and remove all pre-existing labels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false -CreateCsvLabelExports $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name. Finally, use a custom CSV file hosted on the internet to create the labels from.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false -CreateCsvLabelExports $false -LabelsToApplyCsvUri "https://example.com/csv/avm-github-labels.csv"
  
  #>
  
  #Requires -PSEdition Core
  
  [CmdletBinding()]
  param (
    [Parameter(Mandatory = $true)]
    [string]$RepositoryName,
  
    [Parameter(Mandatory = $false)]
    [bool]$RemoveExistingLabels = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$UpdateAndAddLabelsOnly = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$CreateCsvLabelExports = $true,
  
    [Parameter(Mandatory = $false)]
    [string]$OutputDirectory = (Get-Location),
  
    [Parameter(Mandatory = $false)]
    [int]$GitHubCliLimit = 999,
  
    [Parameter(Mandatory = $false)]
    [string]$LabelsToApplyCsvUri = "https://azure.github.io/Azure-Verified-Modules/governance/avm-standard-github-labels.csv",
  
    [Parameter(Mandatory = $false)]
    [bool]$NoUserPrompts = $false
  )
  
  # Check if the GitHub CLI is installed
  $GitHubCliInstalled = Get-Command gh -ErrorAction SilentlyContinue
  if ($null -eq $GitHubCliInstalled) {
    throw "The GitHub CLI is not installed. Please install the GitHub CLI and try again."
  }
  Write-Host "The GitHub CLI is installed..." -ForegroundColor Green
  
  # Check if GitHub CLI is authenticated
  $GitHubCliAuthenticated = gh auth status
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubCliAuthenticated -ForegroundColor Red
    throw "Not authenticated to GitHub. Please authenticate to GitHub using the GitHub CLI, `gh auth login`, and try again."
  }
  Write-Host "Authenticated to GitHub..." -ForegroundColor Green
  
  # Check if GitHub repository name is valid
  $GitHubRepositoryNameValid = $RepositoryName -match "^[a-zA-Z0-9-]+/[a-zA-Z0-9-]+$"
  if ($false -eq $GitHubRepositoryNameValid) {
    throw "The GitHub repository name $RepositoryName is not valid. Please check the repository name and try again. The format must be <OrgName>/<RepoName>"
  }
  
  # List GitHub repository provided and check it exists
  $GitHubRepository = gh repo view $RepositoryName
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubRepository -ForegroundColor Red
    throw "The GitHub repository $RepositoryName does not exist. Please check the repository name and try again."
  }
  Write-Host "The GitHub repository $RepositoryName exists..." -ForegroundColor Green
  
  # PRE - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($RemoveExistingLabels -or $UpdateAndAddLabelsOnly) {
    Write-Host "Getting the current GitHub repository (pre) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels -and $CreateCsvLabelExports -eq $true) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Pre-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (pre) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # Remove all pre-existing labels if -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels
  if ($null -ne $GitHubRepositoryLabels) {
    $GitHubRepositoryLabelsJson = $GitHubRepositoryLabels | ConvertFrom-Json
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $false -and $UpdateAndAddLabelsOnly -eq $false) {
      $RemoveExistingLabelsConfirmation = Read-Host "Are you sure you want to remove all $($GitHubRepositoryLabelsJson.Count) pre-existing labels from $($RepositoryName)? (Y/N)"
      if ($RemoveExistingLabelsConfirmation -eq "Y") {
        Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
        $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
          Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
          gh label delete -R $RepositoryName $_.name --yes
        }
      }
    }
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $true -and $UpdateAndAddLabelsOnly -eq $false) {
      Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
        Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
        gh label delete -R $RepositoryName $_.name --yes
      }
    }
  }
  if ($null -eq $GitHubRepositoryLabels) {
    Write-Host "No pre-existing labels to remove or not selected to be removed from $RepositoryName..." -ForegroundColor Magenta
  }
  
  # Check LabelsToApplyCsvUri is valid and contains a CSV content
  Write-Host "Checking $LabelsToApplyCsvUri is valid..." -ForegroundColor Yellow
  $LabelsToApplyCsvUriValid = $LabelsToApplyCsvUri -match "^https?://"
  if ($false -eq $LabelsToApplyCsvUriValid) {
    throw "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is not valid. Please check the URI and try again. The format must be a valid URI."
  }
  Write-Host "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is valid..." -ForegroundColor Green
  
  # Create AVM lables from the AVM labels CSV file stored on the web using the convertfrom-csv cmdlet
  $avmLabelsCsv = Invoke-WebRequest -Uri $LabelsToApplyCsvUri | ConvertFrom-Csv
  
  # Check if the AVM labels CSV file contains the following columns: Name, Description, HEX
  $avmLabelsCsvColumns = $avmLabelsCsv | Get-Member -MemberType NoteProperty | Select-Object -ExpandProperty Name
  $avmLabelsCsvColumnsValid = $avmLabelsCsvColumns -contains "Name" -and $avmLabelsCsvColumns -contains "Description" -and $avmLabelsCsvColumns -contains "HEX"
  if ($false -eq $avmLabelsCsvColumnsValid) {
    throw "The labels CSV file does not contain the required columns: Name, Description, HEX. Please check the CSV file and try again. It contains the following columns: $avmLabelsCsvColumns"
  }
  Write-Host "The labels CSV file contains the required columns: Name, Description, HEX" -ForegroundColor Green
  
  # Create the AVM labels in the GitHub repository
  Write-Host "Creating/Updating the $($avmLabelsCsv.Count) AVM labels in $RepositoryName..." -ForegroundColor Yellow
  $avmLabelsCsv | ForEach-Object {
    if ($GitHubRepositoryLabelsJson.name -contains $_.name) {
      Write-Host "The label $($_.name) already exists in $RepositoryName. Updating the label to ensure description and color are consitent..." -ForegroundColor Magenta
      gh label create -R $RepositoryName "$($_.name)" -c $_.HEX -d $($_.Description) --force
    }
    else {
      Write-Host "The label $($_.name) does not exist in $RepositoryName. Creating label $($_.name) in $RepositoryName..." -ForegroundColor Cyan
      gh label create -R $RepositoryName "$($_.Name)" -c $_.HEX -d $($_.Description) --force
    }
  }
  
  # POST - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($CreateCsvLabelExports -eq $true) {
    Write-Host "Getting the current GitHub repository (post) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Post-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (post) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # If -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels check that only the avm labels exist in the repository
  if ($RemoveExistingLabels -eq $true -and ($RemoveExistingLabelsConfirmation -eq "Y" -or $NoUserPrompts -eq $true) -and $UpdateAndAddLabelsOnly -eq $false) {
    Write-Host "Checking that only the AVM labels exist in $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
    $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
      if ($avmLabelsCsv.Name -notcontains $_.name) {
        throw "The label $($_.name) exists in $RepositoryName but is not in the CSV file."
      }
    }
    Write-Host "Only the CSV labels exist in $RepositoryName..." -ForegroundColor Green
  }
  
  Write-Host "The CSV labels have been created/updated in $RepositoryName..." -ForegroundColor Green

See origin...

ID: PMNFR4 - Category: Hygiene - Missing Resource Module(s)

An item MUST be logged onto as an issue on the AVM Central Repo (Azure/Azure-Verified-Modules) if a Resource Module does not exist for resources deployed by the pattern module.

Exception

If the Resource Module adds no value, see Resource Module functional requirement ID: RMFR2.

See origin...

ID: BCPNFR15 - Category: Contribution/Support - AVM Module Issue template file

Module owners MUST add an entry to the AVM Module Issue template file in the BRM repository (here). When the module is deprecated, this entry MUST be removed from the file.

Note

Through this approach, the AVM core team will allow raising a bug or feature request for a module, only after the module gets merged to the BRM repository.

The module name entry MUST be added to the dropdown list with id module-name-dropdown as an option, in alphabetical order.

Important

Module owners MUST ensure that the module name is added in alphabetical order, to simplify selecting the right module name when raising an AVM module issue.

Example - AVM Module Issue template module name entry for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

- type: dropdown
  id: module-name-dropdown
  attributes:
    label: Module Name
    description: Which existing AVM module is this issue related to?
    options:
      ...
      - "avm/res/network/virtual-network"
      ...

Telemetry

The content below is listed based on the following tags

Category-TelemetryClass-ResourceLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SFR3	Deployment/Usage Telemetry	MUST	Owner	Initial
2	SFR4	Telemetry Enablement Flexibility	MUST	Owner	Initial
3	BCPFR4	Telemetry Enablement	MUST	OwnerContributor	BAU
4	BCPFR7	Cross-Referencing Modules	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SFR3 - Category: Telemetry - Deployment/Usage Telemetry

Important

These will also be provided as a comment on the module proposal, once accepted, from the AVM core team.

Modules MUST provide the capability to collect deployment/usage telemetry as detailed in Telemetry further.

Telemetry Information Notice

Note

The following information notice is automatically added at the bottom of the README.md file of the module when

Bicep: Using the utilities/tools/Set-AVMModule.ps1 utility
Terraform: Executing the make docs command with the note and header ## Data Collection being placed in the module’s _footer.md beforehand

### Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the [repository](https://aka.ms/avm/telemetry). There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at <https://go.microsoft.com/fwlink/?LinkID=824704>. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Bicep

Important

The value you need to use for your module is defined in the related module index. You can look it up on the index pages for Resource Modules, Pattern Modules and Utility Modules.

The ARM deployment name used for the telemetry MUST follow the pattern and MUST be no longer than 64 characters in length: 46d3xbcp.<res/ptn>.<(short) module name>.<version>.<uniqueness>

<res/ptn> == AVM Resource or Pattern Module
<(short) module name> == The AVM Module’s, possibly shortened, name including the resource provider and the resource type, without;
- The prefixes: avm-res-
- The prefixes: avm-ptn-
<version> == The AVM Module’s MAJOR.MINOR version (only) with . (periods) replaced with - (hyphens), to allow simpler splitting of the ARM deployment name
<uniqueness> == This section of the ARM deployment name is to be used to ensure uniqueness of the deployment name.
- This is to cater for the following scenarios:
  - The module is deployed multiple times to the same:
    - Location/Region
    - Scope (Tenant, Management Group,Subscription, Resource Group)

Note

An example deployment name for the AVM Virtual Machine Resource Module would be: 46d3xbcp.res.compute-virtualmachine.1-2-3.eum3

An example deployment name for a shortened module name would be: 46d3xbcp.res.desktopvirtualization-appgroup.1-2-3.eum3

Tip

Terraform: Terraform uses a telemetry provider, the configuration of which is the same for every module and is included in the template repo.

General: See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

Terraform

The modtm telemetry provider is included in all Terraform modules and is enabled by default through the main.telemetry.tf file being automatically distributed from the template repo.

The modtm provider MUST be listed under the required_providers section in the module’s terraform.tf file using the following entry. This is also validated by the linter.

terraform {
  required_providers {
    # .. other required providers as needed
    modtm = {
      source = "Azure/modtm"
      version = "~> 0.3"
    }
  }
}

See origin...

ID: SFR4 - Category: Telemetry - Telemetry Enablement Flexibility

The telemetry enablement MUST be on/enabled by default, however this MUST be able to be disabled by a module consumer by setting the below parameter/variable value to false:

Bicep: enableTelemetry
Terraform: enable_telemetry

Note

This general specification can be modified for some use-cases, that are language specific:

Bicep

For cross-references in resource modules, the spec BCPFR7 also applies.

Terraform

Currently, no further requirements apply.

See origin...

ID: BCPFR4 - Category: Composition - Telemetry Enablement

  @description('Optional. Location for all resources.')
  param location string = resourceGroup().location
  
  @description('Optional. Enable/Disable usage telemetry for module.')
  param enableTelemetry bool = true
  
  #disable-next-line no-deployments-resources
  resource avmTelemetry 'Microsoft.Resources/deployments@2024-03-01' = if (enableTelemetry) {
    name: take('46d3xbcp.res.compute-virtualmachine.${replace('-..--..-', '.', '-')}.${substring(uniqueString(deployment().name, location), 0, 4)}', 64)
    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'
          }
        }
      }
    }
  }

See origin...

ID: BCPFR7 - Cross-Referencing published Modules

Resource modules, that reference other modules (child, utility, or other resource modules), MUST disable the telemetry on the referenced modules.

Note

This only applies to resource modules that reference other modules, such as:

other resource modules
utility modules
child-modules qualifying for publishing, i.e. having a version.json file in their directory and exposing the enableTelemetry input parameter

For pattern modules, SFR4 still applies.

A variable named enableReferencedModulesTelemetry is created in the main.bicep file of the module, that cross-references other published modules, and set to false. This variable is used to set the enableTelemetry parameter of cross-referenced modules.

var enableReferencedModulesTelemetry = false

// local referencing
module virtualNetwork_subnets 'subnet/main.bicep' = [
  for (subnet, index) in (subnets ?? []): {
    name: '${uniqueString(deployment().name, location)}-subnet-${index}'
    params: {
      (...)
      enableTelemetry: enableReferencedModulesTelemetry
    }
  }
]

// published module reference
module virtualNetwork_subnet 'br/public:avm/res/network/virtual-network/subnet:0.1.0' = {
  name: '${uniqueString(deployment().name, location)}-subnet-${index}'
    params: {
      (...)
      enableTelemetry: enableReferencedModulesTelemetry
    }
}

Naming / Composition

The content below is listed based on the following tags

Category-Naming/CompositionClass-ResourceLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SFR1	Preview Services	MUST	Owner	BAU
2	SFR2	WAF Aligned	SHOULD	Owner	BAU
3	SFR5	Availability Zones	MUST	Owner	Initial
4	SFR6	Data Redundancy	MUST	Owner	Initial
5	SNFR25	Resource Naming	MUST	Owner	Initial
6	RMFR1	Single Resource Only	MUST	OwnerContributor	BAU
7	RMFR2	No Resource Wrapper Modules	MUST	Owner	Initial
8	RMFR3	Resource Groups	MUST	OwnerContributor	BAU
9	RMFR4	AVM Consistent Feature & Extension Resources Value Add	MUST	OwnerContributor	BAU
10	RMFR5	AVM Consistent Feature & Extension Resources Value Add Interfaces/Schemas	MUST	OwnerContributor	BAU
11	RMFR8	Dependency on child and other resources	MUST	OwnerContributor	BAU
12	RMFR9	End-of-life resource versions	SHOULD	OwnerContributor	BAU
13	RMNFR1	Module Naming	MUST	Owner	Initial
14	RMNFR3	RP Collaboration	SHOULD	Owner	BAU
15	BCPFR1	Cross-Referencing Modules	MAY	OwnerContributor	BAU
16	BCPFR2	Role Assignments Role Definition Mapping	MUST	OwnerContributor	BAU
17	BCPFR6	Cross-Referencing Child-Modules	MUST	OwnerContributor	BAU
18	BCPNFR19	User-defined types - Naming	MUST	OwnerContributor	BAU
19	BCPNFR5	Role Assignments Role Definition Mapping Limits	SHOULD	OwnerContributor	BAU
20	BCPNFR6	Role Assignments Role Definition Mapping Compulsory Roles	MUST	OwnerContributor	BAU
21	BCPNFR14	Versioning	MUST	OwnerContributor	BAU
22	BCPRMNFR3	Child resources structure	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SFR1 - Category: Composition - Preview Services

Modules MAY create/adopt public preview services and features at their discretion.

Preview API versions MAY be used when:

The resource/service/feature is GA but the only API version available for the GA resource/service/feature is a preview version
- For example, Diagnostic Settings (Microsoft.Insights/diagnosticSettings) the latest version of the API available with GA features, like Category Groups etc., is 2021-05-01-preview
- Otherwise the latest “non-preview” version of the API SHOULD be used

Preview services and features, SHOULD NOT be promoted and exposed, unless they are supported by the respective PG, and it’s documented publicly.

However, they MAY be exposed at the module owners discretion, but the following rules MUST be followed:

The description of each of the parameters/variables used for the preview service/feature MUST start with:
- “THIS IS A <PARAMETER/VARIABLE> USED FOR A PREVIEW SERVICE/FEATURE, MICROSOFT MAY NOT PROVIDE SUPPORT FOR THIS, PLEASE CHECK THE PRODUCT DOCS FOR CLARIFICATION”

See origin...

ID: SFR2 - Category: Composition - WAF Aligned

Well-Architected Framework (WAF)
Reliability Hub
Azure Proactive Resiliency Library (APRL)
- Only Product Group (PG) verified
Microsoft Defender for Cloud (MDFC)

They SHOULD NOT align to these recommendations when it requires an external dependency/resource to be deployed and configured and then associated to the resources in the module.

Alignment SHOULD prioritize best-practices and security over cost optimization, but MUST allow for these to be overridden by a module consumer easily, if desired.

Tip

Read the FAQ of What does AVM mean by “WAF Aligned”? for more detailed information and examples.

See origin...

ID: SFR5 - Category: Composition - Availability Zones

Modules that deploy zone-redundant resources MUST enable the spanning across as many zones as possible by default, typically all 3.

For both scenarios the modules MUST expose these configuration options via configurable parameters/variables.

Note

For information on the differences between zonal and zone-redundant services, see Availability zone service and regional support

See origin...

ID: SFR6 - Category: Composition - Data Redundancy

Note

For information on the data redundancy options in Azure, see Cross-region replication in Azure

See origin...

ID: SNFR25 - Category: Composition - Resource Naming

Module owners MUST also provide the ability for these default names, including the prefixes, to be overridden via a parameter/variable if the consumer wishes to.

Tip

If the resource does not have a documented abbreviation in Abbreviation examples for Azure resources, then the module owner is free to use a sensible prefix instead.

See origin...

ID: RMFR1 - Category: Composition - Single Resource Only

A resource module MUST only deploy a single instance of the primary resource, e.g., one virtual machine per instance.

Multiple instances of the module MUST be used to scale out.

See origin...

ID: RMFR2 - Category: Composition - No Resource Wrapper Modules

A resource module MUST add value by including additional features on top of the primary resource.

See origin...

ID: RMFR3 - Category: Composition - Resource Groups

A resource module MUST NOT create a Resource Group for resources that require them.

In the case that a Resource Group is required, a module MUST have an input (scope or variable):

In Bicep the targetScope MUST be set to resourceGroup or not specified (which means default to resourceGroup scope)
In Terraform the variable MUST be called resource_group_name

Scopes will be covered further in the respective language specific specifications.

See origin...

ID: RMFR4 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add

Resource modules support the following optional features/extension resources, as specified, if supported by the primary resource. The top-level variable/parameter names MUST be:

Optional Features/Extension Resources	Bicep Parameter Name	Terraform Variable Name	MUST/SHOULD
Diagnostic Settings	`diagnosticSettings`	`diagnostic_settings`	MUST
Role Assignments	`roleAssignments`	`role_assignments`	MUST
Resource Locks	`lock`	`lock`	MUST
Tags	`tags`	`tags`	MUST
Managed Identities (System / User Assigned)	`managedIdentities`	`managed_identities`	MUST
Private Endpoints	`privateEndpoints`	`private_endpoints`	MUST
Customer Managed Keys	`customerManagedKey`	`customer_managed_key`	MUST
Azure Monitor Alerts	`alerts`	`alerts`	SHOULD

Resource modules MUST NOT deploy required/dependent resources for the optional features/extension resources specified above. For example, for Diagnostic Settings the resource module MUST NOT deploy the Log Analytics Workspace, this is expected to be already in existence from the perspective of the resource module deployed via another method/module etc.

Note

Please note that the implementation of Customer Managed Keys from an ARM API perspective is different across various RPs that implement Customer Managed Keys in their service. For that reason you may see differences between modules on how Customer Managed Keys are handled and implemented, but functionality will be as expected.

Module owners MAY choose to utilize cross repo dependencies for these “add-on” resources, or MAY chose to implement the code directly in their own repo/module. So long as the implementation and outputs are as per the specifications requirements, then this is acceptable.

Tip

Make sure to checkout the language specific specifications for more info on this:

See origin...

ID: RMFR5 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add Interfaces/Schemas

Resource modules MUST implement a common interface, e.g. the input’s data structures and properties within them (objects/arrays/dictionaries/maps), for the optional features/extension resources:

See:

See origin...

ID: RMFR8 - Category: Composition - Dependency on child and other resources

A resource module MAY contain references to other resource modules, however MUST NOT contain references to non-AVM modules nor AVM pattern modules.

See BCPFR1 and TFFR1 for more information on this.

See origin...

ID: RMFR9 - Category: Composition - End-of-life resource versions

When a given version of an Azure resource used in a resource module reaches its end-of-life (EOL) and is no longer supported by Microsoft, the module owner SHOULD ensure that:

The module is aligned with these changes and only includes supported versions of the resource. This is typically achieved through the allowed values in the parameter that specifies the resource SKU or type.
The following notice is shown under the Notes section of the module’s readme.md. (If any related public announcement is available, it can also be linked to from the Notes section.):
“Certain versions of this Azure resource reached their end of life. The latest version of this module only includes supported versions of the resource. All unsupported versions have been removed from the related parameters.”
AND the related parameter’s description:
“Certain versions of this Azure resource reached their end of life. The latest version of this module only includes supported versions of the resource. All unsupported versions have been removed from this parameter.”

See origin...

ID: RMNFR1 - Category: Naming - Module Naming

Note

We will maintain a set of CSV files in the AVM Central Repo (Azure/Azure-Verified-Modules) with the correct singular names for all resource types to enable checks to utilize this list to ensure repos are named correctly. To see the formatted content of these CSV files with additional information, please visit the AVM Module Indexes page.

This will be updated quarterly, or ad-hoc as new RPs/ Resources are created and highlighted via a check failure.

Resource modules MUST follow the below naming conventions (all lower case):

Bicep Resource Module Naming

Naming convention: avm/res/<hyphenated resource provider name>/<hyphenated ARM resource type> (module name for registry)
Example: avm/res/compute/virtual-machine or avm/res/managed-identity/user-assigned-identity
Segments:
- res defines this is a resource module
- <hyphenated resource provider name> is the resource provider’s name after the Microsoft part, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Compute = compute, Microsoft.ManagedIdentity = managed-identity.
- <hyphenated ARM resource type> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Compute/virtualMachines = virtual-machine, BUT Microsoft.Network/trafficmanagerprofiles = trafficmanagerprofile - since trafficmanagerprofiles is all lower case as per the ARM API definition.

Bicep Child Module Naming

Naming convention: avm/res/<hyphenated resource provider name>/<hyphenated ARM resource type>/<hyphenated child resource type/<hyphenated grandchild resource type>/<hyphenated great grandchild resource type>/<etc.> (module name for registry)
Example: avm/res/network/virtual-network/subnet or avm/res/storage/storage-account/blob-service/container
Segments:
- res defines this is a resource module
- <hyphenated resource provider name> is the resource provider’s name after the Microsoft part, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network = network.
- <hyphenated ARM resource type> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network/virtualNetworks = virtual-network.
- <hyphenated child resource type (to be repeated for grandchildren, etc.)> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network/virtualNetworks/subnets = subnet or Microsoft.Storage/storageAccounts/blobServices/containers = blob-service/container.

Terraform Resource Module Naming

Naming convention:
- avm-res-<resource provider>-<ARM resource type> (module name for registry)
- terraform-<provider>-avm-res-<resource provider>-<ARM resource type> (GitHub repository name to meet registry naming requirements)
Example: avm-res-compute-virtualmachine or avm-res-managedidentity-userassignedidentity
Segments:
- <provider> is the logical abstraction of various APIs used by Terraform. In most cases, this is going to be azurerm or azuread for resource modules.
- res defines this is a resource module
- <resource provider> is the resource provider’s name after the Microsoft part, e.g., Microsoft.Compute = compute.
- <ARM resource type> is the singular version of the word after the resource provider, e.g., Microsoft.Compute/virtualMachines = virtualmachine

See origin...

ID: RMNFR3 - Category: Composition - RP Collaboration

Module owners (Microsoft FTEs) SHOULD reach out to the respective Resource Provider teams to build a partnership and collaboration on the modules creation, existence and long term maintenance.

Review this wiki page (Microsoft Internal) for more information.

See origin...

ID: BCPFR1 - Category: Composition - Cross-Referencing Modules

Module owners MAY cross-references other modules to build either Resource or Pattern modules.

The only exception to this rule are child modules as documented in BCPFR6.

Modules MUST NOT contain references to non-AVM modules.

See origin...

ID: BCPFR2 - Category: Composition - Role Assignments Role Definition Mapping

However, they MUST use only the official RBAC Role Definition name within the variable and nothing else.

To meet the requirements of BCPFR2, BCPNFR5 and BCPNFR6 you MUST use the below code sample in your AVM Modules to achieve this.

  @description('''Required. You can provide either the display name (note not all roles are supported, check module documentation) of the role definition, or its fully qualified ID in the following format: `/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11`.''')
  param roleDefinitionIdOrName string
  
  var builtInRbacRoleNames = {
    Owner: '/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635'
    Contributor: '/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c'
    Reader: '/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7'
    'Role Based Access Control Administrator (Preview)': '/providers/Microsoft.Authorization/roleDefinitions/f58310d9-a9f6-439a-9e8d-f62e7b41a168'
    'User Access Administrator': '/providers/Microsoft.Authorization/roleDefinitions/18d7d88d-d35e-4fb5-a5c3-7773c20a72d9'
    //Other RBAC Role Definitions Names & IDs can be added here as needed for your module
  }
  
  var roleDefinitionIdMappedResult = (contains(builtInRbacRoleNames, roleDefinitionIdOrName) ? builtInRbacRoleNames[roleDefinitionIdOrName] : roleDefinitionIdOrName)
  
  resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    //Other properties removed for ease of reading
    properties: {
      roleDefinitionId: roleDefinitionIdMappedResult
      //Other properties removed for ease of reading
    }
  }

See origin...

ID: BCPFR6 - Cross-Referencing Child-Modules

@description('Optional. The databases to create in the server')
param databases databaseType[]?

resource server 'Microsoft.Sql/servers@(...)' = { (...) }

module server_databases 'database/main.bicep' = [for (database, index) in (databases ?? []): {
  name: '${uniqueString(deployment().name, location)}-Sql-DB-${index}'
  params: {
    serverName: server.name
    (...)
  }
}]

See origin...

ID: BCPNFR19 - User-defined types - Naming

type subnet = { ... } // Wrong
type subnetType = { ... } // Correct
type subnetOutputType = { ... } // Correct, if used only for outputs

Since User-defined types (UDTs) MUST always be singular as per BCPNFR18, their naming should reflect this and also be singular.

type subnetsType = { ... } // Wrong
type subnetType = { ... } // Correct

See origin...

ID: BCPNFR5 - Category: Composition - Role Assignments Role Definition Mapping Limits

As per BCPFR2, module owners MAY define common RBAC Role Definition names and IDs within a variable to allow consumers to define a RBAC Role Definition by their name rather than their ID.

Therefore module owners SHOULD only map the most applicable and common RBAC Role Definition names for their module and SHOULD NOT exceed 15 RBAC Role Definitions in the variable.

Important

Tip

Review the Bicep Contribution Guide’s ‘RBAC Role Definition Name Mapping’ section for a code sample to achieve this requirement.

See origin...

ID: BCPNFR6 - Category: Composition - Role Assignments Role Definition Mapping Compulsory Roles

Module owners MUST include the following roles in the variable for RBAC Role Definition names:

Owner - ID: 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor - ID: b24988ac-6180-42a0-ab88-20f7382dd24c
Reader - ID: acdd72a7-3385-48ef-bd42-f606fba81ae7
User Access Administrator - ID: 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9
Role Based Access Control Administrator (Preview) - ID: f58310d9-a9f6-439a-9e8d-f62e7b41a168

Tip

Review the Bicep Contribution Guide’s ‘RBAC Role Definition Name Mapping’ section for a code sample to achieve this requirement.

See origin...

ID: BCPNFR14 - Category: Composition - Versioning

To meet SNFR17 and depending on the changes you make, you may need to bump the version in the version.json file.

  {
    "$schema": "https://aka.ms/bicep-registry-module-version-file-schema#",
    "version": "0.1",
    "pathFilters": [
        "./main.json"
    ]
  }

For example, the version value should be:

0.1 for new modules, so that they can be released as v0.1.0.
1.0 once the module owner signs off the module is stable enough for it’s first Major release of v1.0.0.
0.x for all feature updates between the first release v0.1.0 and the first Major release of v1.0.0.

See origin...

ID: BCPRMNFR3 - Implementing child resources

Child resource modules MUST be stored in a subfolder of their parent resource module and named after the child resource’s singular name (ref), so that the path to the child resource folder is consistent with the hierarchy of its resource type.
For example, Microsoft.Sql/servers may have dedicated child resources of type Microsoft.Sql/servers/databases. Hence, the SQL server database child module is stored in a database subfolder of the server parent folder.

sql
└─ server [module]
  └─ database [child-module/resource]

In this folder, we recommend to place the child resource-template alongside a ReadMe & compiled JSON (to be generated via the default Set-AVMModule utility) and optionally further nest additional folders for its child resources.

There are several reasons to structure a module in this way. For example:

It allows a separation of concerns where each module can focus on its own properties and logic, while delegating most of a child-resource’s logic to its separate child module
It’s consistent with the provider namespace structure and makes modules easier to understand not only because they’re more aligned with set structure, but also are aligned with one another
As each module is its own ‘deployment’, it reduces limitations around nested loops
Once the feature is enabled, it will enable module owners to publish set child-modules as separate modules to the public registry, allowing consumers to make use of them directly.

Note

In full transparency: The drawbacks of these additional deployments is an extended deployment period & a contribution to the 800 deployments limit. However, for AVM resource modules it was agreed that the advantages listed above outweigh these limitations.

Inputs / Outputs

The content below is listed based on the following tags

Category-Inputs/OutputsClass-ResourceLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR14	Data Types	SHOULD	OwnerContributor	BAU
2	SNFR22	Parameters/Variables for Resource IDs	MUST	OwnerContributor	BAU
3	SNFR26	Output - Parameters - Decorators	MUST	OwnerContributor	BAU
4	RMFR6	Parameter/Variable Naming	MUST	OwnerContributor	BAU
5	RMFR7	Minimum Required Outputs	MUST	OwnerContributor	BAU
6	RMNFR2	Parameter/Variable Naming	MUST	OwnerContributor	BAU
7	BCPNFR1	Complex data types - General	MUST	OwnerContributor	BAU
8	BCPNFR9	Inputs - Decorators	MUST	OwnerContributor	BAU
9	BCPNFR18	User-defined types - Specification	MUST	OwnerContributor	BAU
10	BCPNFR19	User-defined types - Naming	MUST	OwnerContributor	BAU
11	BCPNFR20	User-defined types - Export	MUST	OwnerContributor	BAU
12	BCPNFR21	User-defined types - Decorators	MUST	OwnerContributor	BAU
13	BCPNFR7	Parameter Requirement Types	MUST	OwnerContributor	BAU
14	BCPRMNFR2	User-defined types - AVM-Common-Types	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR14 - Category: Inputs - Data Types

A module SHOULD use either: simple data types. e.g., string, int, bool.

Complex data types (objects, arrays, maps) when the language-compliant schema is defined.

See origin...

ID: SNFR22 - Category: Inputs - Parameters/Variables for Resource IDs

workspaceId is not descriptive enough and is ambiguous as to which ID is required to be input.

See origin...

ID: SNFR26 - Output-Parameters - Decorators

Output parameters MUST implement:

Decorators in Bicep such as description & secure (if sensitive)
Arguments in Terraform such as description & sensitive (if sensitive)

Output parameters

@description('The resourceId of your resource.')
output sampleResourceId string = sampleResource.id

@description('The key of your resource.')
@secure()
output sampleResourceKey string = sampleResource.key

# Resource output
output "foo" {
  description = "MyResource foo attribute"
  value = azurerm_resource_myresource.foo
}

# Output of a sensitive attribute
output "bar" {
  description = "MyResource bar attribute"
  value     = azurerm_resource_myresource.bar
  sensitive = true
}

See origin...

ID: RMFR6 - Category: Inputs - Parameter/Variable Naming

Parameters/variables that pertain to the primary resource MUST NOT use the resource type in the name.

e.g., use sku, vs. virtualMachineSku/virtualmachine_sku

Another example for where RPs contain some of their name within a property, leave the property unchanged. E.g. Key Vault has a property called keySize, it is fine to leave as this and not remove the key part from the property/parameter name.

See origin...

ID: RMFR7 - Category: Outputs - Minimum Required Outputs

Module owners MUST output the following outputs as a minimum in their modules:

Output	Bicep Output Name	Terraform Output Name
Resource Name	`name`	`name`
Resource ID	`resourceId`	`resource_id`
System Assigned Managed Identity Principal ID (if supported by module)	`systemAssignedMIPrincipalId`	`system_assigned_mi_principal_id`

Tip

Module owners MAY also have to provide additional outputs depending on the IaC language, please check the language specific specs:

See origin...

ID: RMNFR2 - Category: Inputs - Parameter/Variable Naming

A resource module MUST use the following standard inputs:

name (no default)
location (if supported by the resource and not a global resource, then use Resource Group location, if resource supports Resource Groups, otherwise no default)

See origin...

ID: BCPNFR1 - Category: Inputs - Complex data types - General

Tip

User-Defined Types are GA in Bicep as of version v0.21.1, Resource-Derived Types are GA as of version v0.34.1, please ensure you have this version(s) installed as a minimum.

Resource-Derived Types and User-Defined Types allow intellisense support in supported IDEs (e.g. Visual Studio Code) for complex input parameters using objects and array of objects.

v0.x Exemption

While we allow the release of major versions, starting with v1.0.0, retrofitting Resource-Derived Types and User-Defined Types for all modules will take a considerable amount of time.

See origin...

ID: BCPNFR9 - Inputs - Decorators

Similar to BCPNFR21, input parameters MUST implement decorators such as description & secure (if sensitive).

@description('Optional. The threshold of your resource.')
@minValue(1)
@maxValue(10)
param threshold: int?
@description('Required. The SKU of your resource.')
@allowed([
'Basic'
'Premium'
'Standard'
])
param sku string

See origin...

ID: BCPNFR18 - User-defined types - Specification

User-defined types (UDTs) MUST always be singular and non-nullable. The configuration of either should instead be done directly at the parameter or output that uses the type.

For example, instead of

param subnets subnetsType
type subnetsType = { ... }[]?

the type should be defined like

param subnets subnetType[]?
type subnetType = { ... }

See origin...

ID: BCPNFR19 - User-defined types - Naming

type subnet = { ... } // Wrong
type subnetType = { ... } // Correct
type subnetOutputType = { ... } // Correct, if used only for outputs

Since User-defined types (UDTs) MUST always be singular as per BCPNFR18, their naming should reflect this and also be singular.

type subnetsType = { ... } // Wrong
type subnetType = { ... } // Correct

See origin...

ID: BCPNFR20 - User-defined types - Export

User-defined types (UDTs) SHOULD always be exported via the @export() annotation in every template they’re implemented in.

@export()
type subnetType = { ... }

See origin...

ID: BCPNFR21 - User-defined types - Decorators

Similar to BCPNFR9, User-defined types (UDTs) MUST implement decorators such as description & secure (if sensitive). This is true for every property of the UDT, as well as the UDT itself.

@description('My type''s description.')
type myType = {
  @description('Optional. The threshold of your resource.')
  @minValue(1)
  @maxValue(10)
  threshold: int?

  @description('Required. The SKU of your resource.')
  sku: ('Basic' | 'Premium' | 'Standard')
}

See origin...

ID: BCPNFR7 - Category: Inputs - Parameter Requirement Types

Parameter Requirement Type	Definition	Example Description Decorator
Required	The parameter value must be provided. The parameter does not have a default value and hence the module expects and requires an input.	`@description('Required. <PARAMETER DESCRIPTION HERE...>')`
Conditional	The parameter value can be optional or required based on a condition, mostly based on the value provided to other parameters. Should contain a sentence starting with ‘Required if (…).’ to explain the condition.	`@description('Conditional. <PARAMETER DESCRIPTION HERE...>')`
Optional	The parameter value is not mandatory. The module provides a default value for the parameter.	`@description('Optional. <PARAMETER DESCRIPTION HERE...>')`
Generated	The parameter value is generated within the module and should not be specified as input in most cases. A common example of this is the `utcNow()` function that is only supported as the input for a parameter value, and not inside a variable.	`@description('Generated. <PARAMETER DESCRIPTION HERE...>')`

See origin...

ID: BCPRMNFR2 - User-defined types - AVM-Common-Types

When implementing any of the shared or Bicep-specific AVM interface variants you MUST import their User-defined type (UDT) via the published AVM-Common-Types module.

When doing so, each type MUST be imported separately, right above the parameter or output that uses it.

import { roleAssignmentType } from 'br/public:avm/utl/types/avm-common-types:*.*.*'
@description('Optional. Array of role assignments to create.')
param roleAssignments roleAssignmentType[]?
import { diagnosticSettingFullType } from 'br/public:avm/utl/types/avm-common-types:*.*.*'
@description('Optional. The diagnostic settings of the service.')
param diagnosticSettings diagnosticSettingFullType[]?

Importing them individually as opposed to one common block has several benefits such as

Individual versioning of types
If you must update the version for one type, you’re not exposed to unexpected changes to other types

Important

The import (...) block MUST not be added in between a parameter’s definition and its metadata. Doing so breaks the metadata’s binding to the parameter in question.

Finally, you should check for version updates regularly to ensure the resource module stays consistent with the specs. If the used AVM-Common-Types runs stale, the CI may eventually fail the module’s static tests.

Testing

The content below is listed based on the following tags

Category-TestingClass-ResourceLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR1	Prescribed Tests	MUST	OwnerContributor	BAU
2	SNFR2	E2E Testing	MUST	OwnerContributor	BAU
3	SNFR3	AVM Compliance Tests	MUST	OwnerContributor	Initial
4	SNFR4	Unit Tests	SHOULD	OwnerContributor	BAU
5	SNFR5	Upgrade Tests	SHOULD	OwnerContributor	BAU
6	SNFR6	Static Analysis/Linting Tests	MUST	OwnerContributor	BAU
7	SNFR7	Idempotency Tests	MUST	OwnerContributor	BAU
8	SNFR24	Testing Child, Extension & Interface Resources	MUST	OwnerContributor	BAU
9	BCPNFR10	Test Bicep File Naming	MUST	OwnerContributor	BAU
10	BCPNFR11	Test Tooling	MUST	OwnerContributor	BAU
11	BCPNFR12	Deployment Test Naming	MUST	OwnerContributor	BAU
12	BCPNFR13	Test file metadata	MUST	OwnerContributor	BAU
13	BCPNFR16	Post-deployment tests	MUST	OwnerContributor	BAU
14	BCPRMNFR1	Expected Test Directories	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR1 - Category: Testing - Prescribed Tests

Modules MUST use the prescribed tooling and testing frameworks defined in the language specific specs.

See origin...

ID: SNFR2 - Category: Testing - E2E Testing

Each test MUST run and complete without user inputs successfully, for automation purposes.

Each test MUST also destroy/clean-up its resources and test dependencies following a run.

Tip

To see a directory and file structure for a module, see the language specific contribution guide.

Resources/Dependencies Required for E2E Tests

It is likely that to complete E2E tests, a number of resources will be required as dependencies to enable the tests to pass successfully. Some examples:

When testing the Diagnostic Settings interface for a Resource Module, you will need an existing Log Analytics Workspace to be able to send the logs to as a destination.
When testing the Private Endpoints interface for a Resource Module, you will need an existing Virtual Network, Subnet and Private DNS Zone to be able to complete the Private Endpoint deployment and configuration.

Module owners MUST:

Create the required resources that their module depends upon in the test file/directory
- They MUST either use:
  - Simple/native resource declarations/definitions in their respective IaC language,
    OR
  - Another already published AVM Module that MUST be pinned to a specific published version.
    - They MUST NOT use any local directory path references or local copies of AVM modules in their own modules test directory.

➕ Terraform & Bicep Log Analytics Workspace examples using simple/native declarations for use in E2E tests

Terraform

resource "azurerm_resource_group" "example" {
  name     = "rsg-test-001"
  location = "West Europe"
}

resource "azurerm_log_analytics_workspace" "example" {
  name                = "law-test-001"
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  sku                 = "PerGB2018"
  retention_in_days   = 30
}

Bicep

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2021-12-01-preview' = {
  name: 'law-test-001'
  location: resourceGroup().location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
    retentionInDays: 30
  }
}

Skipping Deployments (SHOULD NOT)

Note

A skipped test case is still added to the ‘Usage Examples’ section of the module’s readme and should be manually validated in regular intervals.

Details for use in E2E tests

You MUST add a note to the tests metadata description, which explains the excemption.

Sample filecontent:

The test is skipped, as only one instance of this service can be deployed to a subscription.

Note

For resource modules, the ‘defaults’ and ‘waf-aligned’ tests can’t be skipped.

The deployment of a test can be skipped by adding a .e2eignore file into a test folder (e.g. /examples/<testname>).

See origin...

ID: SNFR3 - Category: Testing - AVM Compliance Tests

Modules MUST pass all tests that ensure compliance to AVM specifications. These tests MUST pass before a module version can be published.

Important

Please note these are still under development at this time and will be published and available soon for module owners.

See origin...

ID: SNFR4 - Category: Testing - Unit Tests

Unit Tests test specific module functionality, without deploying resources. Used on more complex modules. In Bicep and Terraform these live in tests/unit.

See origin...

ID: SNFR5 - Category: Testing - Upgrade Tests

Modules SHOULD implement upgrade testing to ensure new features are implemented in a non-breaking fashion on non-major releases.

See origin...

ID: SNFR6 - Category: Testing - Static Analysis/Linting Tests

Modules MUST use static analysis, e.g., linting, security scanning (PSRule, tflint, etc.). These tests MUST pass before a module version can be published.

There may be differences between languages in linting rules standards, but the AVM core team will try to close these and bring them into alignment over time.

See origin...

ID: SNFR7 - Category: Testing - Idempotency Tests

Modules MUST implement idempotency end-to-end (deployment) testing. E.g. deploying the module twice over the top of itself.

Modules SHOULD pass the idempotency test, as we are aware that there are some exceptions where they may fail as a false-positive or legitimate cases where a resource cannot be idempotent.

For example, Virtual Machine Image names must be unique on each resource creation/update.

See origin...

ID: SNFR24 - Category: Testing - Testing Child, Extension & Interface Resources

These MAY be tested in a separate E2E test and DO NOT have to be tested in each E2E test.

See origin...

ID: BCPNFR10 - Category: Testing - Test Bicep File Naming

Module owners MUST name their test .bicep files in the /tests/e2e/<defaults/waf-aligned/max/etc.> directories: main.test.bicep as the test framework (CI) relies upon this name.

See origin...

ID: BCPNFR11 - Category: Testing - Test Tooling

Module owners MUST use the below tooling for unit/linting/static/security analysis tests. These are also used in the AVM Compliance Tests.

PSRule for Azure
Pester
- Some tests are provided as part of the AVM Compliance Tests, but you are free to also use Pester for your own tests.

See origin...

ID: BCPNFR12 - Category: Testing - Deployment Test Naming

Module owners MUST invoke the module in their test using the syntax:

module testDeployment '../../../main.bicep' =

Example 1: Working example with a single deployment

module testDeployment '../../../main.bicep' = {
  scope: resourceGroup
  name: '${uniqueString(deployment().name, location)}-test-${serviceShort}'
  params: {
    (...)
  }
}

Example 2: Working example using a deployment loop

@batchSize(1)
module testDeployment '../../main.bicep' = [for iteration in [ 'init', 'idem' ]: {
  scope: resourceGroup
  name: '${uniqueString(deployment().name, location)}-test-${serviceShort}-${iteration}'
  params: {
    (...)
  }
}]

The syntax is used by the ReadMe-generating utility to identify, pull & format usage examples.

See origin...

ID: BCPNFR13 - Category: Testing - Test file metadata

For example:

metadata name = 'Using Customer-Managed-Keys with System-Assigned identity'
metadata description = 'This instance deploys the module using Customer-Managed-Keys using a System-Assigned Identity. This required the service to be deployed twice, once as a pre-requisite to create the System-Assigned Identity, and once to use it for accessing the Customer-Managed-Key secret.'

would lead to a header in the module’s readme.md file along the lines of

### Example 1: _Using Customer-Managed-Keys with System-Assigned identity_

This instance deploys the module using Customer-Managed-Keys using a System-Assigned Identity. This required the service to be deployed twice, once as a pre-requisite to create the System-Assigned Identity, and once to use it for accessing the Customer-Managed-Key secret.

See origin...

ID: BCPNFR16 - Category: Testing - Post-deployment tests

For each test case in the e2e folder, you can optionally add post-deployment Pester tests that are executed once the corresponding deployment completed and before the removal logic kicks in.

To leverage the feature you MUST:

Use Pester as a test framework in each test file
Name the file with the suffix "*.tests.ps1"
Place each test file the e2e test’s folder or any subfolder (e.g., e2e/max/myTest.tests.ps1 or e2e/max/tests/myTest.tests.ps1)

Implement an input parameter TestInputData in the following way:

param (
    [Parameter(Mandatory = $false)]
    [hashtable] $TestInputData = @{}
)

Through this parameter you can make use of every output the main.test.bicep file returns, as well as the path to the test template file in case you want to extract data from it directly.

For example, with an output such as output resourceId string = testDeployment[1].outputs.resourceId defined in the main.test.bicep file, the $TestInputData would look like:

$TestInputData = @{
  DeploymentOutputs    = @{
    resourceId = @{
      Type  = "String"
      Value = "/subscriptions/***/resourceGroups/dep-***-keyvault.vaults-kvvpe-rg/providers/Microsoft.KeyVault/vaults/***kvvpe001"
    }
  }
  ModuleTestFolderPath = "/home/runner/work/bicep-registry-modules/bicep-registry-modules/avm/res/key-vault/vault/tests/e2e/private-endpoint"
}

A full test file may look like:

➕ Pester post-deployment test file example

param (
    [Parameter(Mandatory = $false)]
    [hashtable] $TestInputData = @{}
)

Describe 'Validate private endpoint deployment' {

    Context 'Validate sucessful deployment' {

        It "Private endpoints should be deployed in resource group" {

            $keyVaultResourceId = $TestInputData.DeploymentOutputs.resourceId.Value
            $testResourceGroup = ($keyVaultResourceId -split '\/')[4]
            $deployedPrivateEndpoints = Get-AzPrivateEndpoint -ResourceGroupName $testResourceGroup
            $deployedPrivateEndpoints.Count | Should -BeGreaterThan 0
        }
    }
}

See origin...

ID: BCPRMNFR1 - Category: Testing - Expected Test Directories

Module owners MUST create the defaults, waf-aligned folders within their /tests/e2e/ directory in their resource module source code and SHOULD create a max folder also. Module owners CAN create additional folders as required. Each folder will be used as described for various test cases.

Note

If a module can deploy varying styles of the same resource, e.g., VMs can be Linux or Windows, each style should be tested as both defaults and waf-aligned. Each must then be used as suffixes in the directory name to denote the style, e.g., for a VM we would expect to see:

/tests/e2e/linux.defaults/main.test.bicep
/tests/e2e/linux.waf-aligned/main.test.bicep
/tests/e2e/windows.defaults/main.test.bicep
/tests/e2e/windows.waf-aligned/main.test.bicep

Defaults tests (MUST)

The defaults folder contains a test instance that deploys the module with the minimum set of required parameters.

This includes input parameters of type Required plus input parameters of type Conditional marked as required for WAF compliance.

This instance has heavy reliance on the default values for other input parameters. Parameters of type Optional SHOULD NOT be used.

WAF aligned tests (MUST)

The waf-aligned folder contains a test instance that deploys the module in alignment with the best-practices of the Azure Well-Architected Framework.

This includes input parameters of type Required, parameters of type Conditional marked as required for WAF compliance, and parameters of type Optional useful for WAF compliance.

Parameters and dependencies which are not needed for WAF compliance, SHOULD NOT be included.

Max tests (SHOULD)

The max folder contains a test instance that deploys the module using a large parameter set, enabling most of the modules’ features.

The purpose of this instance is primarily parameter validation and not necessarily to serve as a real example scenario. Ideally, all features, extension resources and child resources should be enabled in this test, unless not possible due to conflicts, e.g., in case parameters are mutually exclusive.

Note

Please note that this test is not mandatory to have, but recommended for bulk parameter validation. It can be skipped in case the module parameter validation is covered already by additional, more scenario-specific tests.

Additional tests (CAN)

Additional folders CAN be created by module owners as required.

For example, to validate parameters not covered by the max test due to conflicts, or to provide a real example scenario for a specific use case.

Documentation

The content below is listed based on the following tags

Category-DocumentationClass-ResourceLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR15	Automatic Documentation Generation	MUST	OwnerContributor	BAU
2	SNFR16	Examples/E2E	MUST	OwnerContributor	BAU
3	BCPNFR2	Module Documentation Generation	MUST	OwnerContributor	BAU
4	BCPNFR3	Usage Example formats	MUST	OwnerContributor	BAU
5	BCPNFR4	Parameter Input Examples	MAY	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR15 - Category: Documentation - Automatic Documentation Generation

README documentation MUST be automatically/programmatically generated. MUST include the sections as defined in the language specific requirements BCPNFR2, TFNFR2.

See origin...

ID: SNFR16 - Category: Documentation - Examples/E2E

An examples/e2e directory MUST exist to provide named scenarios for module deployment.

See origin...

ID: BCPNFR2 - Category: Documentation - Module Documentation Generation

Note

This script/tool is currently being developed by the AVM team and will be made available very soon.

Bicep modules documentation MUST be automatically generated via the provided script/tooling from the AVM team, providing the following headings:

Title
Description
Navigation
Resource Types
Usage Examples
Parameters
Outputs
Cross-referenced modules

See origin...

ID: BCPNFR3 - Category: Documentation - Usage Example formats

Usage examples for Bicep modules MUST be provided in the following formats:

Bicep file (orchestration module style) - .bicep

module <resourceName> 'br/public:avm/[res|ptn|utl]/<publishedModuleName>:>version<' = {
  name: '${uniqueString(deployment().name, location)}-test-<uniqueIdentifier>'
  params: { (...) }
}

JSON / ARM Template Parameter Files - .json

{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": { (...) }
}

Note

Bicep Parameter Files (.bicepparam) are being reviewed and considered by the AVM team for the usability and features at this time and will likely be added in the future.

See origin...

ID: BCPNFR4 - Category: Documentation - Parameter Input Examples

Bicep modules MAY provide parameter input examples for parameters using the metadata.example property via the @metadata() decorator.

Example:

@metadata({
  example: 'uksouth'
})
@description('Optional. Location for all resources.')
param location string = resourceGroup().location

@metadata({
  example: '''
  {
    keyName: 'myKey'
    keyVaultResourceId: '/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/my-rg/providers/Microsoft.KeyVault/vaults/myvault'
    keyVersion: '6d143c1a0a6a453daffec4001e357de0'
    userAssignedIdentityResourceId '/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/my-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity'
  }
  '''
})
@description('Optional. The customer managed key definition.')
param customerManagedKey customerManagedKeyType

Release / Publishing

The content below is listed based on the following tags

Category-Release/PublishingClass-ResourceLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR17	Semantic Versioning	MUST	OwnerContributor	BAU
2	SNFR18	Breaking Changes	SHOULD	OwnerContributor	BAU
3	SNFR19	Registries Targeted	MUST	OwnerContributor	BAU
4	SNFR21	Cross Language Collaboration	SHOULD	OwnerContributor	BAU
5	BCPNFR22	Bicep Module Changelog	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR17 - Category: Release - Semantic Versioning

Important

See the Bicep Contribution Guide for more information.

Modules MUST use semantic versioning (aka semver) for their versions and releases in accordance with: Semantic Versioning 2.0.0

For example all modules should be released using a semantic version that matches this pattern: X.Y.Z

X == Major Version
Y == Minor Version
Z == Patch Version

Module versioning before first Major version release `1.0.0`

Initially modules MUST be released as version 0.1.0 and incremented via Minor and Patch versions only until the AVM Core Team are confident the AVM specifications are mature enough and appropriate CI test coverage is in place, plus the module owner is happy the module has been “road tested” and is now stable enough for its first Major release of version 1.0.0.
Note
Releasing as version 0.1.0 initially and only incrementing Minor and Patch versions allows the module owner to make breaking changes more easily and frequently as it’s still not an official Major/Stable release. 👍
Until first Major version 1.0.0 is released, given a version number X.Y.Z:
- X Major version MUST NOT be bumped.
- Y Minor version MUST be bumped when introducing breaking changes (which would normally bump Major after 1.0.0 release) or feature updates (same as it will be after 1.0.0 release).
- Z Patch version MUST be bumped when introducing non-breaking, backward compatible bug fixes (same as it will be after 1.0.0 release).

See origin...

ID: SNFR18 - Category: Release - Breaking Changes

A module SHOULD avoid breaking changes, e.g., deprecating inputs vs. removing. If you need to implement changes that cause a breaking change, the major version should be increased.

Info

Tip

See the language specific examples to find out how you can deal with deprecations in AVM modules.

Bicep

See origin...

ID: SNFR19 - Category: Publishing - Registries Targeted

Modules MUST be published to their respective language public registries.

Bicep = Bicep Public Module Registry
- Within the avm directory
Terraform = HashiCorp Terraform Registry

Tip

See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

See origin...

ID: SNFR21 - Category: Publishing - Cross Language Collaboration

See origin...

ID: BCPNFR22 - Category: Publishing - Changelog

# Changelog

The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/<ptn|res|utl>/<namespace/modulename[/submodulePath]>/CHANGELOG.md).

For each new version, an entry MUST be created above all existing versions in the CHANGELOG.md file of the module.

## <version>

### Changes

- This changed
- And this also

### Breaking Changes

- None

Each version’s entry:

MUST contain two sections: Changes and Breaking Changes. At least one of them must have a meaningful entry and sections must not be left empty. A - None may be added as content for a section.
MUST exist only once.
All versions appear in descending order, which puts the most recent changes at the top.

What SHOULD be listed in the (Breaking) Changes section:

Relevant changes for the module
Changes in tests do not need to be added

Note

The versioning is following the SNFR17 - Semantic Versioning spec.

Example content of the CHANGELOG.md

# Changelog

The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/aad/domain-service/CHANGELOG.md).

## 0.2.1

### Changes

- Updated the referenced AVM common types

### Breaking Changes

- None

## 0.2.0

### Changes

- Implemented the minCPU parameter
- Updated the referenced VirtualNetwork module
- Updated the referenced AVM common types

### Breaking Changes

- The minCPU parameter is mandatory

## 0.1.0

### Changes

- Initial Release

### Breaking Changes

- None

Each bullet point should start with a capital letter.

Manual Editing

It is possible to modify the changelog content any time, e.g., to add missing versions, which will not create a new release of the module itself. Please note the following requirements in all cases:

All versions in the file, need to be valid and available as published version
Every version needs the two sections ## Changes and ## Breaking Changes with content

Note

Code Style

The content below is listed based on the following tags

Category-CodeStyleClass-ResourceLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	BCPNFR8	Code Styling - lower camelCasing	SHOULD	OwnerContributor	BAU
2	BCPNFR17	Code Styling - Type casting	SHOULD	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: BCPNFR8 - Category: Composition - Code Styling - lower camelCasing

Module owners SHOULD use lower camelCasing for naming the following:

Parameters
Variables
Outputs
User Defined Types
Resources (symbolic names)
Modules (symbolic names)

For example: camelCasingExample (lowercase first word (entirely), with capital of first letter of all other words and rest of word in lowercase)

See origin...

ID: BCPNFR17 - Category: Composition - Code Styling - Type casting

For reference, please refer to the following examples:

Boolean as String

@allowed([
  'false'
  'true'
])
param myParameterValue string = 'false'

resource myResource '(...)' = {
  (...)
  properties: {
    myParameter: myParameterValue
  }
}

param myParameterValue string = false

resource myResource '(...)' = {
  (...)
  properties: {
    myParameter: string(myParameterValue)
  }
}

Integer Array as String Array

@allowed([
  '1'
  '2'
  '3'
])
param zones array

resource myResource '(...)' = {
  (...)
  properties: {
    zones: zones
  }
}

@allowed([
  1
  2
  3
])
param zones int[]

resource myResource '(...)' = {
  (...)
  properties: {
    zones: map(zones, zone => string(zone))
  }
}

Bicep Utility Module Specifications

Contribution / Support

No specifications available for this criteria

Category-Contribution/SupportClass-UtilityLanguage-Bicep

Telemetry

No specifications available for this criteria

Category-TelemetryClass-UtilityLanguage-Bicep

Naming / Composition

The content below is listed based on the following tags

Category-Naming/CompositionClass-UtilityLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	BCPNFR14	Versioning	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: BCPNFR14 - Category: Composition - Versioning

To meet SNFR17 and depending on the changes you make, you may need to bump the version in the version.json file.

  {
    "$schema": "https://aka.ms/bicep-registry-module-version-file-schema#",
    "version": "0.1",
    "pathFilters": [
        "./main.json"
    ]
  }

For example, the version value should be:

0.1 for new modules, so that they can be released as v0.1.0.
1.0 once the module owner signs off the module is stable enough for it’s first Major release of v1.0.0.
0.x for all feature updates between the first release v0.1.0 and the first Major release of v1.0.0.

Inputs / Outputs

No specifications available for this criteria

Category-Inputs/OutputsClass-UtilityLanguage-Bicep

Testing

No specifications available for this criteria

Category-TestingClass-UtilityLanguage-Bicep

Documentation

No specifications available for this criteria

Category-DocumentationClass-UtilityLanguage-Bicep

Release / Publishing

The content below is listed based on the following tags

Category-Release/PublishingClass-UtilityLanguage-Bicep

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR17	Semantic Versioning	MUST	OwnerContributor	BAU
2	BCPNFR22	Bicep Module Changelog	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR17 - Category: Release - Semantic Versioning

Important

See the Bicep Contribution Guide for more information.

Modules MUST use semantic versioning (aka semver) for their versions and releases in accordance with: Semantic Versioning 2.0.0

For example all modules should be released using a semantic version that matches this pattern: X.Y.Z

X == Major Version
Y == Minor Version
Z == Patch Version

Module versioning before first Major version release `1.0.0`

Initially modules MUST be released as version 0.1.0 and incremented via Minor and Patch versions only until the AVM Core Team are confident the AVM specifications are mature enough and appropriate CI test coverage is in place, plus the module owner is happy the module has been “road tested” and is now stable enough for its first Major release of version 1.0.0.
Note
Releasing as version 0.1.0 initially and only incrementing Minor and Patch versions allows the module owner to make breaking changes more easily and frequently as it’s still not an official Major/Stable release. 👍
Until first Major version 1.0.0 is released, given a version number X.Y.Z:
- X Major version MUST NOT be bumped.
- Y Minor version MUST be bumped when introducing breaking changes (which would normally bump Major after 1.0.0 release) or feature updates (same as it will be after 1.0.0 release).
- Z Patch version MUST be bumped when introducing non-breaking, backward compatible bug fixes (same as it will be after 1.0.0 release).

See origin...

ID: BCPNFR22 - Category: Publishing - Changelog

# Changelog

The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/<ptn|res|utl>/<namespace/modulename[/submodulePath]>/CHANGELOG.md).

For each new version, an entry MUST be created above all existing versions in the CHANGELOG.md file of the module.

## <version>

### Changes

- This changed
- And this also

### Breaking Changes

- None

Each version’s entry:

MUST contain two sections: Changes and Breaking Changes. At least one of them must have a meaningful entry and sections must not be left empty. A - None may be added as content for a section.
MUST exist only once.
All versions appear in descending order, which puts the most recent changes at the top.

What SHOULD be listed in the (Breaking) Changes section:

Relevant changes for the module
Changes in tests do not need to be added

Note

The versioning is following the SNFR17 - Semantic Versioning spec.

Example content of the CHANGELOG.md

# Changelog

The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/aad/domain-service/CHANGELOG.md).

## 0.2.1

### Changes

- Updated the referenced AVM common types

### Breaking Changes

- None

## 0.2.0

### Changes

- Implemented the minCPU parameter
- Updated the referenced VirtualNetwork module
- Updated the referenced AVM common types

### Breaking Changes

- The minCPU parameter is mandatory

## 0.1.0

### Changes

- Initial Release

### Breaking Changes

- None

Each bullet point should start with a capital letter.

Manual Editing

It is possible to modify the changelog content any time, e.g., to add missing versions, which will not create a new release of the module itself. Please note the following requirements in all cases:

All versions in the file, need to be valid and available as published version
Every version needs the two sections ## Changes and ## Breaking Changes with content

Note

Code Style

No specifications available for this criteria

Category-CodeStyleClass-UtilityLanguage-Bicep

Terraform Specifications

Specifications by Category and Module Classification

Category	Resource	Pattern	Utility
Contribution/Support	9	8	0
Telemetry	2	2	0
Naming/Composition	17	12	1
CodeStyle	29	29	0
Inputs/Outputs	8	6	0
Testing	10	10	0
Documentation	4	4	0
Release/Publishing	4	4	1
Summary	83	75	2

How to propose changes to the specifications?

Important

Any updates to existing or new specifications for Terraform must be submitted as a draft for review by Azure Terraform PG/Engineering(@Azure/terraform-avm) and AVM core team(@Azure/avm-core-team).

Important

Provider Versatility: Users have the autonomy to choose between AzureRM, AzAPI, or a combination of both, tailored to the specific complexity of module requirements.

What changed recently?

See what specifications changed in the last 30 days...

#	ID	Last Modified (UTC)	Git History	Last Commit
1	SNFR3	2025-06-27 14:49:42	All Commits	db02f74
2	SNFR26	2025-06-17 14:13:16	All Commits	f6e12b4
3	SFR3	2025-06-13 21:30:28	All Commits	7d51e6c

Terraform Interfaces

This chapter details the interfaces/schemas for the AVM Resource Modules features/extension resources as referenced in RMFR4 and RMFR5.

Diagnostic Settings

Important

  variable "diagnostic_settings" {
    type = map(object({
      name                                     = optional(string, null)
      log_categories                           = optional(set(string), [])
      log_groups                               = optional(set(string), ["allLogs"])
      metric_categories                        = optional(set(string), ["AllMetrics"])
      log_analytics_destination_type           = optional(string, "Dedicated")
      workspace_resource_id                    = optional(string, null)
      storage_account_resource_id              = optional(string, null)
      event_hub_authorization_rule_resource_id = optional(string, null)
      event_hub_name                           = optional(string, null)
      marketplace_partner_resource_id          = optional(string, null)
    }))
    default  = {}
    nullable = false
  
    validation {
      condition     = alltrue([for _, v in var.diagnostic_settings : contains(["Dedicated", "AzureDiagnostics"], v.log_analytics_destination_type)])
      error_message = "Log analytics destination type must be one of: 'Dedicated', 'AzureDiagnostics'."
    }
    validation {
      condition = alltrue(
        [
          for _, v in var.diagnostic_settings :
          v.workspace_resource_id != null || v.storage_account_resource_id != null || v.event_hub_authorization_rule_resource_id != null || v.marketplace_partner_resource_id != null
        ]
      )
      error_message = "At least one of `workspace_resource_id`, `storage_account_resource_id`, `marketplace_partner_resource_id`, or `event_hub_authorization_rule_resource_id`, must be set."
    }
    description = <<DESCRIPTION
  A map of diagnostic settings to create on the Key Vault. The map key is deliberately arbitrary to avoid issues where map keys maybe unknown at plan time.
  
  - `name` - (Optional) The name of the diagnostic setting. One will be generated if not set, however this will not be unique if you want to create multiple diagnostic setting resources.
  - `log_categories` - (Optional) A set of log categories to send to the log analytics workspace. Defaults to `[]`.
  - `log_groups` - (Optional) A set of log groups to send to the log analytics workspace. Defaults to `["allLogs"]`.
  - `metric_categories` - (Optional) A set of metric categories to send to the log analytics workspace. Defaults to `["AllMetrics"]`.
  - `log_analytics_destination_type` - (Optional) The destination type for the diagnostic setting. Possible values are `Dedicated` and `AzureDiagnostics`. Defaults to `Dedicated`.
  - `workspace_resource_id` - (Optional) The resource ID of the log analytics workspace to send logs and metrics to.
  - `storage_account_resource_id` - (Optional) The resource ID of the storage account to send logs and metrics to.
  - `event_hub_authorization_rule_resource_id` - (Optional) The resource ID of the event hub authorization rule to send logs and metrics to.
  - `event_hub_name` - (Optional) The name of the event hub. If none is specified, the default event hub will be selected.
  - `marketplace_partner_resource_id` - (Optional) The full ARM resource ID of the Marketplace resource to which you would like to send Diagnostic LogsLogs.
  DESCRIPTION
  }
  
  # Sample resource
  resource "azurerm_monitor_diagnostic_setting" "this" {
    for_each                       = var.diagnostic_settings
    name                           = each.value.name != null ? each.value.name : "diag-${var.name}"
    target_resource_id             = azurerm_<MY_RESOURCE>.this.id
    storage_account_id             = each.value.storage_account_resource_id
    eventhub_authorization_rule_id = each.value.event_hub_authorization_rule_resource_id
    eventhub_name                  = each.value.event_hub_name
    partner_solution_id            = each.value.marketplace_partner_resource_id
    log_analytics_workspace_id     = each.value.workspace_resource_id
    log_analytics_destination_type = each.value.log_analytics_destination_type
  
    dynamic "enabled_log" {
      for_each = each.value.log_categories
      content {
        category = enabled_log.value
      }
    }
  
    dynamic "enabled_log" {
      for_each = each.value.log_groups
      content {
        category_group = enabled_log.value
      }
    }
  
    dynamic "enabled_metric" {
      for_each = each.value.metric_categories
      content {
        category = enabled_metric.value
      }
    }
  }

  diagnostic_settings = {
    diag_setting_1 = {
      name                                     = "diagSetting1"
      log_groups                               = ["allLogs"]
      metric_categories                        = ["AllMetrics"]
      log_analytics_destination_type           = "Dedicated"
      workspace_resource_id                    = "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}"
      storage_account_resource_id              = "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}"
      event_hub_authorization_rule_resource_id = "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}/eventhubs/{eventHubName}/authorizationrules/{authorizationRuleName}"
      event_hub_name                           = "{eventHubName}"
      marketplace_partner_resource_id          = "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{partnerResourceProvider}/{partnerResourceType}/{partnerResourceName}"
    }
  }

Note

Role Assignments

  variable "role_assignments" {
    type = map(object({
      role_definition_id_or_name             = string
      principal_id                           = string
      description                            = optional(string, null)
      skip_service_principal_aad_check       = optional(bool, false)
      condition                              = optional(string, null)
      condition_version                      = optional(string, null)
      delegated_managed_identity_resource_id = optional(string, null)
      principal_type                         = optional(string, null)
    }))
    default     = {}
    nullable    = false
    description = <<DESCRIPTION
  A map of role assignments to create on the <RESOURCE>. The map key is deliberately arbitrary to avoid issues where map keys maybe unknown at plan time.
  
  - `role_definition_id_or_name` - The ID or name of the role definition to assign to the principal.
  - `principal_id` - The ID of the principal to assign the role to.
  - `description` - (Optional) The description of the role assignment.
  - `skip_service_principal_aad_check` - (Optional) If set to true, skips the Azure Active Directory check for the service principal in the tenant. Defaults to false.
  - `condition` - (Optional) The condition which will be used to scope the role assignment.
  - `condition_version` - (Optional) The version of the condition syntax. Leave as `null` if you are not using a condition, if you are then valid values are '2.0'.
  - `delegated_managed_identity_resource_id` - (Optional) The delegated Azure Resource Id which contains a Managed Identity. Changing this forces a new resource to be created. This field is only used in cross-tenant scenario.
  - `principal_type` - (Optional) The type of the `principal_id`. Possible values are `User`, `Group` and `ServicePrincipal`. It is necessary to explicitly set this attribute when creating role assignments if the principal creating the assignment is constrained by ABAC rules that filters on the PrincipalType attribute.
  
  > Note: only set `skip_service_principal_aad_check` to true if you are assigning a role to a service principal.
  DESCRIPTION
  }
  
  locals {
    role_definition_resource_substring = "providers/Microsoft.Authorization/roleDefinitions"
  }
  
  # Example resource declaration
  resource "azurerm_role_assignment" "this" {
    for_each                               = var.role_assignments
    scope                                  = azurerm_MY_RESOURCE.this.id
    role_definition_id                     = strcontains(lower(each.value.role_definition_id_or_name), lower(local.role_definition_resource_substring)) ? each.value.role_definition_id_or_name : null
    role_definition_name                   = strcontains(lower(each.value.role_definition_id_or_name), lower(local.role_definition_resource_substring)) ? null : each.value.role_definition_id_or_name
    principal_id                           = each.value.principal_id
    condition                              = each.value.condition
    condition_version                      = each.value.condition_version
    skip_service_principal_aad_check       = each.value.skip_service_principal_aad_check
    delegated_managed_identity_resource_id = each.value.delegated_managed_identity_resource_id
    principal_type                         = each.value.principal_type
  }

  role_assignments = {
    role_assignment_1 = {
      role_definition_id_or_name             = "Contributor"
      principal_id                           = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      skip_service_principal_aad_check       = true
    },
    role_assignment_2 = {
      role_definition_id_or_name             = "Storage Blob Data Reader"
      principal_id                           = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
      description                            = "Example role assignment 2 of reader role"
      skip_service_principal_aad_check       = false
      condition                              = "@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:ContainerName] StringEqualsIgnoreCase 'foo_storage_container'"
      condition_version                      = "2.0"
    }
  }

Details on child, extension and cross-referenced resources:

Modules MUST support Role Assignments on child, extension and cross-referenced resources as well as the primary resource via parameters/variables

Resource Locks

  variable "lock" {
    type = object({
      kind = string
      name = optional(string, null)
    })
    default     = null
    description = <<DESCRIPTION
  Controls the Resource Lock configuration for this resource. The following properties can be specified:
  
  - `kind` - (Required) The type of lock. Possible values are `\"CanNotDelete\"` and `\"ReadOnly\"`.
  - `name` - (Optional) The name of the lock. If not specified, a name will be generated based on the `kind` value. Changing this forces the creation of a new resource.
  DESCRIPTION
  
    validation {
      condition     = var.lock != null ? contains(["CanNotDelete", "ReadOnly"], var.lock.kind) : true
      error_message = "Lock kind must be either `\"CanNotDelete\"` or `\"ReadOnly\"`."
    }
  }
  
  # Example resource implementation
  resource "azurerm_management_lock" "this" {
    count = var.lock != null ? 1 : 0
  
    lock_level = var.lock.kind
    name       = coalesce(var.lock.name, "lock-${var.lock.kind}")
    scope      = azurerm_MY_RESOURCE.this.id
    notes      = var.lock.kind == "CanNotDelete" ? "Cannot delete the resource or its child resources." : "Cannot delete or modify the resource or its child resources."
  }

  lock = {
    name = "lock-{resourcename}" # optional
    type = "CanNotDelete"
  }

Details on child and extension resources:

Locks SHOULD be able to be set for child resources of the primary resource in resource modules

Details on cross-referenced resources:

Locks MUST be automatically applied to cross-referenced resources if the primary resource has a lock applied.
- This MUST also be able to be turned off for each of the cross-referenced resources by the module consumer via a parameter/variable if they desire

Important

In Terraform, locks become part of the resource graph and suitable depends_on values should be set. Note that, during a destroy operation, Terraform will remove the locks before removing the resource itself, reducing the usefulness of the lock somewhat. Also note, due to eventual consistency in Azure, use of locks can cause destroy operations to fail as the lock may not have been fully removed by the time the destroy operation is executed.

Managed Identities

  variable "managed_identities" {
    type = object({
      system_assigned            = optional(bool, false)
      user_assigned_resource_ids = optional(set(string), [])
    })
    default     = {}
    nullable    = false
    description = <<DESCRIPTION
  Controls the Managed Identity configuration on this resource. The following properties can be specified:
  
  - `system_assigned` - (Optional) Specifies if the System Assigned Managed Identity should be enabled.
  - `user_assigned_resource_ids` - (Optional) Specifies a list of User Assigned Managed Identity resource IDs to be assigned to this resource.
  DESCRIPTION
  }
  
  # Helper locals to make the dynamic block more readable
  # There are three attributes here to cater for resources that
  # support both user and system MIs, only system MIs, and only user MIs
  locals {
    managed_identities = {
      system_assigned_user_assigned = (var.managed_identities.system_assigned || length(var.managed_identities.user_assigned_resource_ids) > 0) ? {
        this = {
          type                       = var.managed_identities.system_assigned && length(var.managed_identities.user_assigned_resource_ids) > 0 ? "SystemAssigned, UserAssigned" : length(var.managed_identities.user_assigned_resource_ids) > 0 ? "UserAssigned" : "SystemAssigned"
          user_assigned_resource_ids = var.managed_identities.user_assigned_resource_ids
        }
      } : {}
      system_assigned = var.managed_identities.system_assigned ? {
        this = {
          type = "SystemAssigned"
        }
      } : {}
      user_assigned = length(var.managed_identities.user_assigned_resource_ids) > 0 ? {
        this = {
          type                       = "UserAssigned"
          user_assigned_resource_ids = var.managed_identities.user_assigned_resource_ids
        }
      } : {}
    }
  }
  
  ## Resources supporting both SystemAssigned and UserAssigned
  dynamic "identity" {
    for_each = local.managed_identities.system_assigned_user_assigned
    content {
      type         = identity.value.type
      identity_ids = identity.value.user_assigned_resource_ids
    }
  }
  
  ## Resources that only support SystemAssigned
  dynamic "identity" {
    for_each = identity.managed_identities.system_assigned
    content {
      type = identity.value.type
    }
  }
  
  ## Resources that only support UserAssigned
  dynamic "identity" {
    for_each = local.managed_identities.user_assigned
    content {
      type         = identity.value.type
      identity_ids = identity.value.user_assigned_resource_ids
    }
  }

  managed_identities = {
    system_assigned = true
    user_assigned_resource_ids = [
      "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroupName2}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName2}"
    ]
  }

Reason for differences in User Assigned data type in languages:

We do not forsee the Managed Identity Resource Provider team to ever add additional properties within the empty object ({}) value required on the input of a User Assigned Managed Identity.
In Bicep we therefore have removed the need for this to be declared and just converted it to a simple array of Resource IDs
However, in Terraform we have left it as a object/map as this simplifies for_each and other loop mechanisms and provides more consistency in plan, apply, destroy operations
- Especially when adding, removing or changing the order of the User Assigned Managed Identities as they are declared

Private Endpoints

  # In this example we only support one service, e.g. Key Vault.
  # If your service has multiple private endpoint services, then expose the service name.
  
  # This variable is used to determine if the private_dns_zone_group block should be included,
  # or if it is to be managed externally, e.g. using Azure Policy.
  # https://github.com/Azure/terraform-azurerm-avm-res-keyvault-vault/issues/32
  # Alternatively you can use AzAPI, which does not have this issue.
  variable "private_endpoints_manage_dns_zone_group" {
    type        = bool
    default     = true
    nullable    = false
    description = "Whether to manage private DNS zone groups with this module. If set to false, you must manage private DNS zone groups externally, e.g. using Azure Policy."
  }
  
  variable "private_endpoints" {
    type = map(object({
      name               = optional(string, null)
      role_assignments   = optional(map(object({
        role_definition_id_or_name             = string
        principal_id                           = string
        description                            = optional(string, null)
        skip_service_principal_aad_check       = optional(bool, false)
        condition                              = optional(string, null)
        condition_version                      = optional(string, null)
        delegated_managed_identity_resource_id = optional(string, null)
        principal_type         							   = optional(string, null)
      })), {})
      lock               = optional(object({
        kind = string
        name = optional(string, null)
      }), null)
      tags               = optional(map(string), null)
      subnet_resource_id = string
      subresource_name   = string  # NOTE: `subresource_name` can be excluded if the resource does not support multiple sub resource types (e.g. storage account supports blob, queue, etc)
      private_dns_zone_group_name             = optional(string, "default")
      private_dns_zone_resource_ids           = optional(set(string), [])
      application_security_group_associations = optional(map(string), {})
      private_service_connection_name         = optional(string, null)
      network_interface_name                  = optional(string, null)
      location                                = optional(string, null)
      resource_group_name                     = optional(string, null)
      ip_configurations = optional(map(object({
        name               = string
        private_ip_address = string
      })), {})
    }))
    default     = {}
    nullable    = false
    description = <<DESCRIPTION
  A map of private endpoints to create on the Key Vault. The map key is deliberately arbitrary to avoid issues where map keys maybe unknown at plan time.
  
  - `name` - (Optional) The name of the private endpoint. One will be generated if not set.
  - `role_assignments` - (Optional) A map of role assignments to create on the private endpoint. The map key is deliberately arbitrary to avoid issues where map keys maybe unknown at plan time. See `var.role_assignments` for more information.
    - `role_definition_id_or_name` - The ID or name of the role definition to assign to the principal.
    - `principal_id` - The ID of the principal to assign the role to.
    - `description` - (Optional) The description of the role assignment.
    - `skip_service_principal_aad_check` - (Optional) If set to true, skips the Azure Active Directory check for the service principal in the tenant. Defaults to false.
    - `condition` - (Optional) The condition which will be used to scope the role assignment.
    - `condition_version` - (Optional) The version of the condition syntax. Leave as `null` if you are not using a condition, if you are then valid values are '2.0'.
    - `delegated_managed_identity_resource_id` - (Optional) The delegated Azure Resource Id which contains a Managed Identity. Changing this forces a new resource to be created. This field is only used in cross-tenant scenario.
    - `principal_type` - (Optional) The type of the `principal_id`. Possible values are `User`, `Group` and `ServicePrincipal`. It is necessary to explicitly set this attribute when creating role assignments if the principal creating the assignment is constrained by ABAC rules that filters on the PrincipalType attribute.
  - `lock` - (Optional) The lock level to apply to the private endpoint. Default is `None`. Possible values are `None`, `CanNotDelete`, and `ReadOnly`.
    - `kind` - (Required) The type of lock. Possible values are `\"CanNotDelete\"` and `\"ReadOnly\"`.
    - `name` - (Optional) The name of the lock. If not specified, a name will be generated based on the `kind` value. Changing this forces the creation of a new resource.
  - `tags` - (Optional) A mapping of tags to assign to the private endpoint.
  - `subnet_resource_id` - The resource ID of the subnet to deploy the private endpoint in.
  - `subresource_name` - The name of the sub resource for the private endpoint.
  - `private_dns_zone_group_name` - (Optional) The name of the private DNS zone group. One will be generated if not set.
  - `private_dns_zone_resource_ids` - (Optional) A set of resource IDs of private DNS zones to associate with the private endpoint. If not set, no zone groups will be created and the private endpoint will not be associated with any private DNS zones. DNS records must be managed external to this module.
  - `application_security_group_resource_ids` - (Optional) A map of resource IDs of application security groups to associate with the private endpoint. The map key is deliberately arbitrary to avoid issues where map keys maybe unknown at plan time.
  - `private_service_connection_name` - (Optional) The name of the private service connection. One will be generated if not set.
  - `network_interface_name` - (Optional) The name of the network interface. One will be generated if not set.
  - `location` - (Optional) The Azure location where the resources will be deployed. Defaults to the location of the resource group.
  - `resource_group_name` - (Optional) The resource group where the resources will be deployed. Defaults to the resource group of the Key Vault.
  - `ip_configurations` - (Optional) A map of IP configurations to create on the private endpoint. If not specified the platform will create one. The map key is deliberately arbitrary to avoid issues where map keys maybe unknown at plan time.
    - `name` - The name of the IP configuration.
    - `private_ip_address` - The private IP address of the IP configuration.
  DESCRIPTION
  }
  
  # The PE resource when we are managing the private_dns_zone_group block:
  resource "azurerm_private_endpoint" "this" {
    for_each                      = { for k, v in var.private_endpoints : k => v if var.private_endpoints_manage_dns_zone_group }
    name                          = each.value.name != null ? each.value.name : "pep-${var.name}"
    location                      = each.value.location != null ? each.value.location : var.location
    resource_group_name           = each.value.resource_group_name != null ? each.value.resource_group_name : var.resource_group_name
    subnet_id                     = each.value.subnet_resource_id
    custom_network_interface_name = each.value.network_interface_name
    tags                          = each.value.tags
  
    private_service_connection {
      name                           = each.value.private_service_connection_name != null ? each.value.private_service_connection_name : "pse-${var.name}"
      private_connection_resource_id = azurerm_key_vault.this.id
      is_manual_connection           = false
      subresource_names              = ["MYSERVICE"] # map to each.value.subresource_name if there are multiple services.
    }
  
    dynamic "private_dns_zone_group" {
      for_each = length(each.value.private_dns_zone_resource_ids) > 0 ? ["this"] : []
  
      content {
        name                 = each.value.private_dns_zone_group_name
        private_dns_zone_ids = each.value.private_dns_zone_resource_ids
      }
    }
  
    dynamic "ip_configuration" {
      for_each = each.value.ip_configurations
  
      content {
        name               = ip_configuration.value.name
        subresource_name   = "MYSERVICE" # map to each.value.subresource_name if there are multiple services.
        member_name        = "MYSERVICE" # map to each.value.subresource_name if there are multiple services.
        private_ip_address = ip_configuration.value.private_ip_address
      }
    }
  }
  
  # The PE resource when we are managing **not** the private_dns_zone_group block:
  resource "azurerm_private_endpoint" "this_unmanaged_dns_zone_groups" {
    for_each = { for k, v in var.private_endpoints : k => v if !var.private_endpoints_manage_dns_zone_group }
  
    # ... repeat configuration above
    # **omitting the private_dns_zone_group block**
    # then add the following lifecycle block to ignore changes to the private_dns_zone_group block
  
    lifecycle {
      ignore_changes = [private_dns_zone_group]
    }
  }
  
  # Private endpoint application security group associations.
  # We merge the nested maps from private endpoints and application security group associations into a single map.
  locals {
    private_endpoint_application_security_group_associations = { for assoc in flatten([
      for pe_k, pe_v in var.private_endpoints : [
        for asg_k, asg_v in pe_v.application_security_group_associations : {
          asg_key         = asg_k
          pe_key          = pe_k
          asg_resource_id = asg_v
        }
      ]
    ]) : "${assoc.pe_key}-${assoc.asg_key}" => assoc }
  }
  
  resource "azurerm_private_endpoint_application_security_group_association" "this" {
    for_each                      = local.private_endpoint_application_security_group_associations
    private_endpoint_id           = azurerm_private_endpoint.this[each.value.pe_key].id
    application_security_group_id = each.value.asg_resource_id
  }
  
  # You need an additional resource when not managing private_dns_zone_group with this module:
  
  # In your output you need to select the correct resource based on the value of var.private_endpoints_manage_dns_zone_group:
  output "private_endpoints" {
    value       = var.private_endpoints_manage_dns_zone_group ? azurerm_private_endpoint.this : azurerm_private_endpoint.this_unmanaged_dns_zone_groups
    description = <<DESCRIPTION
  A map of the private endpoints created.
  DESCRIPTION
  }

  private_endpoints = {
    pe1 = {
      role_assignments   = {} # see interfaces/role assignments
      lock               = {} # see interfaces/resource locks
      tags               = {} # see interfaces/tags
      subnet_resource_id = "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/virtualNetworks/{vnetName}/subnets/{subnetName}"
      private_dns_zone_resource_ids = [
        "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/privateDnsZones/{dnsZoneName}"
      ]
      application_security_group_associations = {
        asg1 = "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/applicationSecurityGroups/{asgName}"
      }
      network_interface_name = "nic1"
      ip_configurations = {
        ipconfig1 = {
          name               = "ipconfig1"
          group_id           = "vault"
          member_name        = "default"
          private_ip_address = "10.0.0.7"
        }
      }
    }
  }

Notes:

The properties defined in the schema above are the minimum amount of properties expected to be exposed for Private Endpoints in AVM Resource Modules.
- A module owner MAY chose to expose additional properties of the Private Endpoint resource.
  - However, module owners considering this SHOULD contact the AVM core team first to consult on how the property should be exposed to avoid future breaking changes to the schema that may be enforced upon them.
Module owners MAY chose to define a list of allowed value for the ‘service’ (a.k.a. groupIds) property.
- However, they should do so with caution as should a new service appear for their resource module, a new release will need to be cut to add this new service to the allowed values.
  - Whereas not specifying allowed values will allow flexibility from day 0 without the need for any changes and releases to be made.

Customer Managed Keys

  variable "customer_managed_key" {
    type = object({
      key_vault_resource_id  = string
      key_name               = string
      key_version            = optional(string, null)
      user_assigned_identity = optional(object({
        resource_id = string
      }), null)
    })
    default = null
  }

  customer_managed_key = {
    key_vault_resource_id: "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/vaults/{keyVaultName}"
    key_name: "{keyName}"
    key_version: "{keyVersion}"
    user_assigned_identity_resource_id: "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{uamiName}"
  }

Azure Monitor Alerts

Note

This interface is a SHOULD instead of a MUST and therefore the AVM core team have not mandated a interface schema to use.

Terraform Pattern Module Specifications

Contribution / Support

The content below is listed based on the following tags

Category-Contribution/SupportClass-PatternLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR8	Module Owner(s) GitHub	MUST	Owner	Initial
2	SNFR20	GitHub Teams Only	MUST	Owner	Initial
3	SNFR9	AVM & PG Teams GitHub Repo Permissions	MUST	Owner	Initial
4	SNFR10	MIT Licensing	MUST	Owner	Initial
5	SNFR11	Issues Response Times	MUST	OwnerContributor	BAU
6	SNFR12	Versions Supported	MUST	Owner	BAU
7	SNFR23	GitHub Repo Labels	MUST	Owner	BAU
8	TFNFR3	GitHub Repo Branch Protection	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR8 - Category: Contribution/Support - Module Owner(s) GitHub

A module MUST have an owner that is defined and managed by a GitHub Team in the Azure GitHub organization.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

See origin...

ID: SNFR20 - Category: Contribution/Support - GitHub Teams Only

All GitHub repositories that AVM module are published from and hosted within MUST only assign GitHub repository permissions to GitHub teams only.

Each module MUST have separate GitHub teams assigned for module owners AND module contributors respectively. These GitHub teams MUST be created in the Azure organization in GitHub.

There MUST NOT be any GitHub repository permissions assigned to individual users.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

Important

Naming Convention

The naming convention for the GitHub teams MUST follow the below pattern:

<hyphenated module name>-module-owners-<bicep/tf> - to be assigned as the GitHub repository’s Module Owners team
<hyphenated module name>-module-contributors-<bicep/tf> - to be assigned as the GitHub repository’s Module Contributors team

Note

The naming convention for Bicep modules is slightly different than the naming convention for their respective GitHub teams.

Segments:

<hyphenated module name> == the AVM Module’s name, with each segment separated by dashes, i.e., avm-res-<resource provider>-<ARM resource type>
- See RMNFR1 for AVM Resource Module Naming
- See PMNFR1 for AVM Pattern Module Naming
module-owners or module-contributors == the role the GitHub Team is assigned to
<bicep/tf> == the language the module is written in

Examples:

avm-res-compute-virtualmachine-module-owners-bicep
avm-res-compute-virtualmachine-module-contributors-tf

Add Team Members

All officially documented module owner(s) MUST be added to the -module-owners- team. The -module-owners- team MUST NOT have any other members.

Any additional module contributors whom the module owner(s) agreed to work with MUST be added to the -module-contributors- team.

Grant Permissions - Bicep

Team memberships

Note

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<hyphenated module name>-module-owners-bicep`	AVM Bicep Module Owners - <module name>	Write	Assignment to the `avm-technical-reviewers-bicep` parent team.	Need to work in a fork.
`<hyphenated module name>-module-contributors-bicep`	AVM Bicep Module Contributors - <module name>	Triage	`avm-module-contributors-bicep` parent team.	Need to work in a fork.

Examples - GitHub teams required for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

avm-res-network-virtualnetwork-module-owners-bicep –> assign to the avm-technical-reviewers-bicep parent team.
avm-res-network-virtualnetwork-module-contributors-bicep –> assign to the avm-module-contributors-bicep parent team.

Tip

Direct link to create a new GitHub team and assign it to its parent: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Follow the guidance above (see the Permissions granted through column in the table above).
Team visibility: Visible
Team notifications: Enabled

CODEOWNERS file

As part of the “initial Pull Request” (that publishes the first version of the module), module owners MUST add an entry to the CODEOWNERS file in the BRM repository (here).

Note

Through this approach, the AVM core team will grant review permission to module owners as part of the standard PR review process.

Every CODEOWNERS entry (line) MUST include the following segments separated by a single whitespace character:

Path of the module, relative to the repo’s root, e.g.: /avm/res/network/virtual-network/
The -module-owners-team, with the @Azure/ prefix, e.g., @Azure/avm-res-network-virtualnetwork-module-owners-bicep
The GitHub team of the AVM Bicep reviewers, with the @Azure/ prefix, i.e., @Azure/avm-module-reviewers-bicep

Example - CODEOWNERS entry for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

/avm/res/network/virtual-network/ @Azure/avm-res-network-virtualnetwork-module-owners-bicep @Azure/avm-module-reviewers-bicep

Grant Permissions - Terraform

Module owners MUST assign the -module-owners-and -module-contributors- teams the necessary permissions on their Terraform module repository per the guidance below.

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<module name>-module-owners-tf`	AVM Terraform Module Owners - <module name>	Admin	Direct assignment to repo	Module owner can decide whether they want to work in a branch local to the repo or in a fork.
`<module name>-module-contributors-tf`	AVM Terraform Module Contributors - <module name>	Write	Direct assignment to repo	Need to work in a fork.

Tip

Direct link to create a new GitHub team: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Do not assign the team to any parent team.
Team visibility: Visible
Team notifications: Enabled

See origin...

ID: SNFR9 - Category: Contribution/Support - AVM & PG Teams GitHub Repo Permissions

A module owner MUST make the following GitHub teams in the Azure GitHub organization admins on the GitHub repo of the module in question:

Bicep

@Azure/avm-core-team-technical-bicep = AVM Core Team
@Azure/bicep-admins = Bicep PG team

Note

These required GitHub teams are already associated to the BRM repository and have the required permissions.

Terraform

@Azure/avm-core-team-technical-terraform = AVM Core Team
@Azure/terraform-avm = Terraform PG

Important

Module owners MUST assign these GitHub teams as admins on the GitHub repo of the module in question.

For detailed steps, please follow this guidance.

See origin...

ID: SNFR10 - Category: Contribution/Support - MIT Licensing

A module MUST be published with the MIT License in the Azure GitHub organization.

See origin...

ID: SNFR11 - Category: Contribution/Support - Issues Response Times

A module owner MUST respond to logged issues as defined in the support statement. See Module Support for more information.

See origin...

ID: SNFR12 - Category: Contribution/Support - Versions Supported

Only the latest released version of a module MUST be supported.

This avoids AVM Module owners from having to maintain multiple major release versions.

See origin...

ID: SNFR23 - Category: Contribution/Support - GitHub Repo Labels

GitHub repositories where modules are held MUST use the below labels and SHOULD not use any additional labels:

➕ AVM Standard GitHub Labels

These labels are available in a CSV file from here

Name	Description	HEX
AZD 🧑‍💻	These modules are requested/used by the AZD team.	`E0BFFA`
Needs: Attention 👋	Reply has been added to issue, maintainer to review	`E99695`
Needs: Immediate Attention ‼️	Immediate attention of module owner / AVM team is needed	`FF0000`
Needs: Author Feedback 👂	Awaiting feedback from the issue/PR author	`F18A07`
Needs: External Changes ⚒️	When an issue/PR requires changes that are outside of the control of the module. e.g. to an RP.	`DE389D`
Needs: More Evidence ⚖	We are looking for more evidence to make a decision on this	`F64872`
Needs: Triage 🔍	Maintainers need to triage still	`FBCA04`
Needs: Module Owner 📣	In the AVM repository: this module needs an owner to develop or maintain it. In the BRM repository: the module owner needs to review a PR.	`FF0019`
Needs: Module Contributor 📣	This module needs secondary owner(s) or contributor(s) to develop or maintain it	`C95474`
Needs: Core Team 🧞‍♂️	This item needs the AVM Core Team to review it	`DB4503`
Status: Awaiting Release To Be Cut ✂️	This is fixed in the main branch but not in the latest release, will be fixed with next release cut	`800080`
Status: Do Not Merge ⛔	Do not merge PRs with this label attached as they are not ready or aligned to future direction etc.	`8B4513`
Status: External Contribution 🌍	This is being worked on by someone outside of the AVM module owners/contributors or AVM core team	`D8FA2C`
Status: Fixed ✅	Auto label applied when issue fixed by merged PR	`90EE90`
Status: Help Wanted 🆘	Extra attention is needed	`FF4500`
Status: In Triage 🔍	Picked up for triaging by an AVM core team member	`D4AF37`
Status: In PR 👉	This is when an issue is due to be fixed in an open PR	`EDEDED`
Status: Invalid ❌	This doesn't seem right	`E4E669`
Status: Long Term ⏳	We will do it, but will take a longer amount of time due to complexity/priorities	`B60205`
Status: No Recent Activity 💤	When an issue/PR has not been modified for X amount of days	`808080`
Status: Won't Fix 💔	This will not be worked on	`FFFFFF`
Status: Owners Identified 🤘	This module has its owners identified	`FBEF2A`
Status: Module Available 🟢	The module is published	`C8E6C9`
Status: Module Deprecated 🔴	This is a request to deprecate a module	`000000`
Status: Module Orphaned 🟡	The module has no owner and is therefore orphaned at this time	`F4A460`
Status: Ready For Repository Creation 📝	This module is approved and the owner is ready for the repository to be created (Terraform)	`136A41`
Status: Repository Created 📄	This module has had it's repository created and configured ready for owner contribution (Terraform)	`27AB03`
Status: Response Overdue 🚩	When an issue/PR has not been responded to for X amount of days	`850000`
Status: Looking For Assistance 🦆	This item is looking for anyone to help develop the code and submit a PR for resolution	`03FCC2`
Type: Bug 🐛	Something isn't working	`D73A4A`
Type: CI 🚀	This issue is related to the AVM CI	`74CFB0`
Type: Documentation 📄	Improvements or additions to documentation	`0075CA`
Type: Duplicate 🤲	This issue or pull request already exists	`CFD3D7`
Type: Feature Request ➕	New feature or request	`A2EEEF`
Type: Hygiene 🧹	things related to testing, issue triage etc.	`17016A`
Type: New Module Proposal 💡	A new module for AVM is being proposed	`ADD8E6`
Type: Question/Feedback 🙋‍♀️	Further information is requested or just some feedback	`CB6BA2`
Type: Security Bug 🔒	This is a security bug	`FFFF00`
Type: AVM 🅰️ ✌️ ⓜ️	This is an AVM related issue	`F0FFFF`
Language: Terraform 🌐	This is related to the Terraform IaC language	`7740B6`
Language: Bicep 💪	This is related to the Bicep IaC language	`1D73B3`
Class: Resource Module 📦	This is a resource module	`D3D3D3`
Class: Pattern Module 📦	This is a pattern module	`A9A9A9`
Class: Utility Module 📦	This is a utility module	`CAD1DE`
Class: Child Module 📦	This is a child module	`5E5186`

To help apply these to a module GitHub repository you can use the below PowerShell script:

➕ Set-AvmGitHubLabels.ps1

For most scenario this is the command you’ll need to call the below PowerShell script with, replacing the value for RepositoryName:

  Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -CreateCsvLabelExports $false -NoUserPrompts $true

```shell
# Linux / MacOs
# For Windows replace $PWD with your the local path or your repository
#
docker run -it -v $PWD:/repo -w /repo mcr.microsoft.com/powershell pwsh -Command '
    #Invoke-WebRequest -Uri "https://azure.github.io/Azure-Verified-Modules/scripts/Set-AvmGitHubLabels.ps1" -OutFile "Set-AvmGitHubLabels.ps1"
    $gh_version = "2.44.1"
    Invoke-WebRequest -Uri "https://github.com/cli/cli/releases/download/v2.44.1/gh_2.44.1_linux_amd64.tar.gz" -OutFile "gh_$($gh_version)_linux_amd64.tar.gz"
    apt-get update && apt-get install -y git
    tar -xzf "gh_$($gh_version)_linux_amd64.tar.gz"
    ls -lsa
    mv "gh_$($gh_version)_linux_amd64/bin/gh" /usr/local/bin/
    rm "gh_$($gh_version)_linux_amd64.tar.gz" && rm -rf "gh_$($gh_version)_linux_amd64"
    gh --version
    ls -lsa
    gh auth login
    $OrgProject = "Azure/terraform-azurerm-avm-res-kusto-cluster"
    gh auth status
    ./Set-AvmGitHubLabels.ps1 -RepositoryName $OrgProject -CreateCsvLabelExports $false -NoUserPrompts $true

  '
```

Full Script:

These Set-AvmGitHubLabels.ps1 can be downloaded from here.

  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "", Justification = "Coloured output required in this script")]
  
  <#
  .SYNOPSIS
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
  .DESCRIPTION
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
    By default, the script will remove all pre-existing labels and apply the AVM labels. However, this can be changed by using the -RemoveExistingLabels parameter and setting it to $false. The tool will also output the labels that exist in the repository before and after the script has run to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter.
  
    The AVM labels to be created are documented here: TBC
  
  .NOTES
    Please ensure you have specified the GitHub repositry correctly. The script will prompt you to confirm the repository name before proceeding.
  
  .COMPONENT
    You must have the GitHub CLI installed and be authenticated to a GitHub account with access to the repository you are applying the labels to before running this script.
  
  .LINK
    TBC
  
  .Parameter RepositoryName
    The name of the GitHub repository to apply the labels to.
  
  .Parameter RemoveExistingLabels
    If set to $true, the default value, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will not remove any pre-existing labels.
  
  .Parameter UpdateAndAddLabelsOnly
    If set to $true, the default value, the script will only update and add labels to the repository specified in -RepositoryName. If set to $false, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
  .Parameter OutputDirectory
    The directory to output the pre-existing and post-existing labels to in a CSV file. The default value is the current directory.
  
  .Parameter CreateCsvLabelExports
    If set to $true, the default value, the script will output the pre-existing and post-existing labels to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter. If set to $false, the script will not output the pre-existing and post-existing labels to a CSV file.
  
  .Parameter GitHubCliLimit
    The maximum number of labels to return from the GitHub CLI. The default value is 999.
  
  .Parameter LabelsToApplyCsvUri
    The URI to the CSV file containing the labels to apply to the GitHub repository. The default value is https://raw.githubusercontent.com/jtracey93/label-source/main/avm-github-labels.csv.
  
  .Parameter NoUserPrompts
    If set to $true, the default value, the script will not prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
    This is useful for running the script in automation workflows
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and remove all pre-existing labels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false -CreateCsvLabelExports $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name. Finally, use a custom CSV file hosted on the internet to create the labels from.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false -CreateCsvLabelExports $false -LabelsToApplyCsvUri "https://example.com/csv/avm-github-labels.csv"
  
  #>
  
  #Requires -PSEdition Core
  
  [CmdletBinding()]
  param (
    [Parameter(Mandatory = $true)]
    [string]$RepositoryName,
  
    [Parameter(Mandatory = $false)]
    [bool]$RemoveExistingLabels = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$UpdateAndAddLabelsOnly = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$CreateCsvLabelExports = $true,
  
    [Parameter(Mandatory = $false)]
    [string]$OutputDirectory = (Get-Location),
  
    [Parameter(Mandatory = $false)]
    [int]$GitHubCliLimit = 999,
  
    [Parameter(Mandatory = $false)]
    [string]$LabelsToApplyCsvUri = "https://azure.github.io/Azure-Verified-Modules/governance/avm-standard-github-labels.csv",
  
    [Parameter(Mandatory = $false)]
    [bool]$NoUserPrompts = $false
  )
  
  # Check if the GitHub CLI is installed
  $GitHubCliInstalled = Get-Command gh -ErrorAction SilentlyContinue
  if ($null -eq $GitHubCliInstalled) {
    throw "The GitHub CLI is not installed. Please install the GitHub CLI and try again."
  }
  Write-Host "The GitHub CLI is installed..." -ForegroundColor Green
  
  # Check if GitHub CLI is authenticated
  $GitHubCliAuthenticated = gh auth status
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubCliAuthenticated -ForegroundColor Red
    throw "Not authenticated to GitHub. Please authenticate to GitHub using the GitHub CLI, `gh auth login`, and try again."
  }
  Write-Host "Authenticated to GitHub..." -ForegroundColor Green
  
  # Check if GitHub repository name is valid
  $GitHubRepositoryNameValid = $RepositoryName -match "^[a-zA-Z0-9-]+/[a-zA-Z0-9-]+$"
  if ($false -eq $GitHubRepositoryNameValid) {
    throw "The GitHub repository name $RepositoryName is not valid. Please check the repository name and try again. The format must be <OrgName>/<RepoName>"
  }
  
  # List GitHub repository provided and check it exists
  $GitHubRepository = gh repo view $RepositoryName
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubRepository -ForegroundColor Red
    throw "The GitHub repository $RepositoryName does not exist. Please check the repository name and try again."
  }
  Write-Host "The GitHub repository $RepositoryName exists..." -ForegroundColor Green
  
  # PRE - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($RemoveExistingLabels -or $UpdateAndAddLabelsOnly) {
    Write-Host "Getting the current GitHub repository (pre) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels -and $CreateCsvLabelExports -eq $true) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Pre-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (pre) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # Remove all pre-existing labels if -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels
  if ($null -ne $GitHubRepositoryLabels) {
    $GitHubRepositoryLabelsJson = $GitHubRepositoryLabels | ConvertFrom-Json
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $false -and $UpdateAndAddLabelsOnly -eq $false) {
      $RemoveExistingLabelsConfirmation = Read-Host "Are you sure you want to remove all $($GitHubRepositoryLabelsJson.Count) pre-existing labels from $($RepositoryName)? (Y/N)"
      if ($RemoveExistingLabelsConfirmation -eq "Y") {
        Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
        $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
          Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
          gh label delete -R $RepositoryName $_.name --yes
        }
      }
    }
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $true -and $UpdateAndAddLabelsOnly -eq $false) {
      Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
        Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
        gh label delete -R $RepositoryName $_.name --yes
      }
    }
  }
  if ($null -eq $GitHubRepositoryLabels) {
    Write-Host "No pre-existing labels to remove or not selected to be removed from $RepositoryName..." -ForegroundColor Magenta
  }
  
  # Check LabelsToApplyCsvUri is valid and contains a CSV content
  Write-Host "Checking $LabelsToApplyCsvUri is valid..." -ForegroundColor Yellow
  $LabelsToApplyCsvUriValid = $LabelsToApplyCsvUri -match "^https?://"
  if ($false -eq $LabelsToApplyCsvUriValid) {
    throw "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is not valid. Please check the URI and try again. The format must be a valid URI."
  }
  Write-Host "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is valid..." -ForegroundColor Green
  
  # Create AVM lables from the AVM labels CSV file stored on the web using the convertfrom-csv cmdlet
  $avmLabelsCsv = Invoke-WebRequest -Uri $LabelsToApplyCsvUri | ConvertFrom-Csv
  
  # Check if the AVM labels CSV file contains the following columns: Name, Description, HEX
  $avmLabelsCsvColumns = $avmLabelsCsv | Get-Member -MemberType NoteProperty | Select-Object -ExpandProperty Name
  $avmLabelsCsvColumnsValid = $avmLabelsCsvColumns -contains "Name" -and $avmLabelsCsvColumns -contains "Description" -and $avmLabelsCsvColumns -contains "HEX"
  if ($false -eq $avmLabelsCsvColumnsValid) {
    throw "The labels CSV file does not contain the required columns: Name, Description, HEX. Please check the CSV file and try again. It contains the following columns: $avmLabelsCsvColumns"
  }
  Write-Host "The labels CSV file contains the required columns: Name, Description, HEX" -ForegroundColor Green
  
  # Create the AVM labels in the GitHub repository
  Write-Host "Creating/Updating the $($avmLabelsCsv.Count) AVM labels in $RepositoryName..." -ForegroundColor Yellow
  $avmLabelsCsv | ForEach-Object {
    if ($GitHubRepositoryLabelsJson.name -contains $_.name) {
      Write-Host "The label $($_.name) already exists in $RepositoryName. Updating the label to ensure description and color are consitent..." -ForegroundColor Magenta
      gh label create -R $RepositoryName "$($_.name)" -c $_.HEX -d $($_.Description) --force
    }
    else {
      Write-Host "The label $($_.name) does not exist in $RepositoryName. Creating label $($_.name) in $RepositoryName..." -ForegroundColor Cyan
      gh label create -R $RepositoryName "$($_.Name)" -c $_.HEX -d $($_.Description) --force
    }
  }
  
  # POST - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($CreateCsvLabelExports -eq $true) {
    Write-Host "Getting the current GitHub repository (post) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Post-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (post) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # If -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels check that only the avm labels exist in the repository
  if ($RemoveExistingLabels -eq $true -and ($RemoveExistingLabelsConfirmation -eq "Y" -or $NoUserPrompts -eq $true) -and $UpdateAndAddLabelsOnly -eq $false) {
    Write-Host "Checking that only the AVM labels exist in $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
    $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
      if ($avmLabelsCsv.Name -notcontains $_.name) {
        throw "The label $($_.name) exists in $RepositoryName but is not in the CSV file."
      }
    }
    Write-Host "Only the CSV labels exist in $RepositoryName..." -ForegroundColor Green
  }
  
  Write-Host "The CSV labels have been created/updated in $RepositoryName..." -ForegroundColor Green

See origin...

ID: TFNFR3 - Category: Contribution/Support - GitHub Repo Branch Protection

Module owners MUST set a branch protection policy on their GitHub Repositories for AVM modules against their default branch, typically main, to do the following:

Requires a Pull Request before merging
Require approval of the most recent reviewable push
Dismiss stale pull request approvals when new commits are pushed
Require linear history
Prevents force pushes
Not allow deletions
Require CODEOWNERS review
Do not allow bypassing the above settings
Above settings MUST also be enforced to administrators

Tip

If you use the template repository as mentioned in the contribution guide, the above will automatically be set.

Telemetry

The content below is listed based on the following tags

Category-TelemetryClass-PatternLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SFR3	Deployment/Usage Telemetry	MUST	Owner	Initial
2	SFR4	Telemetry Enablement Flexibility	MUST	Owner	Initial

➕ See Specifications for this category

See origin...

ID: SFR3 - Category: Telemetry - Deployment/Usage Telemetry

Important

These will also be provided as a comment on the module proposal, once accepted, from the AVM core team.

Modules MUST provide the capability to collect deployment/usage telemetry as detailed in Telemetry further.

Telemetry Information Notice

Note

The following information notice is automatically added at the bottom of the README.md file of the module when

Bicep: Using the utilities/tools/Set-AVMModule.ps1 utility
Terraform: Executing the make docs command with the note and header ## Data Collection being placed in the module’s _footer.md beforehand

### Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the [repository](https://aka.ms/avm/telemetry). There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at <https://go.microsoft.com/fwlink/?LinkID=824704>. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Bicep

Important

The value you need to use for your module is defined in the related module index. You can look it up on the index pages for Resource Modules, Pattern Modules and Utility Modules.

The ARM deployment name used for the telemetry MUST follow the pattern and MUST be no longer than 64 characters in length: 46d3xbcp.<res/ptn>.<(short) module name>.<version>.<uniqueness>

<res/ptn> == AVM Resource or Pattern Module
<(short) module name> == The AVM Module’s, possibly shortened, name including the resource provider and the resource type, without;
- The prefixes: avm-res-
- The prefixes: avm-ptn-
<version> == The AVM Module’s MAJOR.MINOR version (only) with . (periods) replaced with - (hyphens), to allow simpler splitting of the ARM deployment name
<uniqueness> == This section of the ARM deployment name is to be used to ensure uniqueness of the deployment name.
- This is to cater for the following scenarios:
  - The module is deployed multiple times to the same:
    - Location/Region
    - Scope (Tenant, Management Group,Subscription, Resource Group)

Note

An example deployment name for the AVM Virtual Machine Resource Module would be: 46d3xbcp.res.compute-virtualmachine.1-2-3.eum3

An example deployment name for a shortened module name would be: 46d3xbcp.res.desktopvirtualization-appgroup.1-2-3.eum3

Tip

Terraform: Terraform uses a telemetry provider, the configuration of which is the same for every module and is included in the template repo.

General: See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

Terraform

The modtm telemetry provider is included in all Terraform modules and is enabled by default through the main.telemetry.tf file being automatically distributed from the template repo.

The modtm provider MUST be listed under the required_providers section in the module’s terraform.tf file using the following entry. This is also validated by the linter.

terraform {
  required_providers {
    # .. other required providers as needed
    modtm = {
      source = "Azure/modtm"
      version = "~> 0.3"
    }
  }
}

See origin...

ID: SFR4 - Category: Telemetry - Telemetry Enablement Flexibility

The telemetry enablement MUST be on/enabled by default, however this MUST be able to be disabled by a module consumer by setting the below parameter/variable value to false:

Bicep: enableTelemetry
Terraform: enable_telemetry

Note

This general specification can be modified for some use-cases, that are language specific:

Bicep

For cross-references in resource modules, the spec BCPFR7 also applies.

Terraform

Currently, no further requirements apply.

Naming / Composition

The content below is listed based on the following tags

Category-Naming/CompositionClass-PatternLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SFR1	Preview Services	MUST	Owner	BAU
2	SFR2	WAF Aligned	SHOULD	Owner	BAU
3	SFR5	Availability Zones	MUST	Owner	Initial
4	SFR6	Data Redundancy	MUST	Owner	Initial
5	SNFR25	Resource Naming	MUST	Owner	Initial
6	PMFR1	Resource Group Creation	MAY	OwnerContributor	BAU
7	PMNFR1	Module Naming	MUST	Owner	Initial
8	PMNFR2	Use Resource Modules to Build a Pattern Module	MUST	OwnerContributor	BAU
9	PMNFR3	Use other Pattern Modules to Build a Pattern Module	MUST	OwnerContributor	BAU
10	TFFR1	Cross-Referencing Modules	MUST	OwnerContributor	BAU
11	TFFR3	Providers - Permitted Versions	MUST	OwnerContributor	BAU
12	TFNFR4	Lower snake_casing	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SFR1 - Category: Composition - Preview Services

Modules MAY create/adopt public preview services and features at their discretion.

Preview API versions MAY be used when:

The resource/service/feature is GA but the only API version available for the GA resource/service/feature is a preview version
- For example, Diagnostic Settings (Microsoft.Insights/diagnosticSettings) the latest version of the API available with GA features, like Category Groups etc., is 2021-05-01-preview
- Otherwise the latest “non-preview” version of the API SHOULD be used

Preview services and features, SHOULD NOT be promoted and exposed, unless they are supported by the respective PG, and it’s documented publicly.

However, they MAY be exposed at the module owners discretion, but the following rules MUST be followed:

The description of each of the parameters/variables used for the preview service/feature MUST start with:
- “THIS IS A <PARAMETER/VARIABLE> USED FOR A PREVIEW SERVICE/FEATURE, MICROSOFT MAY NOT PROVIDE SUPPORT FOR THIS, PLEASE CHECK THE PRODUCT DOCS FOR CLARIFICATION”

See origin...

ID: SFR2 - Category: Composition - WAF Aligned

Well-Architected Framework (WAF)
Reliability Hub
Azure Proactive Resiliency Library (APRL)
- Only Product Group (PG) verified
Microsoft Defender for Cloud (MDFC)

They SHOULD NOT align to these recommendations when it requires an external dependency/resource to be deployed and configured and then associated to the resources in the module.

Alignment SHOULD prioritize best-practices and security over cost optimization, but MUST allow for these to be overridden by a module consumer easily, if desired.

Tip

Read the FAQ of What does AVM mean by “WAF Aligned”? for more detailed information and examples.

See origin...

ID: SFR5 - Category: Composition - Availability Zones

Modules that deploy zone-redundant resources MUST enable the spanning across as many zones as possible by default, typically all 3.

For both scenarios the modules MUST expose these configuration options via configurable parameters/variables.

Note

For information on the differences between zonal and zone-redundant services, see Availability zone service and regional support

See origin...

ID: SFR6 - Category: Composition - Data Redundancy

Note

For information on the data redundancy options in Azure, see Cross-region replication in Azure

See origin...

ID: SNFR25 - Category: Composition - Resource Naming

Module owners MUST also provide the ability for these default names, including the prefixes, to be overridden via a parameter/variable if the consumer wishes to.

Tip

If the resource does not have a documented abbreviation in Abbreviation examples for Azure resources, then the module owner is free to use a sensible prefix instead.

See origin...

ID: PMFR1 - Category: Composition - Resource Group Creation

A Pattern Module MAY create Resource Group(s).

See origin...

ID: PMNFR1 - Category: Naming - Module Naming

Pattern Modules MUST follow the below naming conventions (all lower case):

Bicep Pattern Module Naming

Naming convention: avm/ptn/<hyphenated grouping/category name>/<hyphenated pattern module name>
Example: avm/ptn/compute/app-tier-vmss or avm/ptn/avd-lza/management-plane or avm/ptn/3-tier/web-app
Segments:
- ptn defines this as a pattern module
- <hyphenated grouping/category name> is a hierarchical grouping of pattern modules by category, with each word separated by dashes, such as:
  - project name, e.g., avd-lza,
  - primary resource provider, e.g., compute or network, or
  - architecture, e.g., 3-tier
- <hyphenated pattern module name> is a term describing the module’s function, with each word separated by dashes, e.g., app-tier-vmss = Application Tier VMSS; management-plane = Azure Virtual Desktop Landing Zone Accelerator Management Plane

Terraform Pattern Module Naming

Naming convention:
- avm-ptn-<pattern module name> (Module name for registry)
- terraform-<provider>-avm-ptn-<pattern module name> (GitHub repository name to meet registry naming requirements)
Example: avm-ptn-apptiervmss or avm-ptn-avd-lza-managementplane
Segments:
- <provider> is the logical abstraction of various APIs used by Terraform. In most cases, this is going to be azurerm or azuread for resource modules.
- ptn defines this as a pattern module
- <pattern module name> is a term describing the module’s function, e.g., apptiervmss = Application Tier VMSS; avd-lza-managementplane = Azure Virtual Desktop Landing Zone Accelerator Management Plane

See origin...

ID: PMNFR2 - Category: Composition - Use Resource Modules to Build a Pattern Module

Valid reasons for not using a Resource Module for a resource required by a Pattern Module include but are not limited to:

When using a Resource Module would result in hitting scaling limitations and/or would reduce the capabilities of the Pattern Module due to the limitations of Azure Resource Manager.
Developing a Pattern Module under time constraint, without having all required Resource Modules readily available.

Note

See origin...

ID: PMNFR3 - Category: Composition - Use other Pattern Modules to Build a Pattern Module

A Pattern Module MAY contain and be built using other AVM Pattern Modules. A Pattern Module MUST NOT contain references to non-AVM modules.

See origin...

ID: TFFR1 - Category: Composition - Cross-Referencing Modules

Module owners MAY cross-references other modules to build either Resource or Pattern modules. However, they MUST be referenced only by a HashiCorp Terraform registry reference to a pinned version e.g.,

module "other-module" {
  source  = "Azure/xxx/azurerm"
  version = "1.2.3"
}

They MUST NOT use git reference to a module.

module "other-module" {
  source = "git::https://xxx.yyy/xxx.git"
}

module "other-module" {
  source = "github.com/xxx/yyy"
}

Modules MUST NOT contain references to non-AVM modules.

Tip

See Module Sources for more information.

See origin...

ID: TFFR3 - Category: Providers - Permitted Versions

Authors MUST only use the following Azure providers, and versions, in their modules:

provider	min version	max version
azapi	>= 2.0	< 3.0
azurerm	>= 4.0	< 5.0

Note

Authors MAY select either Azurerm, Azapi, or both providers in their module.

Authors MUST use the required_providers block in their module to enforce the provider versions.

The following is an example.

In it we use the pessimistic version constraint operator ~>.
That is to say that ~> 4.0 is equivalent to >= 4.0, < 5.0.

terraform {
  required_providers {
    # Include one or both providers, as needed
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
  }
}

See origin...

ID: TFNFR4 - Category: Composition - Code Styling - lower snake_casing

Module owners MUST use lower snake_casing for naming the following:

Locals
Variables
Outputs
Resources (symbolic names)
Modules (symbolic names)

For example: snake_casing_example (every word in lowercase, with each word separated by an underscore _)

Code Style

The content below is listed based on the following tags

Category-CodeStyleClass-PatternLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	TFNFR6	Resource & Data Order	SHOULD	OwnerContributor	BAU
2	TFNFR7	Count & for_each Use	MUST	OwnerContributor	BAU
3	TFNFR8	Resource & Data Block Orders	SHOULD	OwnerContributor	BAU
4	TFNFR9	Module Block Order	SHOULD	OwnerContributor	BAU
5	TFNFR10	No Double Quotes in ignore_changes	MUST	OwnerContributor	BAU
6	TFNFR11	Null Comparison Toggle	SHOULD	OwnerContributor	BAU
7	TFNFR12	Dynamic for Optional Nested Objects	MUST	OwnerContributor	BAU
8	TFNFR13	Default Values with coalesce/try	SHOULD	OwnerContributor	BAU
9	TFNFR16	Variable Naming Rules	SHOULD	OwnerContributor	BAU
10	TFNFR17	Variables with Descriptions	SHOULD	OwnerContributor	BAU
11	TFNFR18	Variables with Types	MUST	OwnerContributor	BAU
12	TFNFR19	Sensitive Data Variables	SHOULD	OwnerContributor	BAU
13	TFNFR20	Non-Nullable Defaults for collection values	SHOULD	OwnerContributor	BAU
14	TFNFR21	Discourage Nullability by Default	MUST	OwnerContributor	BAU
15	TFNFR22	Avoid sensitive = false	MUST	OwnerContributor	BAU
16	TFNFR23	Sensitive Default Value Conditions	MUST	OwnerContributor	BAU
17	TFNFR24	Handling Deprecated Variables	MUST	OwnerContributor	BAU
18	TFNFR25	Verified Modules Requirements	MUST	OwnerContributor	BAU
19	TFNFR26	Providers in required_providers	MUST	OwnerContributor	BAU
20	TFNFR27	Provider Declarations in Modules	MUST	OwnerContributor	BAU
22	TFNFR30	Handling Deprecated Outputs	MUST	OwnerContributor	BAU
23	TFNFR31	locals.tf for Locals Only	MAY	OwnerContributor	BAU
25	TFNFR33	Precise Local Types	SHOULD	OwnerContributor	BAU
26	TFNFR34	Using Feature Toggles	MUST	OwnerContributor	BAU
27	TFNFR35	Reviewing Potential Breaking Changes	MUST	OwnerContributor	BAU
28	TFNFR36	Setting prevent_deletion_if_contains_resources	SHOULD	OwnerContributor	BAU
29	TFNFR37	Tool Usage by Module Owner	MAY	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: TFNFR6 - Category: Code Style - Resource & Data Order

For the definition of resources in the same file, the resources be depended on SHOULD come first, after them are the resources depending on others.

Resources that have dependencies SHOULD be defined close to each other.

See origin...

ID: TFNFR7 - Category: Code Style - count & for_each Use

We can use count and for_each to deploy multiple resources, but the improper use of count can lead to anti pattern.

You can use count to create some kind of resources under certain conditions, for example:

resource "azurerm_network_security_group" "this" {
  count               = local.create_new_security_group ? 1 : 0
  name                = coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
  resource_group_name = var.resource_group_name
  location            = local.location
  tags                = var.new_network_security_group_tags
}

The module’s owners MUST use map(xxx) or set(xxx) as resource’s for_each collection, the map’s key or set’s element MUST be static literals.

Good example:

resource "azurerm_subnet" "pair" {
  for_each             = var.subnet_map // `map(string)`, when user call this module, it could be: `{ "subnet0": "subnet0" }`, or `{ "subnet0": azurerm_subnet.subnet0.name }`
  name                 = "${each.value}"-pair
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.1.0/24"]
}

Bad example:

resource "azurerm_subnet" "pair" {
  for_each             = var.subnet_name_set // `set(string)`, when user use `toset([azurerm_subnet.subnet0.name])`, it would cause an error.
  name                 = "${each.value}"-pair
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.1.0/24"]
}

See origin...

ID: TFNFR8 - Category: Code Style - Resource & Data Block Orders

There are 3 types of assignment statements in a resource or data block: argument, meta-argument and nested block. The argument assignment statement is a parameter followed by =:

location = azurerm_resource_group.example.location

or:

tags = {
  environment = "Production"
}

Nested block is a assignment statement of parameter followed by {} block:

subnet {
  name           = "subnet1"
  address_prefix = "10.0.1.0/24"
}

Meta-arguments are assignment statements can be declared by all resource or data blocks. They are:

count
depends_on
for_each
lifecycle
provider

The order of declarations within resource or data blocks is:

All the meta-arguments SHOULD be declared on the top of resource or data blocks in the following order:

provider
count
for_each

Then followed by:

required arguments
optional arguments
required nested blocks
optional nested blocks

All ranked in alphabetical order.

These meta-arguments SHOULD be declared at the bottom of a resource block with the following order:

depends_on
lifecycle

The parameters of lifecycle block SHOULD show up in the following order:

create_before_destroy
ignore_changes
prevent_destroy

parameters under depends_on and ignore_changes are ranked in alphabetical order.

Meta-arguments, arguments and nested blocked are separated by blank lines.

dynamic nested blocks are ranked by the name comes after dynamic, for example:

  dynamic "linux_profile" {
    for_each = var.admin_username == null ? [] : ["linux_profile"]

    content {
      admin_username = var.admin_username

      ssh_key {
        key_data = replace(coalesce(var.public_ssh_key, tls_private_key.ssh[0].public_key_openssh), "\n", "")
      }
    }
  }

This dynamic block will be ranked as a block named linux_profile.

Code within a nested block will also be ranked following the rules above.

PS: You can use avmfix tool to reformat your code automatically.

See origin...

ID: TFNFR9 - Category: Code Style - Module Block Order

The meta-arguments below SHOULD be declared on the top of a module block with the following order:

source
version
count
for_each

blank lines will be used to separate them.

After them will be required arguments, optional arguments, all ranked in alphabetical order.

These meta-arguments below SHOULD be declared on the bottom of a resource block in the following order:

depends_on
providers

Arguments and meta-arguments SHOULD be separated by blank lines.

See origin...

ID: TFNFR10 - Category: Code Style - No Double Quotes in ignore_changes

The ignore_changes attribute MUST NOT be enclosed in double quotes.

Good example:

lifecycle {
    ignore_changes = [
      tags,
    ]
}

Bad example:

lifecycle {
    ignore_changes = [
      "tags",
    ]
}

See origin...

ID: TFNFR11 - Category: Code Style - Null Comparison Toggle

Sometimes we need to ensure that the resources created are compliant to some rules at a minimum extent, for example a subnet has to be connected to at least one network_security_group. The user SHOULD pass in a security_group_id and ask us to make a connection to an existing security_group, or want us to create a new security group.

Intuitively, we will define it like this:

variable "security_group_id" {
  type: string
}

resource "azurerm_network_security_group" "this" {
  count               = var.security_group_id == null ? 1 : 0
  name                = coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
  resource_group_name = var.resource_group_name
  location            = local.location
  tags                = var.new_network_security_group_tags
}

The disadvantage of this approach is if the user create a security group directly in the root module and use the id as a variable of the module, the expression which determines the value of count will contain an attribute from another resource, the value of this very attribute is “known after apply” at plan stage. Terraform core will not be able to get an exact plan of deployment during the “plan” stage.

You can’t do this:

resource "azurerm_network_security_group" "foo" {
  name                = "example-nsg"
  resource_group_name = "example-rg"
  location            = "eastus"
}

module "bar" {
  source = "xxxx"
  ...
  security_group_id = azurerm_network_security_group.foo.id
}

For this kind of parameters, wrapping with object type is RECOMMENDED:

variable "security_group" {
  type: object({
    id   = string
  })
  default     = null
}

The advantage of doing so is encapsulating the value which is “known after apply” in an object, and the object itself can be easily found out if it’s null or not. Since the id of a resource cannot be null, this approach can avoid the situation we are facing in the first example, like the following:

resource "azurerm_network_security_group" "foo" {
  name                = "example-nsg"
  resource_group_name = "example-rg"
  location            = "eastus"
}

module "bar" {
  source = "xxxx"
  ...
  security_group = {
    id = azurerm_network_security_group.foo.id
  }
}

This technique SHOULD be used under this use case only.

See origin...

ID: TFNFR12 - Category: Code Style - Dynamic for Optional Nested Objects

An example from the community:

resource "azurerm_kubernetes_cluster" "main" {
  ...
  dynamic "identity" {
    for_each = var.client_id == "" || var.client_secret == "" ? [1] : []

    content {
      type                      = var.identity_type
      user_assigned_identity_id = var.user_assigned_identity_id
    }
  }
  ...
}

Please refer to the coding style in the example. Nested blocks under conditions, MUST be declared as:

for_each = <condition> ? [<some_item>] : []

See origin...

ID: TFNFR13 - Category: Code Style - Default Values with coalesce/try

The following example shows how "${var.subnet_name}-nsg" SHOULD be used when var.new_network_security_group_name is null or ""

Good examples:

coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")

try(coalesce(var.new_network_security_group.name, "${var.subnet_name}-nsg"), "${var.subnet_name}-nsg")

Bad examples:

var.new_network_security_group_name == null ? "${var.subnet_name}-nsg" : var.new_network_security_group_name)

See origin...

ID: TFNFR16 - Category: Code Style - Variable Naming Rules

The naming of a variable SHOULD follow HashiCorp’s naming rule.

variable used as feature switches SHOULD apply a positive statement, use xxx_enabled instead of xxx_disabled. Avoid double negatives like !xxx_disabled.

Please use xxx_enabled instead of xxx_disabled as name of a variable.

See origin...

ID: TFNFR17 - Category: Code Style - Variables with Descriptions

The target audience of description is the module users.

For a newly created variable (Eg. variable for switching dynamic block on-off), it’s description SHOULD precisely describe the input parameter’s purpose and the expected data type. description SHOULD NOT contain any information for module developers, this kind of information can only exist in code comments.

For object type variable, description can be composed in HEREDOC format:

variable "kubernetes_cluster_key_management_service" {
  type: object({
    key_vault_key_id         = string
    key_vault_network_access = optional(string)
  })
  default     = null
  description = <<-EOT
  - `key_vault_key_id` - (Required) Identifier of Azure Key Vault key. See [key identifier format](https://learn.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name) for more details. When Azure Key Vault key management service is enabled, this field is required and must be a valid key identifier. When `enabled` is `false`, leave the field empty.
  - `key_vault_network_access` - (Optional) Network access of the key vault Network access of key vault. The possible values are `Public` and `Private`. `Public` means the key vault allows public access from all networks. `Private` means the key vault disables public access and enables private link. Defaults to `Public`.
EOT
}

See origin...

ID: TFNFR18 - Category: Code Style - Variables with Types

type MUST be defined for every variable. type SHOULD be as precise as possible, any MAY only be defined with adequate reasons.

Use bool instead of string or number for true/false
Use string for text
Use concrete object instead of map(any)

See origin...

ID: TFNFR19 - Category: Code Style - Sensitive Data Variables

If variable’s type is object and contains one or more fields that would be assigned to a sensitive argument, then this whole variable SHOULD be declared as sensitive = true, otherwise you SHOULD extract sensitive field into separated variable block with sensitive = true.

See origin...

ID: TFNFR20 - Category: Code Style - Non-Nullable Defaults for collection values

Nullable SHOULD be set to false for collection values (e.g. sets, maps, lists) when using them in loops. However for scalar values like string and number, a null value MAY have a semantic meaning and as such these values are allowed.

See origin...

ID: TFNFR21 - Category: Code Style - Discourage Nullability by Default

nullable = true MUST be avoided.

See origin...

ID: TFNFR22 - Category: Code Style - Avoid sensitive = false

sensitive = false MUST be avoided.

See origin...

ID: TFNFR23 - Category: Code Style - Sensitive Default Value Conditions

A default value MUST NOT be set for a sensitive input - e.g., a default password.

See origin...

ID: TFNFR24 - Category: Code Style - Handling Deprecated Variables

Sometimes we will find names for some variable are not suitable anymore, or a change SHOULD be made to the data type. We want to ensure forward compatibility within a major version, so direct changes are strictly forbidden. The right way to do this is move this variable to an independent deprecated_variables.tf file, then redefine the new parameter in variable.tf and make sure it’s compatible everywhere else.

Deprecated variable MUST be annotated as DEPRECATED at the beginning of the description, at the same time the replacement’s name SHOULD be declared. E.g.,

variable "enable_network_security_group" {
  type        = string
  default     = null
  description = "DEPRECATED, use `network_security_group_enabled` instead; Whether to generate a network security group and assign it to the subnet. Changing this forces a new resource to be created."
}

A cleanup of deprecated_variables.tf SHOULD be performed during a major version release.

See origin...

ID: TFNFR25 - Category: Code Style - Verified Modules Requirements

The terraform.tf file MUST only contain one terraform block.

The first line of the terraform block MUST define a required_version property for the Terraform CLI.

The required_version property MUST include a constraint on the minimum version of the Terraform CLI. Previous releases of the Terraform CLI can have unexpected behavior.

The required_version property MUST include a constraint on the maximum major version of the Terraform CLI. Major version releases of the Terraform CLI can introduce breaking changes and MUST be tested.

The required_version property constraint SHOULD use the ~> #.# or the >= #.#.#, < #.#.# format.

Note: You can read more about Terraform version constraints in the documentation.

Example terraform.tf file:

terraform {
  required_version = "~> 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.11"
    }
  }
}

See origin...

ID: TFNFR26 - Category: Code Style - Providers in required_providers

The terraform block in terraform.tf MUST contain the required_providers block.

Each provider used directly in the module MUST be specified with the source and version properties. Providers in the required_providers block SHOULD be sorted in alphabetical order.

Do not add providers to the required_providers block that are not directly required by this module. If submodules are used then each submodule SHOULD have its own versions.tf file.

The source property MUST be in the format of namespace/name. If this is not explicitly specified, it can cause failure.

The version property MUST include a constraint on the minimum version of the provider. Older provider versions may not work as expected.

The version property MUST include a constraint on the maximum major version. A provider major version release may introduce breaking change, so updates to the major version constraint for a provider MUST be tested.

The version property constraint SHOULD use the ~> #.# or the >= #.#.#, < #.#.# format.

Note: You can read more about Terraform version constraints in the documentation.

Good examples:

terraform {
  required_version = "~> 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
  }
}

terraform {
  required_version = ">= 1.6.6, < 2.0.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11.1, < 4.0.0"
    }
  }
}

terraform {
  required_version = ">= 1.6, < 2.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11, < 4.0"
    }
  }
}

Acceptable example (but not recommended):

terraform {
  required_version = "1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "3.11"
    }
  }
}

Bad example:

terraform {
  required_version = ">= 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11"
    }
  }
}

See origin...

ID: TFNFR27 - Category: Code Style - Provider Declarations in Modules

By rules, in the module code provider MUST NOT be declared. The only exception is when the module indeed need different instances of the same kind of provider(Eg. manipulating resources across different locations or accounts), you MUST declare configuration_aliases in terraform.required_providers. See details in this document.

provider block declared in the module MUST only be used to differentiate instances used in resource and data. Declaration of fields other than alias in provider block is strictly forbidden. It could lead to module users unable to utilize count, for_each or depends_on. Configurations of the provider instance SHOULD be passed in by the module users.

Good examples:

In verified module:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
      configuration_aliases = [ azurerm.alternate ]
    }
  }
}

In the root module where we call this verified module:

provider "azurerm" {
  features {}
}

provider "azurerm" {
  alias = "alternate"
  features {}
}

module "foo" {
  source = "xxx"
  providers = {
    azurerm = azurerm
    azurerm.alternate = azurerm.alternate
  }
}

Bad example:

In verified module:

provider "azurerm" {
  # Configuration options
  features {}
}

See origin...

ID: TFNFR30 - Category: Code Style - Handling Deprecated Outputs

Sometimes we notice that the name of certain output is not appropriate anymore, however, since we have to ensure forward compatibility in the same major version, its name MUST NOT be changed directly. It MUST be moved to an independent deprecated_outputs.tf file, then redefine a new output in output.tf and make sure it’s compatible everywhere else in the module.

A cleanup SHOULD be performed to deprecated_outputs.tf and other logics related to compatibility during a major version upgrade.

See origin...

ID: TFNFR31 - Category: Code Style - locals.tf for Locals Only

In locals.tf, file we could declare multiple locals blocks, but only locals blocks are allowed.

You MAY declare locals blocks next to a resource block or data block for some advanced scenarios, like making a fake module to execute some light-weight tests aimed at the expressions.

See origin...

ID: TFNFR33 - Category: Code Style - Precise Local Types

Precise local types SHOULD be used.

Good example:

{
  name = "John"
  age  = 52
}

Bad example:

{
  name = "John"
  age  = "52" # age should be number
}

See origin...

ID: TFNFR34 - Category: Code Style - Using Feature Toggles

A toggle variable MUST be used to allow users to avoid the creation of a new resource block by default if it is added in a minor or patch version.

E.g., our previous release was v1.2.1 and next release would be v1.3.0, now we’d like to submit a pull request which contains such new resource:

resource "azurerm_route_table" "this" {
  location            = local.location
  name                = coalesce(var.new_route_table_name, "${var.subnet_name}-rt")
  resource_group_name = var.resource_group_name
}

A user who’s just upgraded the module’s version would be surprised to see a new resource to be created in a newly generated plan file.

A better approach is adding a feature toggle to be turned off by default:

variable "create_route_table" {
  type     = bool
  default  = false
  nullable = false
}

resource "azurerm_route_table" "this" {
  count               = var.create_route_table ? 1 : 0
  location            = local.location
  name                = coalesce(var.new_route_table_name, "${var.subnet_name}-rt")
  resource_group_name = var.resource_group_name
}

See origin...

ID: TFNFR35 - Category: Code Style - Reviewing Potential Breaking Changes

Potential breaking(surprise) changes introduced by resource block

Adding a new resource without count or for_each for conditional creation, or creating by default
Adding a new argument assignment with a value other than the default value provided by the provider’s schema
Adding a new nested block without making it dynamic or omitting it by default
Renaming a resource block without one or more corresponding moved blocks
Change resource’s count to for_each, or vice versa

Terraform moved block could be your cure.

Potential breaking changes introduced by variable and output blocks

Deleting(Renaming) a variable
Changing type in a variable block
Changing the default value in a variable block
Changing variable’s nullable to false
Changing variable’s sensitive from false to true
Adding a new variable without default
Deleting an output
Changing an output’s value
Changing an output’s sensitive value

These changes do not necessarily trigger breaking changes, but they are very likely to, they MUST be reviewed with caution.

See origin...

ID: TFNFR36 - Category: Code Style - Setting prevent_deletion_if_contains_resources

From Terraform AzureRM 3.0, the default value of prevent_deletion_if_contains_resources in provider block is true. This will lead to an unstable test because the test subscription has some policies applied, and they will add some extra resources during the run, which can cause failures during destroy of resource groups.

Since we cannot guarantee our testing environment won’t be applied some Azure Policy Remediation Tasks in the future, for a robust testing environment, prevent_deletion_if_contains_resources SHOULD be explicitly set to false.

See origin...

ID: TFNFR37 - Category: Code Style - Tool Usage by Module Owner

newres is a command-line tool that generates Terraform configuration files for a specified resource type. It automates the process of creating variables.tf and main.tf files, making it easier to get started with Terraform and reducing the time spent on manual configuration.

Module owners MAY use newres when they’re trying to add new resource block, attribute, or nested block. They MAY generate the whole block along with the corresponding variable blocks in an empty folder, then copy-paste the parts they need with essential refactoring.

Inputs / Outputs

The content below is listed based on the following tags

Category-Inputs/OutputsClass-PatternLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR14	Data Types	SHOULD	OwnerContributor	BAU
2	SNFR22	Parameters/Variables for Resource IDs	MUST	OwnerContributor	BAU
3	SNFR26	Output - Parameters - Decorators	MUST	OwnerContributor	BAU
4	PMNFR5	Parameter/Variable Naming	SHOULD	OwnerContributor	BAU
5	TFFR2	Additional Terraform Outputs	SHOULD	OwnerContributor	BAU
6	TFNFR14	Not allowed variables	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR14 - Category: Inputs - Data Types

A module SHOULD use either: simple data types. e.g., string, int, bool.

Complex data types (objects, arrays, maps) when the language-compliant schema is defined.

See origin...

ID: SNFR22 - Category: Inputs - Parameters/Variables for Resource IDs

workspaceId is not descriptive enough and is ambiguous as to which ID is required to be input.

See origin...

ID: SNFR26 - Output-Parameters - Decorators

Output parameters MUST implement:

Decorators in Bicep such as description & secure (if sensitive)
Arguments in Terraform such as description & sensitive (if sensitive)

Output parameters

@description('The resourceId of your resource.')
output sampleResourceId string = sampleResource.id

@description('The key of your resource.')
@secure()
output sampleResourceKey string = sampleResource.key

# Resource output
output "foo" {
  description = "MyResource foo attribute"
  value = azurerm_resource_myresource.foo
}

# Output of a sensitive attribute
output "bar" {
  description = "MyResource bar attribute"
  value     = azurerm_resource_myresource.bar
  sensitive = true
}

See origin...

ID: PMNFR5 - Category: Inputs - Parameter/Variable Naming

Parameter/variable input names SHOULD contain the resource to which they pertain. E.g., virtualMachineSku/virtualmachine_sku

See origin...

ID: TFFR2 - Category: Outputs - Additional Terraform Outputs

Authors SHOULD NOT output entire resource objects as these may contain sensitive outputs and the schema can change with API or provider versions.
Instead, authors SHOULD output the computed attributes of the resource as discreet outputs.
This kind of pattern protects against provider schema changes and is known as an anti-corruption layer.

Remember, you SHOULD NOT output values that are already inputs (other than name).

E.g.,

# Resource output, computed attribute.
output "foo" {
  description = "MyResource foo attribute"
  value = azurerm_resource_myresource.foo
}

# Resource output for resources that are deployed using `for_each`. Again only computed attributes.
output "childresource_foos" {
  description = "MyResource children's foo attributes"
  value = {
    for key, value in azurerm_resource_mychildresource : key => value.foo
  }
}

# Output of a sensitive attribute
output "bar" {
  description = "MyResource bar attribute"
  value     = azurerm_resource_myresource.bar
  sensitive = true
}

See origin...

ID: TFNFR14 - Category: Inputs - Not allowed variables

Since Terraform 0.13, count, for_each and depends_on are introduced for modules, module development is significantly simplified. Module’s owners MUST NOT add variables like enabled or module_depends_on to control the entire module’s operation. Boolean feature toggles are acceptable however.

Testing

The content below is listed based on the following tags

Category-TestingClass-PatternLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR1	Prescribed Tests	MUST	OwnerContributor	BAU
2	SNFR2	E2E Testing	MUST	OwnerContributor	BAU
3	SNFR3	AVM Compliance Tests	MUST	OwnerContributor	Initial
4	SNFR4	Unit Tests	SHOULD	OwnerContributor	BAU
5	SNFR5	Upgrade Tests	SHOULD	OwnerContributor	BAU
6	SNFR6	Static Analysis/Linting Tests	MUST	OwnerContributor	BAU
7	SNFR7	Idempotency Tests	MUST	OwnerContributor	BAU
8	SNFR24	Testing Child, Extension & Interface Resources	MUST	OwnerContributor	BAU
9	TFNFR5	Test Tooling	MUST	OwnerContributor	BAU
10	TFNFR15	Variable Definition Order	SHOULD	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR1 - Category: Testing - Prescribed Tests

Modules MUST use the prescribed tooling and testing frameworks defined in the language specific specs.

See origin...

ID: SNFR2 - Category: Testing - E2E Testing

Each test MUST run and complete without user inputs successfully, for automation purposes.

Each test MUST also destroy/clean-up its resources and test dependencies following a run.

Tip

To see a directory and file structure for a module, see the language specific contribution guide.

Resources/Dependencies Required for E2E Tests

It is likely that to complete E2E tests, a number of resources will be required as dependencies to enable the tests to pass successfully. Some examples:

When testing the Diagnostic Settings interface for a Resource Module, you will need an existing Log Analytics Workspace to be able to send the logs to as a destination.
When testing the Private Endpoints interface for a Resource Module, you will need an existing Virtual Network, Subnet and Private DNS Zone to be able to complete the Private Endpoint deployment and configuration.

Module owners MUST:

Create the required resources that their module depends upon in the test file/directory
- They MUST either use:
  - Simple/native resource declarations/definitions in their respective IaC language,
    OR
  - Another already published AVM Module that MUST be pinned to a specific published version.
    - They MUST NOT use any local directory path references or local copies of AVM modules in their own modules test directory.

➕ Terraform & Bicep Log Analytics Workspace examples using simple/native declarations for use in E2E tests

Terraform

resource "azurerm_resource_group" "example" {
  name     = "rsg-test-001"
  location = "West Europe"
}

resource "azurerm_log_analytics_workspace" "example" {
  name                = "law-test-001"
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  sku                 = "PerGB2018"
  retention_in_days   = 30
}

Bicep

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2021-12-01-preview' = {
  name: 'law-test-001'
  location: resourceGroup().location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
    retentionInDays: 30
  }
}

Skipping Deployments (SHOULD NOT)

Note

A skipped test case is still added to the ‘Usage Examples’ section of the module’s readme and should be manually validated in regular intervals.

Details for use in E2E tests

You MUST add a note to the tests metadata description, which explains the excemption.

Sample filecontent:

The test is skipped, as only one instance of this service can be deployed to a subscription.

Note

For resource modules, the ‘defaults’ and ‘waf-aligned’ tests can’t be skipped.

The deployment of a test can be skipped by adding a .e2eignore file into a test folder (e.g. /examples/<testname>).

See origin...

ID: SNFR3 - Category: Testing - AVM Compliance Tests

Modules MUST pass all tests that ensure compliance to AVM specifications. These tests MUST pass before a module version can be published.

Important

Please note these are still under development at this time and will be published and available soon for module owners.

See origin...

ID: SNFR4 - Category: Testing - Unit Tests

Unit Tests test specific module functionality, without deploying resources. Used on more complex modules. In Bicep and Terraform these live in tests/unit.

See origin...

ID: SNFR5 - Category: Testing - Upgrade Tests

Modules SHOULD implement upgrade testing to ensure new features are implemented in a non-breaking fashion on non-major releases.

See origin...

ID: SNFR6 - Category: Testing - Static Analysis/Linting Tests

Modules MUST use static analysis, e.g., linting, security scanning (PSRule, tflint, etc.). These tests MUST pass before a module version can be published.

There may be differences between languages in linting rules standards, but the AVM core team will try to close these and bring them into alignment over time.

See origin...

ID: SNFR7 - Category: Testing - Idempotency Tests

Modules MUST implement idempotency end-to-end (deployment) testing. E.g. deploying the module twice over the top of itself.

Modules SHOULD pass the idempotency test, as we are aware that there are some exceptions where they may fail as a false-positive or legitimate cases where a resource cannot be idempotent.

For example, Virtual Machine Image names must be unique on each resource creation/update.

See origin...

ID: SNFR24 - Category: Testing - Testing Child, Extension & Interface Resources

These MAY be tested in a separate E2E test and DO NOT have to be tested in each E2E test.

See origin...

ID: TFNFR5 - Category: Testing - Test Tooling

Module owners MUST use the below tooling for unit/linting/static/security analysis tests. These are also used in the AVM Compliance Tests.

Terraform
- terraform <validate/fmt/test>
terrafmt
Checkov
tflint (with azurerm ruleset)
Go
- Some tests are provided as part of the AVM Compliance Tests, but you are free to also use Go for your own tests.

See origin...

ID: TFNFR15 - Category: Code Style - Variable Definition Order

Input variables SHOULD follow this order:

All required fields, in alphabetical order
All optional fields, in alphabetical order

A variable without default value is a required field, otherwise it’s an optional one.

Documentation

The content below is listed based on the following tags

Category-DocumentationClass-PatternLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR15	Automatic Documentation Generation	MUST	OwnerContributor	BAU
2	SNFR16	Examples/E2E	MUST	OwnerContributor	BAU
3	TFNFR1	Descriptions	MUST	OwnerContributor	BAU
4	TFNFR2	Module Documentation Generation	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR15 - Category: Documentation - Automatic Documentation Generation

README documentation MUST be automatically/programmatically generated. MUST include the sections as defined in the language specific requirements BCPNFR2, TFNFR2.

See origin...

ID: SNFR16 - Category: Documentation - Examples/E2E

An examples/e2e directory MUST exist to provide named scenarios for module deployment.

See origin...

ID: TFNFR1 - Category: Documentation - Descriptions

Where descriptions for variables and outputs spans multiple lines. The description MAY provide variable input examples for each variable using the HEREDOC format and embedded markdown.

Example:

  variable "my_complex_input" {
    type = map(object({
      param1 = string
      param2 = optional(number, null)
    }))
    description = <<DESCRIPTION
  A complex input variable that is a map of objects.
  Each object has two attributes:
  
  - `param1`: A required string parameter.
  - `param2`: (Optional) An optional number parameter.
  
  Example Input:
  
  ```terraform
  my_complex_input = {
    "object1" = {
      param1 = "value1"
      param2 = 2
    }
    "object2" = {
      param1 = "value2"
    }
  }
  ```
  DESCRIPTION
  }

See origin...

ID: TFNFR2 - Category: Documentation - Module Documentation Generation

Terraform modules documentation MUST be automatically generated via Terraform Docs.

A file called .terraform-docs.yml MUST be present in the root of the module and have the following content:

  ---
  ### To generate the output file to partially incorporate in the README.md,
  ### Execute this command in the Terraform module's code folder:
  # terraform-docs -c .terraform-docs.yml .
  
  formatter: "markdown document" # this is required
  
  version: "0.16.0"
  
  header-from: "_header.md"
  footer-from: "_footer.md"
  
  recursive:
    enabled: false
    path: modules
  
  sections:
    hide: []
    show: []
  
  content: |-
    {{ .Header }}    
  
    <!-- markdownlint-disable MD033 -->
    {{ .Requirements }}
  
    {{ .Providers }}
  
    {{ .Resources }}
  
    <!-- markdownlint-disable MD013 -->
    {{ .Inputs }}
  
    {{ .Outputs }}
  
    {{ .Modules }}
  
    {{ .Footer }}
  
  output:
    file: README.md
    mode: replace
    template: |-
      <!-- BEGIN_TF_DOCS -->
      {{ .Content }}
      <!-- END_TF_DOCS -->      
  output-values:
    enabled: false
    from: ""
  
  sort:
    enabled: true
    by: required
  
  settings:
    anchor: true
    color: true
    default: true
    description: false
    escape: true
    hide-empty: false
    html: true
    indent: 2
    lockfile: true
    read-comments: true
    required: true
    sensitive: true
    type: true

Release / Publishing

The content below is listed based on the following tags

Category-Release/PublishingClass-PatternLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR17	Semantic Versioning	MUST	OwnerContributor	BAU
2	SNFR18	Breaking Changes	SHOULD	OwnerContributor	BAU
3	SNFR19	Registries Targeted	MUST	OwnerContributor	BAU
4	SNFR21	Cross Language Collaboration	SHOULD	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR17 - Category: Release - Semantic Versioning

Important

See the Bicep Contribution Guide for more information.

Modules MUST use semantic versioning (aka semver) for their versions and releases in accordance with: Semantic Versioning 2.0.0

For example all modules should be released using a semantic version that matches this pattern: X.Y.Z

X == Major Version
Y == Minor Version
Z == Patch Version

Module versioning before first Major version release `1.0.0`

Initially modules MUST be released as version 0.1.0 and incremented via Minor and Patch versions only until the AVM Core Team are confident the AVM specifications are mature enough and appropriate CI test coverage is in place, plus the module owner is happy the module has been “road tested” and is now stable enough for its first Major release of version 1.0.0.
Note
Releasing as version 0.1.0 initially and only incrementing Minor and Patch versions allows the module owner to make breaking changes more easily and frequently as it’s still not an official Major/Stable release. 👍
Until first Major version 1.0.0 is released, given a version number X.Y.Z:
- X Major version MUST NOT be bumped.
- Y Minor version MUST be bumped when introducing breaking changes (which would normally bump Major after 1.0.0 release) or feature updates (same as it will be after 1.0.0 release).
- Z Patch version MUST be bumped when introducing non-breaking, backward compatible bug fixes (same as it will be after 1.0.0 release).

See origin...

ID: SNFR18 - Category: Release - Breaking Changes

A module SHOULD avoid breaking changes, e.g., deprecating inputs vs. removing. If you need to implement changes that cause a breaking change, the major version should be increased.

Info

Tip

See the language specific examples to find out how you can deal with deprecations in AVM modules.

Bicep

See origin...

ID: SNFR19 - Category: Publishing - Registries Targeted

Modules MUST be published to their respective language public registries.

Bicep = Bicep Public Module Registry
- Within the avm directory
Terraform = HashiCorp Terraform Registry

Tip

See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

See origin...

ID: SNFR21 - Category: Publishing - Cross Language Collaboration

Terraform Resource Module Specifications

Contribution / Support

The content below is listed based on the following tags

Category-Contribution/SupportClass-ResourceLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR8	Module Owner(s) GitHub	MUST	Owner	Initial
2	SNFR20	GitHub Teams Only	MUST	Owner	Initial
3	SNFR9	AVM & PG Teams GitHub Repo Permissions	MUST	Owner	Initial
4	SNFR10	MIT Licensing	MUST	Owner	Initial
5	SNFR11	Issues Response Times	MUST	OwnerContributor	BAU
6	SNFR12	Versions Supported	MUST	Owner	BAU
7	SNFR23	GitHub Repo Labels	MUST	Owner	BAU
8	PMNFR4	Missing Resource Module(s)	MUST	OwnerContributor	BAU
9	TFNFR3	GitHub Repo Branch Protection	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR8 - Category: Contribution/Support - Module Owner(s) GitHub

A module MUST have an owner that is defined and managed by a GitHub Team in the Azure GitHub organization.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

See origin...

ID: SNFR20 - Category: Contribution/Support - GitHub Teams Only

All GitHub repositories that AVM module are published from and hosted within MUST only assign GitHub repository permissions to GitHub teams only.

Each module MUST have separate GitHub teams assigned for module owners AND module contributors respectively. These GitHub teams MUST be created in the Azure organization in GitHub.

There MUST NOT be any GitHub repository permissions assigned to individual users.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

Important

Naming Convention

The naming convention for the GitHub teams MUST follow the below pattern:

<hyphenated module name>-module-owners-<bicep/tf> - to be assigned as the GitHub repository’s Module Owners team
<hyphenated module name>-module-contributors-<bicep/tf> - to be assigned as the GitHub repository’s Module Contributors team

Note

The naming convention for Bicep modules is slightly different than the naming convention for their respective GitHub teams.

Segments:

<hyphenated module name> == the AVM Module’s name, with each segment separated by dashes, i.e., avm-res-<resource provider>-<ARM resource type>
- See RMNFR1 for AVM Resource Module Naming
- See PMNFR1 for AVM Pattern Module Naming
module-owners or module-contributors == the role the GitHub Team is assigned to
<bicep/tf> == the language the module is written in

Examples:

avm-res-compute-virtualmachine-module-owners-bicep
avm-res-compute-virtualmachine-module-contributors-tf

Add Team Members

All officially documented module owner(s) MUST be added to the -module-owners- team. The -module-owners- team MUST NOT have any other members.

Any additional module contributors whom the module owner(s) agreed to work with MUST be added to the -module-contributors- team.

Grant Permissions - Bicep

Team memberships

Note

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<hyphenated module name>-module-owners-bicep`	AVM Bicep Module Owners - <module name>	Write	Assignment to the `avm-technical-reviewers-bicep` parent team.	Need to work in a fork.
`<hyphenated module name>-module-contributors-bicep`	AVM Bicep Module Contributors - <module name>	Triage	`avm-module-contributors-bicep` parent team.	Need to work in a fork.

Examples - GitHub teams required for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

avm-res-network-virtualnetwork-module-owners-bicep –> assign to the avm-technical-reviewers-bicep parent team.
avm-res-network-virtualnetwork-module-contributors-bicep –> assign to the avm-module-contributors-bicep parent team.

Tip

Direct link to create a new GitHub team and assign it to its parent: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Follow the guidance above (see the Permissions granted through column in the table above).
Team visibility: Visible
Team notifications: Enabled

CODEOWNERS file

As part of the “initial Pull Request” (that publishes the first version of the module), module owners MUST add an entry to the CODEOWNERS file in the BRM repository (here).

Note

Through this approach, the AVM core team will grant review permission to module owners as part of the standard PR review process.

Every CODEOWNERS entry (line) MUST include the following segments separated by a single whitespace character:

Path of the module, relative to the repo’s root, e.g.: /avm/res/network/virtual-network/
The -module-owners-team, with the @Azure/ prefix, e.g., @Azure/avm-res-network-virtualnetwork-module-owners-bicep
The GitHub team of the AVM Bicep reviewers, with the @Azure/ prefix, i.e., @Azure/avm-module-reviewers-bicep

Example - CODEOWNERS entry for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

/avm/res/network/virtual-network/ @Azure/avm-res-network-virtualnetwork-module-owners-bicep @Azure/avm-module-reviewers-bicep

Grant Permissions - Terraform

Module owners MUST assign the -module-owners-and -module-contributors- teams the necessary permissions on their Terraform module repository per the guidance below.

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<module name>-module-owners-tf`	AVM Terraform Module Owners - <module name>	Admin	Direct assignment to repo	Module owner can decide whether they want to work in a branch local to the repo or in a fork.
`<module name>-module-contributors-tf`	AVM Terraform Module Contributors - <module name>	Write	Direct assignment to repo	Need to work in a fork.

Tip

Direct link to create a new GitHub team: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Do not assign the team to any parent team.
Team visibility: Visible
Team notifications: Enabled

See origin...

ID: SNFR9 - Category: Contribution/Support - AVM & PG Teams GitHub Repo Permissions

A module owner MUST make the following GitHub teams in the Azure GitHub organization admins on the GitHub repo of the module in question:

Bicep

@Azure/avm-core-team-technical-bicep = AVM Core Team
@Azure/bicep-admins = Bicep PG team

Note

These required GitHub teams are already associated to the BRM repository and have the required permissions.

Terraform

@Azure/avm-core-team-technical-terraform = AVM Core Team
@Azure/terraform-avm = Terraform PG

Important

Module owners MUST assign these GitHub teams as admins on the GitHub repo of the module in question.

For detailed steps, please follow this guidance.

See origin...

ID: SNFR10 - Category: Contribution/Support - MIT Licensing

A module MUST be published with the MIT License in the Azure GitHub organization.

See origin...

ID: SNFR11 - Category: Contribution/Support - Issues Response Times

A module owner MUST respond to logged issues as defined in the support statement. See Module Support for more information.

See origin...

ID: SNFR12 - Category: Contribution/Support - Versions Supported

Only the latest released version of a module MUST be supported.

This avoids AVM Module owners from having to maintain multiple major release versions.

See origin...

ID: SNFR23 - Category: Contribution/Support - GitHub Repo Labels

GitHub repositories where modules are held MUST use the below labels and SHOULD not use any additional labels:

➕ AVM Standard GitHub Labels

These labels are available in a CSV file from here

Name	Description	HEX
AZD 🧑‍💻	These modules are requested/used by the AZD team.	`E0BFFA`
Needs: Attention 👋	Reply has been added to issue, maintainer to review	`E99695`
Needs: Immediate Attention ‼️	Immediate attention of module owner / AVM team is needed	`FF0000`
Needs: Author Feedback 👂	Awaiting feedback from the issue/PR author	`F18A07`
Needs: External Changes ⚒️	When an issue/PR requires changes that are outside of the control of the module. e.g. to an RP.	`DE389D`
Needs: More Evidence ⚖	We are looking for more evidence to make a decision on this	`F64872`
Needs: Triage 🔍	Maintainers need to triage still	`FBCA04`
Needs: Module Owner 📣	In the AVM repository: this module needs an owner to develop or maintain it. In the BRM repository: the module owner needs to review a PR.	`FF0019`
Needs: Module Contributor 📣	This module needs secondary owner(s) or contributor(s) to develop or maintain it	`C95474`
Needs: Core Team 🧞‍♂️	This item needs the AVM Core Team to review it	`DB4503`
Status: Awaiting Release To Be Cut ✂️	This is fixed in the main branch but not in the latest release, will be fixed with next release cut	`800080`
Status: Do Not Merge ⛔	Do not merge PRs with this label attached as they are not ready or aligned to future direction etc.	`8B4513`
Status: External Contribution 🌍	This is being worked on by someone outside of the AVM module owners/contributors or AVM core team	`D8FA2C`
Status: Fixed ✅	Auto label applied when issue fixed by merged PR	`90EE90`
Status: Help Wanted 🆘	Extra attention is needed	`FF4500`
Status: In Triage 🔍	Picked up for triaging by an AVM core team member	`D4AF37`
Status: In PR 👉	This is when an issue is due to be fixed in an open PR	`EDEDED`
Status: Invalid ❌	This doesn't seem right	`E4E669`
Status: Long Term ⏳	We will do it, but will take a longer amount of time due to complexity/priorities	`B60205`
Status: No Recent Activity 💤	When an issue/PR has not been modified for X amount of days	`808080`
Status: Won't Fix 💔	This will not be worked on	`FFFFFF`
Status: Owners Identified 🤘	This module has its owners identified	`FBEF2A`
Status: Module Available 🟢	The module is published	`C8E6C9`
Status: Module Deprecated 🔴	This is a request to deprecate a module	`000000`
Status: Module Orphaned 🟡	The module has no owner and is therefore orphaned at this time	`F4A460`
Status: Ready For Repository Creation 📝	This module is approved and the owner is ready for the repository to be created (Terraform)	`136A41`
Status: Repository Created 📄	This module has had it's repository created and configured ready for owner contribution (Terraform)	`27AB03`
Status: Response Overdue 🚩	When an issue/PR has not been responded to for X amount of days	`850000`
Status: Looking For Assistance 🦆	This item is looking for anyone to help develop the code and submit a PR for resolution	`03FCC2`
Type: Bug 🐛	Something isn't working	`D73A4A`
Type: CI 🚀	This issue is related to the AVM CI	`74CFB0`
Type: Documentation 📄	Improvements or additions to documentation	`0075CA`
Type: Duplicate 🤲	This issue or pull request already exists	`CFD3D7`
Type: Feature Request ➕	New feature or request	`A2EEEF`
Type: Hygiene 🧹	things related to testing, issue triage etc.	`17016A`
Type: New Module Proposal 💡	A new module for AVM is being proposed	`ADD8E6`
Type: Question/Feedback 🙋‍♀️	Further information is requested or just some feedback	`CB6BA2`
Type: Security Bug 🔒	This is a security bug	`FFFF00`
Type: AVM 🅰️ ✌️ ⓜ️	This is an AVM related issue	`F0FFFF`
Language: Terraform 🌐	This is related to the Terraform IaC language	`7740B6`
Language: Bicep 💪	This is related to the Bicep IaC language	`1D73B3`
Class: Resource Module 📦	This is a resource module	`D3D3D3`
Class: Pattern Module 📦	This is a pattern module	`A9A9A9`
Class: Utility Module 📦	This is a utility module	`CAD1DE`
Class: Child Module 📦	This is a child module	`5E5186`

To help apply these to a module GitHub repository you can use the below PowerShell script:

➕ Set-AvmGitHubLabels.ps1

For most scenario this is the command you’ll need to call the below PowerShell script with, replacing the value for RepositoryName:

  Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -CreateCsvLabelExports $false -NoUserPrompts $true

```shell
# Linux / MacOs
# For Windows replace $PWD with your the local path or your repository
#
docker run -it -v $PWD:/repo -w /repo mcr.microsoft.com/powershell pwsh -Command '
    #Invoke-WebRequest -Uri "https://azure.github.io/Azure-Verified-Modules/scripts/Set-AvmGitHubLabels.ps1" -OutFile "Set-AvmGitHubLabels.ps1"
    $gh_version = "2.44.1"
    Invoke-WebRequest -Uri "https://github.com/cli/cli/releases/download/v2.44.1/gh_2.44.1_linux_amd64.tar.gz" -OutFile "gh_$($gh_version)_linux_amd64.tar.gz"
    apt-get update && apt-get install -y git
    tar -xzf "gh_$($gh_version)_linux_amd64.tar.gz"
    ls -lsa
    mv "gh_$($gh_version)_linux_amd64/bin/gh" /usr/local/bin/
    rm "gh_$($gh_version)_linux_amd64.tar.gz" && rm -rf "gh_$($gh_version)_linux_amd64"
    gh --version
    ls -lsa
    gh auth login
    $OrgProject = "Azure/terraform-azurerm-avm-res-kusto-cluster"
    gh auth status
    ./Set-AvmGitHubLabels.ps1 -RepositoryName $OrgProject -CreateCsvLabelExports $false -NoUserPrompts $true

  '
```

Full Script:

These Set-AvmGitHubLabels.ps1 can be downloaded from here.

  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "", Justification = "Coloured output required in this script")]
  
  <#
  .SYNOPSIS
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
  .DESCRIPTION
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
    By default, the script will remove all pre-existing labels and apply the AVM labels. However, this can be changed by using the -RemoveExistingLabels parameter and setting it to $false. The tool will also output the labels that exist in the repository before and after the script has run to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter.
  
    The AVM labels to be created are documented here: TBC
  
  .NOTES
    Please ensure you have specified the GitHub repositry correctly. The script will prompt you to confirm the repository name before proceeding.
  
  .COMPONENT
    You must have the GitHub CLI installed and be authenticated to a GitHub account with access to the repository you are applying the labels to before running this script.
  
  .LINK
    TBC
  
  .Parameter RepositoryName
    The name of the GitHub repository to apply the labels to.
  
  .Parameter RemoveExistingLabels
    If set to $true, the default value, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will not remove any pre-existing labels.
  
  .Parameter UpdateAndAddLabelsOnly
    If set to $true, the default value, the script will only update and add labels to the repository specified in -RepositoryName. If set to $false, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
  .Parameter OutputDirectory
    The directory to output the pre-existing and post-existing labels to in a CSV file. The default value is the current directory.
  
  .Parameter CreateCsvLabelExports
    If set to $true, the default value, the script will output the pre-existing and post-existing labels to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter. If set to $false, the script will not output the pre-existing and post-existing labels to a CSV file.
  
  .Parameter GitHubCliLimit
    The maximum number of labels to return from the GitHub CLI. The default value is 999.
  
  .Parameter LabelsToApplyCsvUri
    The URI to the CSV file containing the labels to apply to the GitHub repository. The default value is https://raw.githubusercontent.com/jtracey93/label-source/main/avm-github-labels.csv.
  
  .Parameter NoUserPrompts
    If set to $true, the default value, the script will not prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
    This is useful for running the script in automation workflows
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and remove all pre-existing labels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false -CreateCsvLabelExports $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name. Finally, use a custom CSV file hosted on the internet to create the labels from.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false -CreateCsvLabelExports $false -LabelsToApplyCsvUri "https://example.com/csv/avm-github-labels.csv"
  
  #>
  
  #Requires -PSEdition Core
  
  [CmdletBinding()]
  param (
    [Parameter(Mandatory = $true)]
    [string]$RepositoryName,
  
    [Parameter(Mandatory = $false)]
    [bool]$RemoveExistingLabels = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$UpdateAndAddLabelsOnly = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$CreateCsvLabelExports = $true,
  
    [Parameter(Mandatory = $false)]
    [string]$OutputDirectory = (Get-Location),
  
    [Parameter(Mandatory = $false)]
    [int]$GitHubCliLimit = 999,
  
    [Parameter(Mandatory = $false)]
    [string]$LabelsToApplyCsvUri = "https://azure.github.io/Azure-Verified-Modules/governance/avm-standard-github-labels.csv",
  
    [Parameter(Mandatory = $false)]
    [bool]$NoUserPrompts = $false
  )
  
  # Check if the GitHub CLI is installed
  $GitHubCliInstalled = Get-Command gh -ErrorAction SilentlyContinue
  if ($null -eq $GitHubCliInstalled) {
    throw "The GitHub CLI is not installed. Please install the GitHub CLI and try again."
  }
  Write-Host "The GitHub CLI is installed..." -ForegroundColor Green
  
  # Check if GitHub CLI is authenticated
  $GitHubCliAuthenticated = gh auth status
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubCliAuthenticated -ForegroundColor Red
    throw "Not authenticated to GitHub. Please authenticate to GitHub using the GitHub CLI, `gh auth login`, and try again."
  }
  Write-Host "Authenticated to GitHub..." -ForegroundColor Green
  
  # Check if GitHub repository name is valid
  $GitHubRepositoryNameValid = $RepositoryName -match "^[a-zA-Z0-9-]+/[a-zA-Z0-9-]+$"
  if ($false -eq $GitHubRepositoryNameValid) {
    throw "The GitHub repository name $RepositoryName is not valid. Please check the repository name and try again. The format must be <OrgName>/<RepoName>"
  }
  
  # List GitHub repository provided and check it exists
  $GitHubRepository = gh repo view $RepositoryName
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubRepository -ForegroundColor Red
    throw "The GitHub repository $RepositoryName does not exist. Please check the repository name and try again."
  }
  Write-Host "The GitHub repository $RepositoryName exists..." -ForegroundColor Green
  
  # PRE - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($RemoveExistingLabels -or $UpdateAndAddLabelsOnly) {
    Write-Host "Getting the current GitHub repository (pre) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels -and $CreateCsvLabelExports -eq $true) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Pre-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (pre) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # Remove all pre-existing labels if -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels
  if ($null -ne $GitHubRepositoryLabels) {
    $GitHubRepositoryLabelsJson = $GitHubRepositoryLabels | ConvertFrom-Json
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $false -and $UpdateAndAddLabelsOnly -eq $false) {
      $RemoveExistingLabelsConfirmation = Read-Host "Are you sure you want to remove all $($GitHubRepositoryLabelsJson.Count) pre-existing labels from $($RepositoryName)? (Y/N)"
      if ($RemoveExistingLabelsConfirmation -eq "Y") {
        Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
        $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
          Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
          gh label delete -R $RepositoryName $_.name --yes
        }
      }
    }
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $true -and $UpdateAndAddLabelsOnly -eq $false) {
      Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
        Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
        gh label delete -R $RepositoryName $_.name --yes
      }
    }
  }
  if ($null -eq $GitHubRepositoryLabels) {
    Write-Host "No pre-existing labels to remove or not selected to be removed from $RepositoryName..." -ForegroundColor Magenta
  }
  
  # Check LabelsToApplyCsvUri is valid and contains a CSV content
  Write-Host "Checking $LabelsToApplyCsvUri is valid..." -ForegroundColor Yellow
  $LabelsToApplyCsvUriValid = $LabelsToApplyCsvUri -match "^https?://"
  if ($false -eq $LabelsToApplyCsvUriValid) {
    throw "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is not valid. Please check the URI and try again. The format must be a valid URI."
  }
  Write-Host "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is valid..." -ForegroundColor Green
  
  # Create AVM lables from the AVM labels CSV file stored on the web using the convertfrom-csv cmdlet
  $avmLabelsCsv = Invoke-WebRequest -Uri $LabelsToApplyCsvUri | ConvertFrom-Csv
  
  # Check if the AVM labels CSV file contains the following columns: Name, Description, HEX
  $avmLabelsCsvColumns = $avmLabelsCsv | Get-Member -MemberType NoteProperty | Select-Object -ExpandProperty Name
  $avmLabelsCsvColumnsValid = $avmLabelsCsvColumns -contains "Name" -and $avmLabelsCsvColumns -contains "Description" -and $avmLabelsCsvColumns -contains "HEX"
  if ($false -eq $avmLabelsCsvColumnsValid) {
    throw "The labels CSV file does not contain the required columns: Name, Description, HEX. Please check the CSV file and try again. It contains the following columns: $avmLabelsCsvColumns"
  }
  Write-Host "The labels CSV file contains the required columns: Name, Description, HEX" -ForegroundColor Green
  
  # Create the AVM labels in the GitHub repository
  Write-Host "Creating/Updating the $($avmLabelsCsv.Count) AVM labels in $RepositoryName..." -ForegroundColor Yellow
  $avmLabelsCsv | ForEach-Object {
    if ($GitHubRepositoryLabelsJson.name -contains $_.name) {
      Write-Host "The label $($_.name) already exists in $RepositoryName. Updating the label to ensure description and color are consitent..." -ForegroundColor Magenta
      gh label create -R $RepositoryName "$($_.name)" -c $_.HEX -d $($_.Description) --force
    }
    else {
      Write-Host "The label $($_.name) does not exist in $RepositoryName. Creating label $($_.name) in $RepositoryName..." -ForegroundColor Cyan
      gh label create -R $RepositoryName "$($_.Name)" -c $_.HEX -d $($_.Description) --force
    }
  }
  
  # POST - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($CreateCsvLabelExports -eq $true) {
    Write-Host "Getting the current GitHub repository (post) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Post-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (post) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # If -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels check that only the avm labels exist in the repository
  if ($RemoveExistingLabels -eq $true -and ($RemoveExistingLabelsConfirmation -eq "Y" -or $NoUserPrompts -eq $true) -and $UpdateAndAddLabelsOnly -eq $false) {
    Write-Host "Checking that only the AVM labels exist in $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
    $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
      if ($avmLabelsCsv.Name -notcontains $_.name) {
        throw "The label $($_.name) exists in $RepositoryName but is not in the CSV file."
      }
    }
    Write-Host "Only the CSV labels exist in $RepositoryName..." -ForegroundColor Green
  }
  
  Write-Host "The CSV labels have been created/updated in $RepositoryName..." -ForegroundColor Green

See origin...

ID: PMNFR4 - Category: Hygiene - Missing Resource Module(s)

An item MUST be logged onto as an issue on the AVM Central Repo (Azure/Azure-Verified-Modules) if a Resource Module does not exist for resources deployed by the pattern module.

Exception

If the Resource Module adds no value, see Resource Module functional requirement ID: RMFR2.

See origin...

ID: TFNFR3 - Category: Contribution/Support - GitHub Repo Branch Protection

Module owners MUST set a branch protection policy on their GitHub Repositories for AVM modules against their default branch, typically main, to do the following:

Requires a Pull Request before merging
Require approval of the most recent reviewable push
Dismiss stale pull request approvals when new commits are pushed
Require linear history
Prevents force pushes
Not allow deletions
Require CODEOWNERS review
Do not allow bypassing the above settings
Above settings MUST also be enforced to administrators

Tip

If you use the template repository as mentioned in the contribution guide, the above will automatically be set.

Telemetry

The content below is listed based on the following tags

Category-TelemetryClass-ResourceLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SFR3	Deployment/Usage Telemetry	MUST	Owner	Initial
2	SFR4	Telemetry Enablement Flexibility	MUST	Owner	Initial

➕ See Specifications for this category

See origin...

ID: SFR3 - Category: Telemetry - Deployment/Usage Telemetry

Important

These will also be provided as a comment on the module proposal, once accepted, from the AVM core team.

Modules MUST provide the capability to collect deployment/usage telemetry as detailed in Telemetry further.

Telemetry Information Notice

Note

The following information notice is automatically added at the bottom of the README.md file of the module when

Bicep: Using the utilities/tools/Set-AVMModule.ps1 utility
Terraform: Executing the make docs command with the note and header ## Data Collection being placed in the module’s _footer.md beforehand

### Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the [repository](https://aka.ms/avm/telemetry). There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at <https://go.microsoft.com/fwlink/?LinkID=824704>. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Bicep

Important

The value you need to use for your module is defined in the related module index. You can look it up on the index pages for Resource Modules, Pattern Modules and Utility Modules.

The ARM deployment name used for the telemetry MUST follow the pattern and MUST be no longer than 64 characters in length: 46d3xbcp.<res/ptn>.<(short) module name>.<version>.<uniqueness>

<res/ptn> == AVM Resource or Pattern Module
<(short) module name> == The AVM Module’s, possibly shortened, name including the resource provider and the resource type, without;
- The prefixes: avm-res-
- The prefixes: avm-ptn-
<version> == The AVM Module’s MAJOR.MINOR version (only) with . (periods) replaced with - (hyphens), to allow simpler splitting of the ARM deployment name
<uniqueness> == This section of the ARM deployment name is to be used to ensure uniqueness of the deployment name.
- This is to cater for the following scenarios:
  - The module is deployed multiple times to the same:
    - Location/Region
    - Scope (Tenant, Management Group,Subscription, Resource Group)

Note

An example deployment name for the AVM Virtual Machine Resource Module would be: 46d3xbcp.res.compute-virtualmachine.1-2-3.eum3

An example deployment name for a shortened module name would be: 46d3xbcp.res.desktopvirtualization-appgroup.1-2-3.eum3

Tip

Terraform: Terraform uses a telemetry provider, the configuration of which is the same for every module and is included in the template repo.

General: See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

Terraform

The modtm telemetry provider is included in all Terraform modules and is enabled by default through the main.telemetry.tf file being automatically distributed from the template repo.

The modtm provider MUST be listed under the required_providers section in the module’s terraform.tf file using the following entry. This is also validated by the linter.

terraform {
  required_providers {
    # .. other required providers as needed
    modtm = {
      source = "Azure/modtm"
      version = "~> 0.3"
    }
  }
}

See origin...

ID: SFR4 - Category: Telemetry - Telemetry Enablement Flexibility

The telemetry enablement MUST be on/enabled by default, however this MUST be able to be disabled by a module consumer by setting the below parameter/variable value to false:

Bicep: enableTelemetry
Terraform: enable_telemetry

Note

This general specification can be modified for some use-cases, that are language specific:

Bicep

For cross-references in resource modules, the spec BCPFR7 also applies.

Terraform

Currently, no further requirements apply.

Naming / Composition

The content below is listed based on the following tags

Category-Naming/CompositionClass-ResourceLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SFR1	Preview Services	MUST	Owner	BAU
2	SFR2	WAF Aligned	SHOULD	Owner	BAU
3	SFR5	Availability Zones	MUST	Owner	Initial
4	SFR6	Data Redundancy	MUST	Owner	Initial
5	SNFR25	Resource Naming	MUST	Owner	Initial
6	RMFR1	Single Resource Only	MUST	OwnerContributor	BAU
7	RMFR2	No Resource Wrapper Modules	MUST	Owner	Initial
8	RMFR3	Resource Groups	MUST	OwnerContributor	BAU
9	RMFR4	AVM Consistent Feature & Extension Resources Value Add	MUST	OwnerContributor	BAU
10	RMFR5	AVM Consistent Feature & Extension Resources Value Add Interfaces/Schemas	MUST	OwnerContributor	BAU
11	RMFR8	Dependency on child and other resources	MUST	OwnerContributor	BAU
12	RMFR9	End-of-life resource versions	SHOULD	OwnerContributor	BAU
13	RMNFR1	Module Naming	MUST	Owner	Initial
14	RMNFR3	RP Collaboration	SHOULD	Owner	BAU
15	TFFR1	Cross-Referencing Modules	MUST	OwnerContributor	BAU
16	TFFR3	Providers - Permitted Versions	MUST	OwnerContributor	BAU
17	TFNFR4	Lower snake_casing	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SFR1 - Category: Composition - Preview Services

Modules MAY create/adopt public preview services and features at their discretion.

Preview API versions MAY be used when:

The resource/service/feature is GA but the only API version available for the GA resource/service/feature is a preview version
- For example, Diagnostic Settings (Microsoft.Insights/diagnosticSettings) the latest version of the API available with GA features, like Category Groups etc., is 2021-05-01-preview
- Otherwise the latest “non-preview” version of the API SHOULD be used

Preview services and features, SHOULD NOT be promoted and exposed, unless they are supported by the respective PG, and it’s documented publicly.

However, they MAY be exposed at the module owners discretion, but the following rules MUST be followed:

The description of each of the parameters/variables used for the preview service/feature MUST start with:
- “THIS IS A <PARAMETER/VARIABLE> USED FOR A PREVIEW SERVICE/FEATURE, MICROSOFT MAY NOT PROVIDE SUPPORT FOR THIS, PLEASE CHECK THE PRODUCT DOCS FOR CLARIFICATION”

See origin...

ID: SFR2 - Category: Composition - WAF Aligned

Well-Architected Framework (WAF)
Reliability Hub
Azure Proactive Resiliency Library (APRL)
- Only Product Group (PG) verified
Microsoft Defender for Cloud (MDFC)

They SHOULD NOT align to these recommendations when it requires an external dependency/resource to be deployed and configured and then associated to the resources in the module.

Alignment SHOULD prioritize best-practices and security over cost optimization, but MUST allow for these to be overridden by a module consumer easily, if desired.

Tip

Read the FAQ of What does AVM mean by “WAF Aligned”? for more detailed information and examples.

See origin...

ID: SFR5 - Category: Composition - Availability Zones

Modules that deploy zone-redundant resources MUST enable the spanning across as many zones as possible by default, typically all 3.

For both scenarios the modules MUST expose these configuration options via configurable parameters/variables.

Note

For information on the differences between zonal and zone-redundant services, see Availability zone service and regional support

See origin...

ID: SFR6 - Category: Composition - Data Redundancy

Note

For information on the data redundancy options in Azure, see Cross-region replication in Azure

See origin...

ID: SNFR25 - Category: Composition - Resource Naming

Module owners MUST also provide the ability for these default names, including the prefixes, to be overridden via a parameter/variable if the consumer wishes to.

Tip

If the resource does not have a documented abbreviation in Abbreviation examples for Azure resources, then the module owner is free to use a sensible prefix instead.

See origin...

ID: RMFR1 - Category: Composition - Single Resource Only

A resource module MUST only deploy a single instance of the primary resource, e.g., one virtual machine per instance.

Multiple instances of the module MUST be used to scale out.

See origin...

ID: RMFR2 - Category: Composition - No Resource Wrapper Modules

A resource module MUST add value by including additional features on top of the primary resource.

See origin...

ID: RMFR3 - Category: Composition - Resource Groups

A resource module MUST NOT create a Resource Group for resources that require them.

In the case that a Resource Group is required, a module MUST have an input (scope or variable):

In Bicep the targetScope MUST be set to resourceGroup or not specified (which means default to resourceGroup scope)
In Terraform the variable MUST be called resource_group_name

Scopes will be covered further in the respective language specific specifications.

See origin...

ID: RMFR4 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add

Resource modules support the following optional features/extension resources, as specified, if supported by the primary resource. The top-level variable/parameter names MUST be:

Optional Features/Extension Resources	Bicep Parameter Name	Terraform Variable Name	MUST/SHOULD
Diagnostic Settings	`diagnosticSettings`	`diagnostic_settings`	MUST
Role Assignments	`roleAssignments`	`role_assignments`	MUST
Resource Locks	`lock`	`lock`	MUST
Tags	`tags`	`tags`	MUST
Managed Identities (System / User Assigned)	`managedIdentities`	`managed_identities`	MUST
Private Endpoints	`privateEndpoints`	`private_endpoints`	MUST
Customer Managed Keys	`customerManagedKey`	`customer_managed_key`	MUST
Azure Monitor Alerts	`alerts`	`alerts`	SHOULD

Note

Tip

Make sure to checkout the language specific specifications for more info on this:

See origin...

ID: RMFR5 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add Interfaces/Schemas

See:

See origin...

ID: RMFR8 - Category: Composition - Dependency on child and other resources

A resource module MAY contain references to other resource modules, however MUST NOT contain references to non-AVM modules nor AVM pattern modules.

See BCPFR1 and TFFR1 for more information on this.

See origin...

ID: RMFR9 - Category: Composition - End-of-life resource versions

When a given version of an Azure resource used in a resource module reaches its end-of-life (EOL) and is no longer supported by Microsoft, the module owner SHOULD ensure that:

The module is aligned with these changes and only includes supported versions of the resource. This is typically achieved through the allowed values in the parameter that specifies the resource SKU or type.
The following notice is shown under the Notes section of the module’s readme.md. (If any related public announcement is available, it can also be linked to from the Notes section.):
“Certain versions of this Azure resource reached their end of life. The latest version of this module only includes supported versions of the resource. All unsupported versions have been removed from the related parameters.”
AND the related parameter’s description:
“Certain versions of this Azure resource reached their end of life. The latest version of this module only includes supported versions of the resource. All unsupported versions have been removed from this parameter.”

See origin...

ID: RMNFR1 - Category: Naming - Module Naming

Note

This will be updated quarterly, or ad-hoc as new RPs/ Resources are created and highlighted via a check failure.

Resource modules MUST follow the below naming conventions (all lower case):

Bicep Resource Module Naming

Naming convention: avm/res/<hyphenated resource provider name>/<hyphenated ARM resource type> (module name for registry)
Example: avm/res/compute/virtual-machine or avm/res/managed-identity/user-assigned-identity
Segments:
- res defines this is a resource module
- <hyphenated resource provider name> is the resource provider’s name after the Microsoft part, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Compute = compute, Microsoft.ManagedIdentity = managed-identity.
- <hyphenated ARM resource type> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Compute/virtualMachines = virtual-machine, BUT Microsoft.Network/trafficmanagerprofiles = trafficmanagerprofile - since trafficmanagerprofiles is all lower case as per the ARM API definition.

Bicep Child Module Naming

Naming convention: avm/res/<hyphenated resource provider name>/<hyphenated ARM resource type>/<hyphenated child resource type/<hyphenated grandchild resource type>/<hyphenated great grandchild resource type>/<etc.> (module name for registry)
Example: avm/res/network/virtual-network/subnet or avm/res/storage/storage-account/blob-service/container
Segments:
- res defines this is a resource module
- <hyphenated resource provider name> is the resource provider’s name after the Microsoft part, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network = network.
- <hyphenated ARM resource type> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network/virtualNetworks = virtual-network.
- <hyphenated child resource type (to be repeated for grandchildren, etc.)> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network/virtualNetworks/subnets = subnet or Microsoft.Storage/storageAccounts/blobServices/containers = blob-service/container.

Terraform Resource Module Naming

Naming convention:
- avm-res-<resource provider>-<ARM resource type> (module name for registry)
- terraform-<provider>-avm-res-<resource provider>-<ARM resource type> (GitHub repository name to meet registry naming requirements)
Example: avm-res-compute-virtualmachine or avm-res-managedidentity-userassignedidentity
Segments:
- <provider> is the logical abstraction of various APIs used by Terraform. In most cases, this is going to be azurerm or azuread for resource modules.
- res defines this is a resource module
- <resource provider> is the resource provider’s name after the Microsoft part, e.g., Microsoft.Compute = compute.
- <ARM resource type> is the singular version of the word after the resource provider, e.g., Microsoft.Compute/virtualMachines = virtualmachine

See origin...

ID: RMNFR3 - Category: Composition - RP Collaboration

Module owners (Microsoft FTEs) SHOULD reach out to the respective Resource Provider teams to build a partnership and collaboration on the modules creation, existence and long term maintenance.

Review this wiki page (Microsoft Internal) for more information.

See origin...

ID: TFFR1 - Category: Composition - Cross-Referencing Modules

module "other-module" {
  source  = "Azure/xxx/azurerm"
  version = "1.2.3"
}

They MUST NOT use git reference to a module.

module "other-module" {
  source = "git::https://xxx.yyy/xxx.git"
}

module "other-module" {
  source = "github.com/xxx/yyy"
}

Modules MUST NOT contain references to non-AVM modules.

Tip

See Module Sources for more information.

See origin...

ID: TFFR3 - Category: Providers - Permitted Versions

Authors MUST only use the following Azure providers, and versions, in their modules:

provider	min version	max version
azapi	>= 2.0	< 3.0
azurerm	>= 4.0	< 5.0

Note

Authors MAY select either Azurerm, Azapi, or both providers in their module.

Authors MUST use the required_providers block in their module to enforce the provider versions.

The following is an example.

In it we use the pessimistic version constraint operator ~>.
That is to say that ~> 4.0 is equivalent to >= 4.0, < 5.0.

terraform {
  required_providers {
    # Include one or both providers, as needed
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
  }
}

See origin...

ID: TFNFR4 - Category: Composition - Code Styling - lower snake_casing

Module owners MUST use lower snake_casing for naming the following:

Locals
Variables
Outputs
Resources (symbolic names)
Modules (symbolic names)

For example: snake_casing_example (every word in lowercase, with each word separated by an underscore _)

Code Style

The content below is listed based on the following tags

Category-CodeStyleClass-ResourceLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	TFNFR6	Resource & Data Order	SHOULD	OwnerContributor	BAU
2	TFNFR7	Count & for_each Use	MUST	OwnerContributor	BAU
3	TFNFR8	Resource & Data Block Orders	SHOULD	OwnerContributor	BAU
4	TFNFR9	Module Block Order	SHOULD	OwnerContributor	BAU
5	TFNFR10	No Double Quotes in ignore_changes	MUST	OwnerContributor	BAU
6	TFNFR11	Null Comparison Toggle	SHOULD	OwnerContributor	BAU
7	TFNFR12	Dynamic for Optional Nested Objects	MUST	OwnerContributor	BAU
8	TFNFR13	Default Values with coalesce/try	SHOULD	OwnerContributor	BAU
9	TFNFR16	Variable Naming Rules	SHOULD	OwnerContributor	BAU
10	TFNFR17	Variables with Descriptions	SHOULD	OwnerContributor	BAU
11	TFNFR18	Variables with Types	MUST	OwnerContributor	BAU
12	TFNFR19	Sensitive Data Variables	SHOULD	OwnerContributor	BAU
13	TFNFR20	Non-Nullable Defaults for collection values	SHOULD	OwnerContributor	BAU
14	TFNFR21	Discourage Nullability by Default	MUST	OwnerContributor	BAU
15	TFNFR22	Avoid sensitive = false	MUST	OwnerContributor	BAU
16	TFNFR23	Sensitive Default Value Conditions	MUST	OwnerContributor	BAU
17	TFNFR24	Handling Deprecated Variables	MUST	OwnerContributor	BAU
18	TFNFR25	Verified Modules Requirements	MUST	OwnerContributor	BAU
19	TFNFR26	Providers in required_providers	MUST	OwnerContributor	BAU
20	TFNFR27	Provider Declarations in Modules	MUST	OwnerContributor	BAU
22	TFNFR30	Handling Deprecated Outputs	MUST	OwnerContributor	BAU
23	TFNFR31	locals.tf for Locals Only	MAY	OwnerContributor	BAU
25	TFNFR33	Precise Local Types	SHOULD	OwnerContributor	BAU
26	TFNFR34	Using Feature Toggles	MUST	OwnerContributor	BAU
27	TFNFR35	Reviewing Potential Breaking Changes	MUST	OwnerContributor	BAU
28	TFNFR36	Setting prevent_deletion_if_contains_resources	SHOULD	OwnerContributor	BAU
29	TFNFR37	Tool Usage by Module Owner	MAY	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: TFNFR6 - Category: Code Style - Resource & Data Order

For the definition of resources in the same file, the resources be depended on SHOULD come first, after them are the resources depending on others.

Resources that have dependencies SHOULD be defined close to each other.

See origin...

ID: TFNFR7 - Category: Code Style - count & for_each Use

We can use count and for_each to deploy multiple resources, but the improper use of count can lead to anti pattern.

You can use count to create some kind of resources under certain conditions, for example:

resource "azurerm_network_security_group" "this" {
  count               = local.create_new_security_group ? 1 : 0
  name                = coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
  resource_group_name = var.resource_group_name
  location            = local.location
  tags                = var.new_network_security_group_tags
}

The module’s owners MUST use map(xxx) or set(xxx) as resource’s for_each collection, the map’s key or set’s element MUST be static literals.

Good example:

resource "azurerm_subnet" "pair" {
  for_each             = var.subnet_map // `map(string)`, when user call this module, it could be: `{ "subnet0": "subnet0" }`, or `{ "subnet0": azurerm_subnet.subnet0.name }`
  name                 = "${each.value}"-pair
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.1.0/24"]
}

Bad example:

resource "azurerm_subnet" "pair" {
  for_each             = var.subnet_name_set // `set(string)`, when user use `toset([azurerm_subnet.subnet0.name])`, it would cause an error.
  name                 = "${each.value}"-pair
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.1.0/24"]
}

See origin...

ID: TFNFR8 - Category: Code Style - Resource & Data Block Orders

There are 3 types of assignment statements in a resource or data block: argument, meta-argument and nested block. The argument assignment statement is a parameter followed by =:

location = azurerm_resource_group.example.location

or:

tags = {
  environment = "Production"
}

Nested block is a assignment statement of parameter followed by {} block:

subnet {
  name           = "subnet1"
  address_prefix = "10.0.1.0/24"
}

Meta-arguments are assignment statements can be declared by all resource or data blocks. They are:

count
depends_on
for_each
lifecycle
provider

The order of declarations within resource or data blocks is:

All the meta-arguments SHOULD be declared on the top of resource or data blocks in the following order:

provider
count
for_each

Then followed by:

required arguments
optional arguments
required nested blocks
optional nested blocks

All ranked in alphabetical order.

These meta-arguments SHOULD be declared at the bottom of a resource block with the following order:

depends_on
lifecycle

The parameters of lifecycle block SHOULD show up in the following order:

create_before_destroy
ignore_changes
prevent_destroy

parameters under depends_on and ignore_changes are ranked in alphabetical order.

Meta-arguments, arguments and nested blocked are separated by blank lines.

dynamic nested blocks are ranked by the name comes after dynamic, for example:

  dynamic "linux_profile" {
    for_each = var.admin_username == null ? [] : ["linux_profile"]

    content {
      admin_username = var.admin_username

      ssh_key {
        key_data = replace(coalesce(var.public_ssh_key, tls_private_key.ssh[0].public_key_openssh), "\n", "")
      }
    }
  }

This dynamic block will be ranked as a block named linux_profile.

Code within a nested block will also be ranked following the rules above.

PS: You can use avmfix tool to reformat your code automatically.

See origin...

ID: TFNFR9 - Category: Code Style - Module Block Order

The meta-arguments below SHOULD be declared on the top of a module block with the following order:

source
version
count
for_each

blank lines will be used to separate them.

After them will be required arguments, optional arguments, all ranked in alphabetical order.

These meta-arguments below SHOULD be declared on the bottom of a resource block in the following order:

depends_on
providers

Arguments and meta-arguments SHOULD be separated by blank lines.

See origin...

ID: TFNFR10 - Category: Code Style - No Double Quotes in ignore_changes

The ignore_changes attribute MUST NOT be enclosed in double quotes.

Good example:

lifecycle {
    ignore_changes = [
      tags,
    ]
}

Bad example:

lifecycle {
    ignore_changes = [
      "tags",
    ]
}

See origin...

ID: TFNFR11 - Category: Code Style - Null Comparison Toggle

Intuitively, we will define it like this:

variable "security_group_id" {
  type: string
}

resource "azurerm_network_security_group" "this" {
  count               = var.security_group_id == null ? 1 : 0
  name                = coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
  resource_group_name = var.resource_group_name
  location            = local.location
  tags                = var.new_network_security_group_tags
}

You can’t do this:

resource "azurerm_network_security_group" "foo" {
  name                = "example-nsg"
  resource_group_name = "example-rg"
  location            = "eastus"
}

module "bar" {
  source = "xxxx"
  ...
  security_group_id = azurerm_network_security_group.foo.id
}

For this kind of parameters, wrapping with object type is RECOMMENDED:

variable "security_group" {
  type: object({
    id   = string
  })
  default     = null
}

resource "azurerm_network_security_group" "foo" {
  name                = "example-nsg"
  resource_group_name = "example-rg"
  location            = "eastus"
}

module "bar" {
  source = "xxxx"
  ...
  security_group = {
    id = azurerm_network_security_group.foo.id
  }
}

This technique SHOULD be used under this use case only.

See origin...

ID: TFNFR12 - Category: Code Style - Dynamic for Optional Nested Objects

An example from the community:

resource "azurerm_kubernetes_cluster" "main" {
  ...
  dynamic "identity" {
    for_each = var.client_id == "" || var.client_secret == "" ? [1] : []

    content {
      type                      = var.identity_type
      user_assigned_identity_id = var.user_assigned_identity_id
    }
  }
  ...
}

Please refer to the coding style in the example. Nested blocks under conditions, MUST be declared as:

for_each = <condition> ? [<some_item>] : []

See origin...

ID: TFNFR13 - Category: Code Style - Default Values with coalesce/try

The following example shows how "${var.subnet_name}-nsg" SHOULD be used when var.new_network_security_group_name is null or ""

Good examples:

coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")

try(coalesce(var.new_network_security_group.name, "${var.subnet_name}-nsg"), "${var.subnet_name}-nsg")

Bad examples:

var.new_network_security_group_name == null ? "${var.subnet_name}-nsg" : var.new_network_security_group_name)

See origin...

ID: TFNFR16 - Category: Code Style - Variable Naming Rules

The naming of a variable SHOULD follow HashiCorp’s naming rule.

variable used as feature switches SHOULD apply a positive statement, use xxx_enabled instead of xxx_disabled. Avoid double negatives like !xxx_disabled.

Please use xxx_enabled instead of xxx_disabled as name of a variable.

See origin...

ID: TFNFR17 - Category: Code Style - Variables with Descriptions

The target audience of description is the module users.

For object type variable, description can be composed in HEREDOC format:

variable "kubernetes_cluster_key_management_service" {
  type: object({
    key_vault_key_id         = string
    key_vault_network_access = optional(string)
  })
  default     = null
  description = <<-EOT
  - `key_vault_key_id` - (Required) Identifier of Azure Key Vault key. See [key identifier format](https://learn.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name) for more details. When Azure Key Vault key management service is enabled, this field is required and must be a valid key identifier. When `enabled` is `false`, leave the field empty.
  - `key_vault_network_access` - (Optional) Network access of the key vault Network access of key vault. The possible values are `Public` and `Private`. `Public` means the key vault allows public access from all networks. `Private` means the key vault disables public access and enables private link. Defaults to `Public`.
EOT
}

See origin...

ID: TFNFR18 - Category: Code Style - Variables with Types

type MUST be defined for every variable. type SHOULD be as precise as possible, any MAY only be defined with adequate reasons.

Use bool instead of string or number for true/false
Use string for text
Use concrete object instead of map(any)

See origin...

ID: TFNFR19 - Category: Code Style - Sensitive Data Variables

See origin...

ID: TFNFR20 - Category: Code Style - Non-Nullable Defaults for collection values

See origin...

ID: TFNFR21 - Category: Code Style - Discourage Nullability by Default

nullable = true MUST be avoided.

See origin...

ID: TFNFR22 - Category: Code Style - Avoid sensitive = false

sensitive = false MUST be avoided.

See origin...

ID: TFNFR23 - Category: Code Style - Sensitive Default Value Conditions

A default value MUST NOT be set for a sensitive input - e.g., a default password.

See origin...

ID: TFNFR24 - Category: Code Style - Handling Deprecated Variables

Deprecated variable MUST be annotated as DEPRECATED at the beginning of the description, at the same time the replacement’s name SHOULD be declared. E.g.,

variable "enable_network_security_group" {
  type        = string
  default     = null
  description = "DEPRECATED, use `network_security_group_enabled` instead; Whether to generate a network security group and assign it to the subnet. Changing this forces a new resource to be created."
}

A cleanup of deprecated_variables.tf SHOULD be performed during a major version release.

See origin...

ID: TFNFR25 - Category: Code Style - Verified Modules Requirements

The terraform.tf file MUST only contain one terraform block.

The first line of the terraform block MUST define a required_version property for the Terraform CLI.

The required_version property MUST include a constraint on the minimum version of the Terraform CLI. Previous releases of the Terraform CLI can have unexpected behavior.

The required_version property constraint SHOULD use the ~> #.# or the >= #.#.#, < #.#.# format.

Note: You can read more about Terraform version constraints in the documentation.

Example terraform.tf file:

terraform {
  required_version = "~> 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.11"
    }
  }
}

See origin...

ID: TFNFR26 - Category: Code Style - Providers in required_providers

The terraform block in terraform.tf MUST contain the required_providers block.

Each provider used directly in the module MUST be specified with the source and version properties. Providers in the required_providers block SHOULD be sorted in alphabetical order.

Do not add providers to the required_providers block that are not directly required by this module. If submodules are used then each submodule SHOULD have its own versions.tf file.

The source property MUST be in the format of namespace/name. If this is not explicitly specified, it can cause failure.

The version property MUST include a constraint on the minimum version of the provider. Older provider versions may not work as expected.

The version property constraint SHOULD use the ~> #.# or the >= #.#.#, < #.#.# format.

Note: You can read more about Terraform version constraints in the documentation.

Good examples:

terraform {
  required_version = "~> 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
  }
}

terraform {
  required_version = ">= 1.6.6, < 2.0.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11.1, < 4.0.0"
    }
  }
}

terraform {
  required_version = ">= 1.6, < 2.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11, < 4.0"
    }
  }
}

Acceptable example (but not recommended):

terraform {
  required_version = "1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "3.11"
    }
  }
}

Bad example:

terraform {
  required_version = ">= 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11"
    }
  }
}

See origin...

ID: TFNFR27 - Category: Code Style - Provider Declarations in Modules

Good examples:

In verified module:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
      configuration_aliases = [ azurerm.alternate ]
    }
  }
}

In the root module where we call this verified module:

provider "azurerm" {
  features {}
}

provider "azurerm" {
  alias = "alternate"
  features {}
}

module "foo" {
  source = "xxx"
  providers = {
    azurerm = azurerm
    azurerm.alternate = azurerm.alternate
  }
}

Bad example:

In verified module:

provider "azurerm" {
  # Configuration options
  features {}
}

See origin...

ID: TFNFR30 - Category: Code Style - Handling Deprecated Outputs

A cleanup SHOULD be performed to deprecated_outputs.tf and other logics related to compatibility during a major version upgrade.

See origin...

ID: TFNFR31 - Category: Code Style - locals.tf for Locals Only

In locals.tf, file we could declare multiple locals blocks, but only locals blocks are allowed.

You MAY declare locals blocks next to a resource block or data block for some advanced scenarios, like making a fake module to execute some light-weight tests aimed at the expressions.

See origin...

ID: TFNFR33 - Category: Code Style - Precise Local Types

Precise local types SHOULD be used.

Good example:

{
  name = "John"
  age  = 52
}

Bad example:

{
  name = "John"
  age  = "52" # age should be number
}

See origin...

ID: TFNFR34 - Category: Code Style - Using Feature Toggles

A toggle variable MUST be used to allow users to avoid the creation of a new resource block by default if it is added in a minor or patch version.

E.g., our previous release was v1.2.1 and next release would be v1.3.0, now we’d like to submit a pull request which contains such new resource:

resource "azurerm_route_table" "this" {
  location            = local.location
  name                = coalesce(var.new_route_table_name, "${var.subnet_name}-rt")
  resource_group_name = var.resource_group_name
}

A user who’s just upgraded the module’s version would be surprised to see a new resource to be created in a newly generated plan file.

A better approach is adding a feature toggle to be turned off by default:

variable "create_route_table" {
  type     = bool
  default  = false
  nullable = false
}

resource "azurerm_route_table" "this" {
  count               = var.create_route_table ? 1 : 0
  location            = local.location
  name                = coalesce(var.new_route_table_name, "${var.subnet_name}-rt")
  resource_group_name = var.resource_group_name
}

See origin...

ID: TFNFR35 - Category: Code Style - Reviewing Potential Breaking Changes

Potential breaking(surprise) changes introduced by resource block

Adding a new resource without count or for_each for conditional creation, or creating by default
Adding a new argument assignment with a value other than the default value provided by the provider’s schema
Adding a new nested block without making it dynamic or omitting it by default
Renaming a resource block without one or more corresponding moved blocks
Change resource’s count to for_each, or vice versa

Terraform moved block could be your cure.

Potential breaking changes introduced by variable and output blocks

Deleting(Renaming) a variable
Changing type in a variable block
Changing the default value in a variable block
Changing variable’s nullable to false
Changing variable’s sensitive from false to true
Adding a new variable without default
Deleting an output
Changing an output’s value
Changing an output’s sensitive value

These changes do not necessarily trigger breaking changes, but they are very likely to, they MUST be reviewed with caution.

See origin...

ID: TFNFR36 - Category: Code Style - Setting prevent_deletion_if_contains_resources

See origin...

ID: TFNFR37 - Category: Code Style - Tool Usage by Module Owner

Inputs / Outputs

The content below is listed based on the following tags

Category-Inputs/OutputsClass-ResourceLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR14	Data Types	SHOULD	OwnerContributor	BAU
2	SNFR22	Parameters/Variables for Resource IDs	MUST	OwnerContributor	BAU
3	SNFR26	Output - Parameters - Decorators	MUST	OwnerContributor	BAU
4	RMFR6	Parameter/Variable Naming	MUST	OwnerContributor	BAU
5	RMFR7	Minimum Required Outputs	MUST	OwnerContributor	BAU
6	RMNFR2	Parameter/Variable Naming	MUST	OwnerContributor	BAU
7	TFFR2	Additional Terraform Outputs	SHOULD	OwnerContributor	BAU
8	TFNFR14	Not allowed variables	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR14 - Category: Inputs - Data Types

A module SHOULD use either: simple data types. e.g., string, int, bool.

Complex data types (objects, arrays, maps) when the language-compliant schema is defined.

See origin...

ID: SNFR22 - Category: Inputs - Parameters/Variables for Resource IDs

workspaceId is not descriptive enough and is ambiguous as to which ID is required to be input.

See origin...

ID: SNFR26 - Output-Parameters - Decorators

Output parameters MUST implement:

Decorators in Bicep such as description & secure (if sensitive)
Arguments in Terraform such as description & sensitive (if sensitive)

Output parameters

@description('The resourceId of your resource.')
output sampleResourceId string = sampleResource.id

@description('The key of your resource.')
@secure()
output sampleResourceKey string = sampleResource.key

# Resource output
output "foo" {
  description = "MyResource foo attribute"
  value = azurerm_resource_myresource.foo
}

# Output of a sensitive attribute
output "bar" {
  description = "MyResource bar attribute"
  value     = azurerm_resource_myresource.bar
  sensitive = true
}

See origin...

ID: RMFR6 - Category: Inputs - Parameter/Variable Naming

Parameters/variables that pertain to the primary resource MUST NOT use the resource type in the name.

e.g., use sku, vs. virtualMachineSku/virtualmachine_sku

See origin...

ID: RMFR7 - Category: Outputs - Minimum Required Outputs

Module owners MUST output the following outputs as a minimum in their modules:

Output	Bicep Output Name	Terraform Output Name
Resource Name	`name`	`name`
Resource ID	`resourceId`	`resource_id`
System Assigned Managed Identity Principal ID (if supported by module)	`systemAssignedMIPrincipalId`	`system_assigned_mi_principal_id`

Tip

Module owners MAY also have to provide additional outputs depending on the IaC language, please check the language specific specs:

See origin...

ID: RMNFR2 - Category: Inputs - Parameter/Variable Naming

A resource module MUST use the following standard inputs:

name (no default)
location (if supported by the resource and not a global resource, then use Resource Group location, if resource supports Resource Groups, otherwise no default)

See origin...

ID: TFFR2 - Category: Outputs - Additional Terraform Outputs

Remember, you SHOULD NOT output values that are already inputs (other than name).

E.g.,

# Resource output, computed attribute.
output "foo" {
  description = "MyResource foo attribute"
  value = azurerm_resource_myresource.foo
}

# Resource output for resources that are deployed using `for_each`. Again only computed attributes.
output "childresource_foos" {
  description = "MyResource children's foo attributes"
  value = {
    for key, value in azurerm_resource_mychildresource : key => value.foo
  }
}

# Output of a sensitive attribute
output "bar" {
  description = "MyResource bar attribute"
  value     = azurerm_resource_myresource.bar
  sensitive = true
}

See origin...

ID: TFNFR14 - Category: Inputs - Not allowed variables

Testing

The content below is listed based on the following tags

Category-TestingClass-ResourceLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR1	Prescribed Tests	MUST	OwnerContributor	BAU
2	SNFR2	E2E Testing	MUST	OwnerContributor	BAU
3	SNFR3	AVM Compliance Tests	MUST	OwnerContributor	Initial
4	SNFR4	Unit Tests	SHOULD	OwnerContributor	BAU
5	SNFR5	Upgrade Tests	SHOULD	OwnerContributor	BAU
6	SNFR6	Static Analysis/Linting Tests	MUST	OwnerContributor	BAU
7	SNFR7	Idempotency Tests	MUST	OwnerContributor	BAU
8	SNFR24	Testing Child, Extension & Interface Resources	MUST	OwnerContributor	BAU
9	TFNFR5	Test Tooling	MUST	OwnerContributor	BAU
10	TFNFR15	Variable Definition Order	SHOULD	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR1 - Category: Testing - Prescribed Tests

Modules MUST use the prescribed tooling and testing frameworks defined in the language specific specs.

See origin...

ID: SNFR2 - Category: Testing - E2E Testing

Each test MUST run and complete without user inputs successfully, for automation purposes.

Each test MUST also destroy/clean-up its resources and test dependencies following a run.

Tip

To see a directory and file structure for a module, see the language specific contribution guide.

Resources/Dependencies Required for E2E Tests

It is likely that to complete E2E tests, a number of resources will be required as dependencies to enable the tests to pass successfully. Some examples:

When testing the Diagnostic Settings interface for a Resource Module, you will need an existing Log Analytics Workspace to be able to send the logs to as a destination.
When testing the Private Endpoints interface for a Resource Module, you will need an existing Virtual Network, Subnet and Private DNS Zone to be able to complete the Private Endpoint deployment and configuration.

Module owners MUST:

Create the required resources that their module depends upon in the test file/directory
- They MUST either use:
  - Simple/native resource declarations/definitions in their respective IaC language,
    OR
  - Another already published AVM Module that MUST be pinned to a specific published version.
    - They MUST NOT use any local directory path references or local copies of AVM modules in their own modules test directory.

➕ Terraform & Bicep Log Analytics Workspace examples using simple/native declarations for use in E2E tests

Terraform

resource "azurerm_resource_group" "example" {
  name     = "rsg-test-001"
  location = "West Europe"
}

resource "azurerm_log_analytics_workspace" "example" {
  name                = "law-test-001"
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  sku                 = "PerGB2018"
  retention_in_days   = 30
}

Bicep

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2021-12-01-preview' = {
  name: 'law-test-001'
  location: resourceGroup().location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
    retentionInDays: 30
  }
}

Skipping Deployments (SHOULD NOT)

Note

A skipped test case is still added to the ‘Usage Examples’ section of the module’s readme and should be manually validated in regular intervals.

Details for use in E2E tests

You MUST add a note to the tests metadata description, which explains the excemption.

Sample filecontent:

The test is skipped, as only one instance of this service can be deployed to a subscription.

Note

For resource modules, the ‘defaults’ and ‘waf-aligned’ tests can’t be skipped.

The deployment of a test can be skipped by adding a .e2eignore file into a test folder (e.g. /examples/<testname>).

See origin...

ID: SNFR3 - Category: Testing - AVM Compliance Tests

Modules MUST pass all tests that ensure compliance to AVM specifications. These tests MUST pass before a module version can be published.

Important

Please note these are still under development at this time and will be published and available soon for module owners.

See origin...

ID: SNFR4 - Category: Testing - Unit Tests

Unit Tests test specific module functionality, without deploying resources. Used on more complex modules. In Bicep and Terraform these live in tests/unit.

See origin...

ID: SNFR5 - Category: Testing - Upgrade Tests

Modules SHOULD implement upgrade testing to ensure new features are implemented in a non-breaking fashion on non-major releases.

See origin...

ID: SNFR6 - Category: Testing - Static Analysis/Linting Tests

Modules MUST use static analysis, e.g., linting, security scanning (PSRule, tflint, etc.). These tests MUST pass before a module version can be published.

There may be differences between languages in linting rules standards, but the AVM core team will try to close these and bring them into alignment over time.

See origin...

ID: SNFR7 - Category: Testing - Idempotency Tests

Modules MUST implement idempotency end-to-end (deployment) testing. E.g. deploying the module twice over the top of itself.

Modules SHOULD pass the idempotency test, as we are aware that there are some exceptions where they may fail as a false-positive or legitimate cases where a resource cannot be idempotent.

For example, Virtual Machine Image names must be unique on each resource creation/update.

See origin...

ID: SNFR24 - Category: Testing - Testing Child, Extension & Interface Resources

These MAY be tested in a separate E2E test and DO NOT have to be tested in each E2E test.

See origin...

ID: TFNFR5 - Category: Testing - Test Tooling

Module owners MUST use the below tooling for unit/linting/static/security analysis tests. These are also used in the AVM Compliance Tests.

Terraform
- terraform <validate/fmt/test>
terrafmt
Checkov
tflint (with azurerm ruleset)
Go
- Some tests are provided as part of the AVM Compliance Tests, but you are free to also use Go for your own tests.

See origin...

ID: TFNFR15 - Category: Code Style - Variable Definition Order

Input variables SHOULD follow this order:

All required fields, in alphabetical order
All optional fields, in alphabetical order

A variable without default value is a required field, otherwise it’s an optional one.

Documentation

The content below is listed based on the following tags

Category-DocumentationClass-ResourceLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR15	Automatic Documentation Generation	MUST	OwnerContributor	BAU
2	SNFR16	Examples/E2E	MUST	OwnerContributor	BAU
3	TFNFR1	Descriptions	MUST	OwnerContributor	BAU
4	TFNFR2	Module Documentation Generation	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR15 - Category: Documentation - Automatic Documentation Generation

README documentation MUST be automatically/programmatically generated. MUST include the sections as defined in the language specific requirements BCPNFR2, TFNFR2.

See origin...

ID: SNFR16 - Category: Documentation - Examples/E2E

An examples/e2e directory MUST exist to provide named scenarios for module deployment.

See origin...

ID: TFNFR1 - Category: Documentation - Descriptions

Where descriptions for variables and outputs spans multiple lines. The description MAY provide variable input examples for each variable using the HEREDOC format and embedded markdown.

Example:

  variable "my_complex_input" {
    type = map(object({
      param1 = string
      param2 = optional(number, null)
    }))
    description = <<DESCRIPTION
  A complex input variable that is a map of objects.
  Each object has two attributes:
  
  - `param1`: A required string parameter.
  - `param2`: (Optional) An optional number parameter.
  
  Example Input:
  
  ```terraform
  my_complex_input = {
    "object1" = {
      param1 = "value1"
      param2 = 2
    }
    "object2" = {
      param1 = "value2"
    }
  }
  ```
  DESCRIPTION
  }

See origin...

ID: TFNFR2 - Category: Documentation - Module Documentation Generation

Terraform modules documentation MUST be automatically generated via Terraform Docs.

A file called .terraform-docs.yml MUST be present in the root of the module and have the following content:

  ---
  ### To generate the output file to partially incorporate in the README.md,
  ### Execute this command in the Terraform module's code folder:
  # terraform-docs -c .terraform-docs.yml .
  
  formatter: "markdown document" # this is required
  
  version: "0.16.0"
  
  header-from: "_header.md"
  footer-from: "_footer.md"
  
  recursive:
    enabled: false
    path: modules
  
  sections:
    hide: []
    show: []
  
  content: |-
    {{ .Header }}    
  
    <!-- markdownlint-disable MD033 -->
    {{ .Requirements }}
  
    {{ .Providers }}
  
    {{ .Resources }}
  
    <!-- markdownlint-disable MD013 -->
    {{ .Inputs }}
  
    {{ .Outputs }}
  
    {{ .Modules }}
  
    {{ .Footer }}
  
  output:
    file: README.md
    mode: replace
    template: |-
      <!-- BEGIN_TF_DOCS -->
      {{ .Content }}
      <!-- END_TF_DOCS -->      
  output-values:
    enabled: false
    from: ""
  
  sort:
    enabled: true
    by: required
  
  settings:
    anchor: true
    color: true
    default: true
    description: false
    escape: true
    hide-empty: false
    html: true
    indent: 2
    lockfile: true
    read-comments: true
    required: true
    sensitive: true
    type: true

Release / Publishing

The content below is listed based on the following tags

Category-Release/PublishingClass-ResourceLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR17	Semantic Versioning	MUST	OwnerContributor	BAU
2	SNFR18	Breaking Changes	SHOULD	OwnerContributor	BAU
3	SNFR19	Registries Targeted	MUST	OwnerContributor	BAU
4	SNFR21	Cross Language Collaboration	SHOULD	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR17 - Category: Release - Semantic Versioning

Important

See the Bicep Contribution Guide for more information.

Modules MUST use semantic versioning (aka semver) for their versions and releases in accordance with: Semantic Versioning 2.0.0

For example all modules should be released using a semantic version that matches this pattern: X.Y.Z

X == Major Version
Y == Minor Version
Z == Patch Version

Module versioning before first Major version release `1.0.0`

Initially modules MUST be released as version 0.1.0 and incremented via Minor and Patch versions only until the AVM Core Team are confident the AVM specifications are mature enough and appropriate CI test coverage is in place, plus the module owner is happy the module has been “road tested” and is now stable enough for its first Major release of version 1.0.0.
Note
Releasing as version 0.1.0 initially and only incrementing Minor and Patch versions allows the module owner to make breaking changes more easily and frequently as it’s still not an official Major/Stable release. 👍
Until first Major version 1.0.0 is released, given a version number X.Y.Z:
- X Major version MUST NOT be bumped.
- Y Minor version MUST be bumped when introducing breaking changes (which would normally bump Major after 1.0.0 release) or feature updates (same as it will be after 1.0.0 release).
- Z Patch version MUST be bumped when introducing non-breaking, backward compatible bug fixes (same as it will be after 1.0.0 release).

See origin...

ID: SNFR18 - Category: Release - Breaking Changes

A module SHOULD avoid breaking changes, e.g., deprecating inputs vs. removing. If you need to implement changes that cause a breaking change, the major version should be increased.

Info

Tip

See the language specific examples to find out how you can deal with deprecations in AVM modules.

Bicep

See origin...

ID: SNFR19 - Category: Publishing - Registries Targeted

Modules MUST be published to their respective language public registries.

Bicep = Bicep Public Module Registry
- Within the avm directory
Terraform = HashiCorp Terraform Registry

Tip

See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

See origin...

ID: SNFR21 - Category: Publishing - Cross Language Collaboration

Terraform Utility Module Specifications

Contribution / Support

No specifications available for this criteria

Category-Contribution/SupportClass-UtilityLanguage-Terraform

Telemetry

No specifications available for this criteria

Category-TelemetryClass-UtilityLanguage-Terraform

Naming / Composition

The content below is listed based on the following tags

Category-Naming/CompositionClass-UtilityLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	TFFR3	Providers - Permitted Versions	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: TFFR3 - Category: Providers - Permitted Versions

Authors MUST only use the following Azure providers, and versions, in their modules:

provider	min version	max version
azapi	>= 2.0	< 3.0
azurerm	>= 4.0	< 5.0

Note

Authors MAY select either Azurerm, Azapi, or both providers in their module.

Authors MUST use the required_providers block in their module to enforce the provider versions.

The following is an example.

In it we use the pessimistic version constraint operator ~>.
That is to say that ~> 4.0 is equivalent to >= 4.0, < 5.0.

terraform {
  required_providers {
    # Include one or both providers, as needed
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
  }
}

Code Style

No specifications available for this criteria

Category-CodeStyleClass-UtilityLanguage-Terraform

Inputs / Outputs

No specifications available for this criteria

Category-Inputs/OutputsClass-UtilityLanguage-Terraform

Testing

No specifications available for this criteria

Category-TestingClass-UtilityLanguage-Terraform

Documentation

No specifications available for this criteria

Category-DocumentationClass-UtilityLanguage-Terraform

Release / Publishing

The content below is listed based on the following tags

Category-Release/PublishingClass-UtilityLanguage-Terraform

#	ID	Title	Severity	Persona	Lifecycle
1	SNFR17	Semantic Versioning	MUST	OwnerContributor	BAU

➕ See Specifications for this category

See origin...

ID: SNFR17 - Category: Release - Semantic Versioning

Important

See the Bicep Contribution Guide for more information.

Modules MUST use semantic versioning (aka semver) for their versions and releases in accordance with: Semantic Versioning 2.0.0

For example all modules should be released using a semantic version that matches this pattern: X.Y.Z

X == Major Version
Y == Minor Version
Z == Patch Version

Module versioning before first Major version release `1.0.0`

Initially modules MUST be released as version 0.1.0 and incremented via Minor and Patch versions only until the AVM Core Team are confident the AVM specifications are mature enough and appropriate CI test coverage is in place, plus the module owner is happy the module has been “road tested” and is now stable enough for its first Major release of version 1.0.0.
Note
Releasing as version 0.1.0 initially and only incrementing Minor and Patch versions allows the module owner to make breaking changes more easily and frequently as it’s still not an official Major/Stable release. 👍
Until first Major version 1.0.0 is released, given a version number X.Y.Z:
- X Major version MUST NOT be bumped.
- Y Minor version MUST be bumped when introducing breaking changes (which would normally bump Major after 1.0.0 release) or feature updates (same as it will be after 1.0.0 release).
- Z Patch version MUST be bumped when introducing non-breaking, backward compatible bug fixes (same as it will be after 1.0.0 release).

BCPFR1 - Cross-Referencing Modules

ID: BCPFR1 - Category: Composition - Cross-Referencing Modules

Module owners MAY cross-references other modules to build either Resource or Pattern modules.

The only exception to this rule are child modules as documented in BCPFR6.

Modules MUST NOT contain references to non-AVM modules.

BCPFR2 - Role Assignments Role Definition Mapping

ID: BCPFR2 - Category: Composition - Role Assignments Role Definition Mapping

However, they MUST use only the official RBAC Role Definition name within the variable and nothing else.

To meet the requirements of BCPFR2, BCPNFR5 and BCPNFR6 you MUST use the below code sample in your AVM Modules to achieve this.

  @description('''Required. You can provide either the display name (note not all roles are supported, check module documentation) of the role definition, or its fully qualified ID in the following format: `/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11`.''')
  param roleDefinitionIdOrName string
  
  var builtInRbacRoleNames = {
    Owner: '/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635'
    Contributor: '/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c'
    Reader: '/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7'
    'Role Based Access Control Administrator (Preview)': '/providers/Microsoft.Authorization/roleDefinitions/f58310d9-a9f6-439a-9e8d-f62e7b41a168'
    'User Access Administrator': '/providers/Microsoft.Authorization/roleDefinitions/18d7d88d-d35e-4fb5-a5c3-7773c20a72d9'
    //Other RBAC Role Definitions Names & IDs can be added here as needed for your module
  }
  
  var roleDefinitionIdMappedResult = (contains(builtInRbacRoleNames, roleDefinitionIdOrName) ? builtInRbacRoleNames[roleDefinitionIdOrName] : roleDefinitionIdOrName)
  
  resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    //Other properties removed for ease of reading
    properties: {
      roleDefinitionId: roleDefinitionIdMappedResult
      //Other properties removed for ease of reading
    }
  }

BCPFR4 - Telemetry Enablement

ID: BCPFR4 - Category: Composition - Telemetry Enablement

  @description('Optional. Location for all resources.')
  param location string = resourceGroup().location
  
  @description('Optional. Enable/Disable usage telemetry for module.')
  param enableTelemetry bool = true
  
  #disable-next-line no-deployments-resources
  resource avmTelemetry 'Microsoft.Resources/deployments@2024-03-01' = if (enableTelemetry) {
    name: take('46d3xbcp.res.compute-virtualmachine.${replace('-..--..-', '.', '-')}.${substring(uniqueString(deployment().name, location), 0, 4)}', 64)
    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'
          }
        }
      }
    }
  }

BCPFR6 - Cross-Referencing Child-Modules

ID: BCPFR6 - Cross-Referencing Child-Modules

@description('Optional. The databases to create in the server')
param databases databaseType[]?

resource server 'Microsoft.Sql/servers@(...)' = { (...) }

module server_databases 'database/main.bicep' = [for (database, index) in (databases ?? []): {
  name: '${uniqueString(deployment().name, location)}-Sql-DB-${index}'
  params: {
    serverName: server.name
    (...)
  }
}]

BCPFR7 - Cross-Referencing Modules

ID: BCPFR7 - Cross-Referencing published Modules

Resource modules, that reference other modules (child, utility, or other resource modules), MUST disable the telemetry on the referenced modules.

Note

This only applies to resource modules that reference other modules, such as:

other resource modules
utility modules
child-modules qualifying for publishing, i.e. having a version.json file in their directory and exposing the enableTelemetry input parameter

For pattern modules, SFR4 still applies.

var enableReferencedModulesTelemetry = false

// local referencing
module virtualNetwork_subnets 'subnet/main.bicep' = [
  for (subnet, index) in (subnets ?? []): {
    name: '${uniqueString(deployment().name, location)}-subnet-${index}'
    params: {
      (...)
      enableTelemetry: enableReferencedModulesTelemetry
    }
  }
]

// published module reference
module virtualNetwork_subnet 'br/public:avm/res/network/virtual-network/subnet:0.1.0' = {
  name: '${uniqueString(deployment().name, location)}-subnet-${index}'
    params: {
      (...)
      enableTelemetry: enableReferencedModulesTelemetry
    }
}

BCPNFR1 - Complex data types - General

ID: BCPNFR1 - Category: Inputs - Complex data types - General

Tip

User-Defined Types are GA in Bicep as of version v0.21.1, Resource-Derived Types are GA as of version v0.34.1, please ensure you have this version(s) installed as a minimum.

Resource-Derived Types and User-Defined Types allow intellisense support in supported IDEs (e.g. Visual Studio Code) for complex input parameters using objects and array of objects.

v0.x Exemption

While we allow the release of major versions, starting with v1.0.0, retrofitting Resource-Derived Types and User-Defined Types for all modules will take a considerable amount of time.

BCPNFR10 - Test Bicep File Naming

ID: BCPNFR10 - Category: Testing - Test Bicep File Naming

Module owners MUST name their test .bicep files in the /tests/e2e/<defaults/waf-aligned/max/etc.> directories: main.test.bicep as the test framework (CI) relies upon this name.

BCPNFR11 - Test Tooling

ID: BCPNFR11 - Category: Testing - Test Tooling

Module owners MUST use the below tooling for unit/linting/static/security analysis tests. These are also used in the AVM Compliance Tests.

PSRule for Azure
Pester
- Some tests are provided as part of the AVM Compliance Tests, but you are free to also use Pester for your own tests.

BCPNFR12 - Deployment Test Naming

ID: BCPNFR12 - Category: Testing - Deployment Test Naming

Module owners MUST invoke the module in their test using the syntax:

module testDeployment '../../../main.bicep' =

Example 1: Working example with a single deployment

module testDeployment '../../../main.bicep' = {
  scope: resourceGroup
  name: '${uniqueString(deployment().name, location)}-test-${serviceShort}'
  params: {
    (...)
  }
}

Example 2: Working example using a deployment loop

@batchSize(1)
module testDeployment '../../main.bicep' = [for iteration in [ 'init', 'idem' ]: {
  scope: resourceGroup
  name: '${uniqueString(deployment().name, location)}-test-${serviceShort}-${iteration}'
  params: {
    (...)
  }
}]

The syntax is used by the ReadMe-generating utility to identify, pull & format usage examples.

BCPNFR13 - Test file metadata

ID: BCPNFR13 - Category: Testing - Test file metadata

For example:

metadata name = 'Using Customer-Managed-Keys with System-Assigned identity'
metadata description = 'This instance deploys the module using Customer-Managed-Keys using a System-Assigned Identity. This required the service to be deployed twice, once as a pre-requisite to create the System-Assigned Identity, and once to use it for accessing the Customer-Managed-Key secret.'

would lead to a header in the module’s readme.md file along the lines of

### Example 1: _Using Customer-Managed-Keys with System-Assigned identity_

This instance deploys the module using Customer-Managed-Keys using a System-Assigned Identity. This required the service to be deployed twice, once as a pre-requisite to create the System-Assigned Identity, and once to use it for accessing the Customer-Managed-Key secret.

BCPNFR14 - Versioning

ID: BCPNFR14 - Category: Composition - Versioning

To meet SNFR17 and depending on the changes you make, you may need to bump the version in the version.json file.

  {
    "$schema": "https://aka.ms/bicep-registry-module-version-file-schema#",
    "version": "0.1",
    "pathFilters": [
        "./main.json"
    ]
  }

For example, the version value should be:

0.1 for new modules, so that they can be released as v0.1.0.
1.0 once the module owner signs off the module is stable enough for it’s first Major release of v1.0.0.
0.x for all feature updates between the first release v0.1.0 and the first Major release of v1.0.0.

BCPNFR15 - AVM Module Issue template file

ID: BCPNFR15 - Category: Contribution/Support - AVM Module Issue template file

Module owners MUST add an entry to the AVM Module Issue template file in the BRM repository (here). When the module is deprecated, this entry MUST be removed from the file.

Note

Through this approach, the AVM core team will allow raising a bug or feature request for a module, only after the module gets merged to the BRM repository.

The module name entry MUST be added to the dropdown list with id module-name-dropdown as an option, in alphabetical order.

Important

Module owners MUST ensure that the module name is added in alphabetical order, to simplify selecting the right module name when raising an AVM module issue.

Example - AVM Module Issue template module name entry for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

- type: dropdown
  id: module-name-dropdown
  attributes:
    label: Module Name
    description: Which existing AVM module is this issue related to?
    options:
      ...
      - "avm/res/network/virtual-network"
      ...

BCPNFR16 - Post-deployment tests

ID: BCPNFR16 - Category: Testing - Post-deployment tests

For each test case in the e2e folder, you can optionally add post-deployment Pester tests that are executed once the corresponding deployment completed and before the removal logic kicks in.

To leverage the feature you MUST:

Use Pester as a test framework in each test file
Name the file with the suffix "*.tests.ps1"
Place each test file the e2e test’s folder or any subfolder (e.g., e2e/max/myTest.tests.ps1 or e2e/max/tests/myTest.tests.ps1)

Implement an input parameter TestInputData in the following way:

param (
    [Parameter(Mandatory = $false)]
    [hashtable] $TestInputData = @{}
)

Through this parameter you can make use of every output the main.test.bicep file returns, as well as the path to the test template file in case you want to extract data from it directly.

For example, with an output such as output resourceId string = testDeployment[1].outputs.resourceId defined in the main.test.bicep file, the $TestInputData would look like:

$TestInputData = @{
  DeploymentOutputs    = @{
    resourceId = @{
      Type  = "String"
      Value = "/subscriptions/***/resourceGroups/dep-***-keyvault.vaults-kvvpe-rg/providers/Microsoft.KeyVault/vaults/***kvvpe001"
    }
  }
  ModuleTestFolderPath = "/home/runner/work/bicep-registry-modules/bicep-registry-modules/avm/res/key-vault/vault/tests/e2e/private-endpoint"
}

A full test file may look like:

➕ Pester post-deployment test file example

param (
    [Parameter(Mandatory = $false)]
    [hashtable] $TestInputData = @{}
)

Describe 'Validate private endpoint deployment' {

    Context 'Validate sucessful deployment' {

        It "Private endpoints should be deployed in resource group" {

            $keyVaultResourceId = $TestInputData.DeploymentOutputs.resourceId.Value
            $testResourceGroup = ($keyVaultResourceId -split '\/')[4]
            $deployedPrivateEndpoints = Get-AzPrivateEndpoint -ResourceGroupName $testResourceGroup
            $deployedPrivateEndpoints.Count | Should -BeGreaterThan 0
        }
    }
}

BCPNFR17 - Code Styling - Type casting

ID: BCPNFR17 - Category: Composition - Code Styling - Type casting

For reference, please refer to the following examples:

Boolean as String

@allowed([
  'false'
  'true'
])
param myParameterValue string = 'false'

resource myResource '(...)' = {
  (...)
  properties: {
    myParameter: myParameterValue
  }
}

param myParameterValue string = false

resource myResource '(...)' = {
  (...)
  properties: {
    myParameter: string(myParameterValue)
  }
}

Integer Array as String Array

@allowed([
  '1'
  '2'
  '3'
])
param zones array

resource myResource '(...)' = {
  (...)
  properties: {
    zones: zones
  }
}

@allowed([
  1
  2
  3
])
param zones int[]

resource myResource '(...)' = {
  (...)
  properties: {
    zones: map(zones, zone => string(zone))
  }
}

BCPNFR18 - User-defined types - Specification

ID: BCPNFR18 - User-defined types - Specification

User-defined types (UDTs) MUST always be singular and non-nullable. The configuration of either should instead be done directly at the parameter or output that uses the type.

For example, instead of

param subnets subnetsType
type subnetsType = { ... }[]?

the type should be defined like

param subnets subnetType[]?
type subnetType = { ... }

BCPNFR19 - User-defined types - Naming

ID: BCPNFR19 - User-defined types - Naming

type subnet = { ... } // Wrong
type subnetType = { ... } // Correct
type subnetOutputType = { ... } // Correct, if used only for outputs

Since User-defined types (UDTs) MUST always be singular as per BCPNFR18, their naming should reflect this and also be singular.

type subnetsType = { ... } // Wrong
type subnetType = { ... } // Correct

BCPNFR2 - Module Documentation Generation

ID: BCPNFR2 - Category: Documentation - Module Documentation Generation

Note

This script/tool is currently being developed by the AVM team and will be made available very soon.

Bicep modules documentation MUST be automatically generated via the provided script/tooling from the AVM team, providing the following headings:

Title
Description
Navigation
Resource Types
Usage Examples
Parameters
Outputs
Cross-referenced modules

BCPNFR20 - User-defined types - Export

ID: BCPNFR20 - User-defined types - Export

User-defined types (UDTs) SHOULD always be exported via the @export() annotation in every template they’re implemented in.

@export()
type subnetType = { ... }

BCPNFR21 - User-defined types - Decorators

ID: BCPNFR21 - User-defined types - Decorators

Similar to BCPNFR9, User-defined types (UDTs) MUST implement decorators such as description & secure (if sensitive). This is true for every property of the UDT, as well as the UDT itself.

@description('My type''s description.')
type myType = {
  @description('Optional. The threshold of your resource.')
  @minValue(1)
  @maxValue(10)
  threshold: int?

  @description('Required. The SKU of your resource.')
  sku: ('Basic' | 'Premium' | 'Standard')
}

BCPNFR22 - Bicep Module Changelog

ID: BCPNFR22 - Category: Publishing - Changelog

# Changelog

The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/<ptn|res|utl>/<namespace/modulename[/submodulePath]>/CHANGELOG.md).

For each new version, an entry MUST be created above all existing versions in the CHANGELOG.md file of the module.

## <version>

### Changes

- This changed
- And this also

### Breaking Changes

- None

Each version’s entry:

MUST contain two sections: Changes and Breaking Changes. At least one of them must have a meaningful entry and sections must not be left empty. A - None may be added as content for a section.
MUST exist only once.
All versions appear in descending order, which puts the most recent changes at the top.

What SHOULD be listed in the (Breaking) Changes section:

Relevant changes for the module
Changes in tests do not need to be added

Note

The versioning is following the SNFR17 - Semantic Versioning spec.

Example content of the CHANGELOG.md

# Changelog

The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/aad/domain-service/CHANGELOG.md).

## 0.2.1

### Changes

- Updated the referenced AVM common types

### Breaking Changes

- None

## 0.2.0

### Changes

- Implemented the minCPU parameter
- Updated the referenced VirtualNetwork module
- Updated the referenced AVM common types

### Breaking Changes

- The minCPU parameter is mandatory

## 0.1.0

### Changes

- Initial Release

### Breaking Changes

- None

Each bullet point should start with a capital letter.

Manual Editing

It is possible to modify the changelog content any time, e.g., to add missing versions, which will not create a new release of the module itself. Please note the following requirements in all cases:

All versions in the file, need to be valid and available as published version
Every version needs the two sections ## Changes and ## Breaking Changes with content

Note

BCPNFR3 - Usage Example formats

ID: BCPNFR3 - Category: Documentation - Usage Example formats

Usage examples for Bicep modules MUST be provided in the following formats:

Bicep file (orchestration module style) - .bicep

module <resourceName> 'br/public:avm/[res|ptn|utl]/<publishedModuleName>:>version<' = {
  name: '${uniqueString(deployment().name, location)}-test-<uniqueIdentifier>'
  params: { (...) }
}

JSON / ARM Template Parameter Files - .json

{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": { (...) }
}

Note

Bicep Parameter Files (.bicepparam) are being reviewed and considered by the AVM team for the usability and features at this time and will likely be added in the future.

BCPNFR4 - Parameter Input Examples

ID: BCPNFR4 - Category: Documentation - Parameter Input Examples

Bicep modules MAY provide parameter input examples for parameters using the metadata.example property via the @metadata() decorator.

Example:

@metadata({
  example: 'uksouth'
})
@description('Optional. Location for all resources.')
param location string = resourceGroup().location

@metadata({
  example: '''
  {
    keyName: 'myKey'
    keyVaultResourceId: '/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/my-rg/providers/Microsoft.KeyVault/vaults/myvault'
    keyVersion: '6d143c1a0a6a453daffec4001e357de0'
    userAssignedIdentityResourceId '/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/my-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity'
  }
  '''
})
@description('Optional. The customer managed key definition.')
param customerManagedKey customerManagedKeyType

BCPNFR5 - Role Assignments Role Definition Mapping Limits

ID: BCPNFR5 - Category: Composition - Role Assignments Role Definition Mapping Limits

As per BCPFR2, module owners MAY define common RBAC Role Definition names and IDs within a variable to allow consumers to define a RBAC Role Definition by their name rather than their ID.

Therefore module owners SHOULD only map the most applicable and common RBAC Role Definition names for their module and SHOULD NOT exceed 15 RBAC Role Definitions in the variable.

Important

Tip

Review the Bicep Contribution Guide’s ‘RBAC Role Definition Name Mapping’ section for a code sample to achieve this requirement.

BCPNFR6 - Role Assignments Role Definition Mapping Compulsory Roles

ID: BCPNFR6 - Category: Composition - Role Assignments Role Definition Mapping Compulsory Roles

Module owners MUST include the following roles in the variable for RBAC Role Definition names:

Owner - ID: 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor - ID: b24988ac-6180-42a0-ab88-20f7382dd24c
Reader - ID: acdd72a7-3385-48ef-bd42-f606fba81ae7
User Access Administrator - ID: 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9
Role Based Access Control Administrator (Preview) - ID: f58310d9-a9f6-439a-9e8d-f62e7b41a168

Tip

Review the Bicep Contribution Guide’s ‘RBAC Role Definition Name Mapping’ section for a code sample to achieve this requirement.

BCPNFR7 - Parameter Requirement Types

ID: BCPNFR7 - Category: Inputs - Parameter Requirement Types

Parameter Requirement Type	Definition	Example Description Decorator
Required	The parameter value must be provided. The parameter does not have a default value and hence the module expects and requires an input.	`@description('Required. <PARAMETER DESCRIPTION HERE...>')`
Conditional	The parameter value can be optional or required based on a condition, mostly based on the value provided to other parameters. Should contain a sentence starting with ‘Required if (…).’ to explain the condition.	`@description('Conditional. <PARAMETER DESCRIPTION HERE...>')`
Optional	The parameter value is not mandatory. The module provides a default value for the parameter.	`@description('Optional. <PARAMETER DESCRIPTION HERE...>')`
Generated	The parameter value is generated within the module and should not be specified as input in most cases. A common example of this is the `utcNow()` function that is only supported as the input for a parameter value, and not inside a variable.	`@description('Generated. <PARAMETER DESCRIPTION HERE...>')`

BCPNFR8 - Code Styling - lower camelCasing

ID: BCPNFR8 - Category: Composition - Code Styling - lower camelCasing

Module owners SHOULD use lower camelCasing for naming the following:

Parameters
Variables
Outputs
User Defined Types
Resources (symbolic names)
Modules (symbolic names)

For example: camelCasingExample (lowercase first word (entirely), with capital of first letter of all other words and rest of word in lowercase)

BCPNFR9 - Inputs - Decorators

ID: BCPNFR9 - Inputs - Decorators

Similar to BCPNFR21, input parameters MUST implement decorators such as description & secure (if sensitive).

@description('Optional. The threshold of your resource.')
@minValue(1)
@maxValue(10)
param threshold: int?
@description('Required. The SKU of your resource.')
@allowed([
'Basic'
'Premium'
'Standard'
])
param sku string

BCPRMNFR1 - Expected Test Directories

ID: BCPRMNFR1 - Category: Testing - Expected Test Directories

Note

/tests/e2e/linux.defaults/main.test.bicep
/tests/e2e/linux.waf-aligned/main.test.bicep
/tests/e2e/windows.defaults/main.test.bicep
/tests/e2e/windows.waf-aligned/main.test.bicep

Defaults tests (MUST)

The defaults folder contains a test instance that deploys the module with the minimum set of required parameters.

This includes input parameters of type Required plus input parameters of type Conditional marked as required for WAF compliance.

This instance has heavy reliance on the default values for other input parameters. Parameters of type Optional SHOULD NOT be used.

WAF aligned tests (MUST)

The waf-aligned folder contains a test instance that deploys the module in alignment with the best-practices of the Azure Well-Architected Framework.

This includes input parameters of type Required, parameters of type Conditional marked as required for WAF compliance, and parameters of type Optional useful for WAF compliance.

Parameters and dependencies which are not needed for WAF compliance, SHOULD NOT be included.

Max tests (SHOULD)

The max folder contains a test instance that deploys the module using a large parameter set, enabling most of the modules’ features.

Note

Additional tests (CAN)

Additional folders CAN be created by module owners as required.

For example, to validate parameters not covered by the max test due to conflicts, or to provide a real example scenario for a specific use case.

BCPRMNFR2 - User-defined types - AVM-Common-Types

ID: BCPRMNFR2 - User-defined types - AVM-Common-Types

When implementing any of the shared or Bicep-specific AVM interface variants you MUST import their User-defined type (UDT) via the published AVM-Common-Types module.

When doing so, each type MUST be imported separately, right above the parameter or output that uses it.

import { roleAssignmentType } from 'br/public:avm/utl/types/avm-common-types:*.*.*'
@description('Optional. Array of role assignments to create.')
param roleAssignments roleAssignmentType[]?
import { diagnosticSettingFullType } from 'br/public:avm/utl/types/avm-common-types:*.*.*'
@description('Optional. The diagnostic settings of the service.')
param diagnosticSettings diagnosticSettingFullType[]?

Importing them individually as opposed to one common block has several benefits such as

Individual versioning of types
If you must update the version for one type, you’re not exposed to unexpected changes to other types

Important

The import (...) block MUST not be added in between a parameter’s definition and its metadata. Doing so breaks the metadata’s binding to the parameter in question.

BCPRMNFR3 - Child resources structure

ID: BCPRMNFR3 - Implementing child resources

sql
└─ server [module]
  └─ database [child-module/resource]

There are several reasons to structure a module in this way. For example:

It allows a separation of concerns where each module can focus on its own properties and logic, while delegating most of a child-resource’s logic to its separate child module
It’s consistent with the provider namespace structure and makes modules easier to understand not only because they’re more aligned with set structure, but also are aligned with one another
As each module is its own ‘deployment’, it reduces limitations around nested loops
Once the feature is enabled, it will enable module owners to publish set child-modules as separate modules to the public registry, allowing consumers to make use of them directly.

Note

Module Classifications

Module Classification Definitions

AVM defines two module classifications, Resource Modules and Pattern Modules, that can be created, published, and consumed, these are defined further in the table below:

Module Class	Definition	Who is it for?
Resource Module	Deploys a primary resource with WAF high priority/impact best practice configurations set by default, e.g., availability zones, firewall, enforced Entra ID authentication and other shared interfaces, e.g., RBAC, Locks, Private Endpoints etc. (if supported). See What does AVM mean by “WAF Aligned”? They MAY include related resources, e.g. VM contains disk & NIC. Focus should be on customer experience. A customer would expect that a VM module would include all required resources to provision a VM. Furthermore, Resource Modules MUST NOT deploy external dependencies for the primary resource. E.g. a VM needs a vNet and Subnet to be deployed into, but the vNet will not be created by the VM Resource Module. Finally, a resource can be anything such as Microsoft Defender for Cloud Pricing Plans, these are still resources in ARM and can therefore be created as a Resource Module.	People who want to craft bespoke architectures that default to WAF best practices, where appropriate, for each resource. People who want to create pattern modules.
Pattern Module	Deploys multiple resources, usually using Resource Modules. They can be any size but should help accelerate a common task/deployment/architecture. Good candidates for pattern modules are those architectures that exist in Azure Architecture Center, or other official documentation. Note: Pattern modules can contain other pattern modules, however, pattern modules MUST NOT contain references to non-AVM modules.	People who want to easily deploy patterns (architectures) using WAF best practices.
Utility Module (draft, see below)	Implements a function or routine that can be flexibly reused in resource or pattern modules - e.g., a function that retrieves the endpoint of an API or portal of a given environment. It MUST NOT deploy any Azure resources other than deployment scripts.	People who want to leverage commonly used functions/routines/helpers in their module, instead of re-implementing them locally.

PREVIEW

The concept of Utility Modules will be introduced gradually, through some initial examples. The definition above is subject to change as additional details are worked out.

The required automated tests and other workflow elements will be derived from the Pattern Modules’ automation/CI environment as the concept matures.

Utility modules will follow the below naming convention:

Bicep: avm/utl/<hyphenated grouping/category name>/<hyphenated utility module name>. Modules will be kept under the avm/utl folder in the BRM repository.
Terraform: avm-utl-<utility-module-name>. Repositories will be named after the utility module (e.g., terraform-azurerm-avm-utl-<my utility module>).

All related documentation (functional and non-functional requirements, etc.) will also be published along the way.

Module Lifecycle

This section outlines the different stages of a module’s lifecycle:

flowchart LR
    Proposed["1 - Proposed ⚪"] --> |Acceptance criteria met ✅| Available["2 - Available 🟢"]
      click Proposed "/Azure-Verified-Modules/specs/shared/module-lifecycle/#1-proposed-modules"
      click Available "/Azure-Verified-Modules/specs/shared/module-lifecycle/#2-available-modules"
    Proposed --> |Acceptance criteria not met ❌| Rejected[Rejected]
    Available --> |Module temporarily not maintained| Orphaned["3 - Orphaned 🟡"]
    Orphaned --> |End of life| Deprecated["4 - Deprecated 🔴"]
      click Orphaned "/Azure-Verified-Modules/specs/shared/module-lifecycle/#3-orphaned-modules"
    Orphaned --> |New owner identified| Available
    Available --> |End of life| Deprecated
      click Deprecated "/Azure-Verified-Modules/specs/shared/module-lifecycle/#4-deprecated-modules"
    style Proposed fill:#ADD8E6,stroke:#333,stroke-width:1px
    style Orphaned fill:#F4A460,stroke:#333,stroke-width:1px
    style Available fill:#8DE971,stroke:#333,stroke-width:4px
    style Deprecated fill:#000000,stroke:#333,stroke-width:1px,color:#fff
    style Rejected fill:#A2A2A2,stroke:#333,stroke-width:1px

Important

If a module proposal is rejected, the issue is closed and the module’s lifecycle ends.

1. Proposed Modules

A module can be proposed through the module proposal process. The module proposal process is outlined in the Process Overview section.

To propose/request a new AVM resource, pattern or utility module, submit a module proposal issue in the AVM repository.

The proposal should include the following information:

module name
language (Bicep, Terraform, etc.)
module class (resource, pattern, utility)
module description
module owner(s) - if known

The AVM core team will review the proposal, and administrate the module.

Info

To propose a new module, submit a module proposal issue in the AVM repository.

2. Available modules

Once a module has been fully developed, tested and published in the main branch of the repository and the corresponding public registry (Bicep or Terraform), it is then considered to be “available” and can be used by the community. The module is maintained by the module owner(s). Feature or bug fix requests and related pull requests can be submitted by anyone to the module owner(s) for review.

3. Orphaned Modules

It is critical to the consumers experience that modules continue to be maintained. In the case where a module owner cannot continue in their role or do not respond to issues as per the defined timescale in the Module Support page , the following process will apply:

The module owner is responsible for finding a replacement owner and providing a handover.
If no replacement can be found or the module owner leaves Microsoft without giving warning to the AVM core team, the AVM core team will provide essential maintenance (critical bug and security fixes), as per the Module Support page
The AVM core team will continue to try and re-assign the module ownership.
While a module is in an orphaned state, only security and bug fixes MUST be made, no new feature development will be worked on until a new owner is found that can then lead this effort for the module.
An issue will be created on the central AVM repo (Azure/Azure-Verified-Modules) to track the finding of a new owner for a module.

Info

To orphan a module, submit an orphaned module issue in the AVM repository.

Notification of a Module Becoming Orphaned

Important

When a module becomes orphaned, the AVM core team will communicate this through an information notice to be placed as follows.

In case of a Bicep module, the information notice will be placed in an ORPHANED.md file and in the header of the module’s README.md - both residing in the module’s root.
In case of a Terraform module, the information notice will be placed in the header of the README.md file, in the module’s root.

The information notice will include the following statement:

⚠️THIS MODULE IS CURRENTLY ORPHANED.⚠️

- Only security and bug fixes are being handled by the AVM core team at present.
- If interested in becoming the module owner of this orphaned module (must be Microsoft FTE), please look for the related "orphaned module" GitHub issue [here](https://aka.ms/AVM/OrphanedModules)!

Also, the AVM core team will amend the issue automation to auto reply stating that the repo is orphaned and only security/bug fixes are being handled until a new module owner is found.

4. Deprecated Modules

Once a module reaches the end of its lifecycle (e.g., it’s permanently replaced by another module; permanent retirement due to obsolete technology/solution), it needs to be deprecated. A deprecated module will no longer be maintained, and no new features or bug fixes will be implemented for it. The module will indefinitely stay available in the public registry and source code repository for use, but certain measures will take place, such as:

The module will show as deprecated in the AVM module index.
The module will no longer be shown through VS Code IntelliSense.
The module’s source code will be kept in its repository but it will show a deprecated status through a DEPRECATED.md file (Bicep only) and a disclaimer in the module’s README.md file.
It will be a clearly indicated on the module’s repo that new issues can no longer be submitted for the module:
- Bicep: The module will be taken off the list of available modules in related issue templates.
- Terraform: The module’s repo will be archived.
The module’s -owners- and -contributors- GitHub teams will be retained indefinitely as these grant access to the source code of the module.

It is recommended to migrate to a replacement/alternative version of the module, if available.

Important

When a module becomes deprecated, the AVM core team will communicate this through an information notice to be placed as follows.

In case of a Bicep module, the information notice will be placed in a DEPRECATED.md file and in the header of the module’s README.md - both residing in the module’s root.
In case of a Terraform module, the information notice will be placed in the header of the README.md file, in the module’s root.

The information notice MUST include the following statement:

⚠️THIS MODULE IS DEPRECATED.⚠️

- It will no longer receive any updates.
- The module can still be used as is (references to any existing versions will keep working), but it is not recommended for new deployments.
- It is recommended to migrate to a replacement/alternative version of the module, if available.

Info

To deprecate a module, submit a deprecated module issue in the AVM repository.

➕ Retrieve the available versions of a deprecated module

To find all previous versions of a Bicep module, the following steps need to be performed (assuming the avm/ptn/finops-toolkit/finops-hub module has been deprecated):

To find out the all the versions the module has ever been published under, perform one of these steps:
1. navigate to Bicep Public Registry’s JSON index and look for the module’s name,
2. OR visit https://mcr.microsoft.com/v2/bicep/avm/ptn/finops-toolkit/finops-hub/tags/list.
3. OR clone the Bicep Public Registry repository and run the following command in the root of the repository: git tag -l 'avm/ptn/finops-toolkit/finops-hub/*'. This will list all the tags that match the module’s name.
Identify the available versions of the module, e.g., 0.1.0, 0.1.1, etc.
To download the content, construct and navigate to the following URL: https://github.com/Azure/bicep-registry-modules/releases/tag/avm/ptn/finops-toolkit/finops-hub/0.1.0
To see the content in the folder hierarchy, construct and navigate to the following URL: https://github.com/Azure/bicep-registry-modules/tree/avm/ptn/finops-toolkit/finops-hub/0.1.0/avm/ptn/finops-toolkit/finops-hu

Terraform modules will be listed in the HashiCorp Terraform Registry indefinitely.

PMFR1 - Resource Group Creation

ID: PMFR1 - Category: Composition - Resource Group Creation

A Pattern Module MAY create Resource Group(s).

PMNFR1 - Module Naming

ID: PMNFR1 - Category: Naming - Module Naming

Pattern Modules MUST follow the below naming conventions (all lower case):

Bicep Pattern Module Naming

Naming convention: avm/ptn/<hyphenated grouping/category name>/<hyphenated pattern module name>
Example: avm/ptn/compute/app-tier-vmss or avm/ptn/avd-lza/management-plane or avm/ptn/3-tier/web-app
Segments:
- ptn defines this as a pattern module
- <hyphenated grouping/category name> is a hierarchical grouping of pattern modules by category, with each word separated by dashes, such as:
  - project name, e.g., avd-lza,
  - primary resource provider, e.g., compute or network, or
  - architecture, e.g., 3-tier
- <hyphenated pattern module name> is a term describing the module’s function, with each word separated by dashes, e.g., app-tier-vmss = Application Tier VMSS; management-plane = Azure Virtual Desktop Landing Zone Accelerator Management Plane

Terraform Pattern Module Naming

Naming convention:
- avm-ptn-<pattern module name> (Module name for registry)
- terraform-<provider>-avm-ptn-<pattern module name> (GitHub repository name to meet registry naming requirements)
Example: avm-ptn-apptiervmss or avm-ptn-avd-lza-managementplane
Segments:
- <provider> is the logical abstraction of various APIs used by Terraform. In most cases, this is going to be azurerm or azuread for resource modules.
- ptn defines this as a pattern module
- <pattern module name> is a term describing the module’s function, e.g., apptiervmss = Application Tier VMSS; avd-lza-managementplane = Azure Virtual Desktop Landing Zone Accelerator Management Plane

PMNFR2 - Use Resource Modules to Build a Pattern Module

ID: PMNFR2 - Category: Composition - Use Resource Modules to Build a Pattern Module

Valid reasons for not using a Resource Module for a resource required by a Pattern Module include but are not limited to:

When using a Resource Module would result in hitting scaling limitations and/or would reduce the capabilities of the Pattern Module due to the limitations of Azure Resource Manager.
Developing a Pattern Module under time constraint, without having all required Resource Modules readily available.

Note

PMNFR3 - Use other Pattern Modules to Build a Pattern Module

ID: PMNFR3 - Category: Composition - Use other Pattern Modules to Build a Pattern Module

A Pattern Module MAY contain and be built using other AVM Pattern Modules. A Pattern Module MUST NOT contain references to non-AVM modules.

PMNFR4 - Missing Resource Module(s)

ID: PMNFR4 - Category: Hygiene - Missing Resource Module(s)

An item MUST be logged onto as an issue on the AVM Central Repo (Azure/Azure-Verified-Modules) if a Resource Module does not exist for resources deployed by the pattern module.

Exception

If the Resource Module adds no value, see Resource Module functional requirement ID: RMFR2.

PMNFR5 - Parameter/Variable Naming

ID: PMNFR5 - Category: Inputs - Parameter/Variable Naming

Parameter/variable input names SHOULD contain the resource to which they pertain. E.g., virtualMachineSku/virtualmachine_sku

RMFR1 - Single Resource Only

ID: RMFR1 - Category: Composition - Single Resource Only

A resource module MUST only deploy a single instance of the primary resource, e.g., one virtual machine per instance.

Multiple instances of the module MUST be used to scale out.

RMFR2 - No Resource Wrapper Modules

ID: RMFR2 - Category: Composition - No Resource Wrapper Modules

A resource module MUST add value by including additional features on top of the primary resource.

RMFR3 - Resource Groups

ID: RMFR3 - Category: Composition - Resource Groups

A resource module MUST NOT create a Resource Group for resources that require them.

In the case that a Resource Group is required, a module MUST have an input (scope or variable):

In Bicep the targetScope MUST be set to resourceGroup or not specified (which means default to resourceGroup scope)
In Terraform the variable MUST be called resource_group_name

Scopes will be covered further in the respective language specific specifications.

RMFR4 - AVM Consistent Feature & Extension Resources Value Add

ID: RMFR4 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add

Resource modules support the following optional features/extension resources, as specified, if supported by the primary resource. The top-level variable/parameter names MUST be:

Optional Features/Extension Resources	Bicep Parameter Name	Terraform Variable Name	MUST/SHOULD
Diagnostic Settings	`diagnosticSettings`	`diagnostic_settings`	MUST
Role Assignments	`roleAssignments`	`role_assignments`	MUST
Resource Locks	`lock`	`lock`	MUST
Tags	`tags`	`tags`	MUST
Managed Identities (System / User Assigned)	`managedIdentities`	`managed_identities`	MUST
Private Endpoints	`privateEndpoints`	`private_endpoints`	MUST
Customer Managed Keys	`customerManagedKey`	`customer_managed_key`	MUST
Azure Monitor Alerts	`alerts`	`alerts`	SHOULD

Note

Tip

Make sure to checkout the language specific specifications for more info on this:

RMFR5 - AVM Consistent Feature & Extension Resources Value Add Interfaces/Schemas

ID: RMFR5 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add Interfaces/Schemas

See:

RMFR6 - Parameter/Variable Naming

ID: RMFR6 - Category: Inputs - Parameter/Variable Naming

Parameters/variables that pertain to the primary resource MUST NOT use the resource type in the name.

e.g., use sku, vs. virtualMachineSku/virtualmachine_sku

RMFR7 - Minimum Required Outputs

ID: RMFR7 - Category: Outputs - Minimum Required Outputs

Module owners MUST output the following outputs as a minimum in their modules:

Output	Bicep Output Name	Terraform Output Name
Resource Name	`name`	`name`
Resource ID	`resourceId`	`resource_id`
System Assigned Managed Identity Principal ID (if supported by module)	`systemAssignedMIPrincipalId`	`system_assigned_mi_principal_id`

Tip

Module owners MAY also have to provide additional outputs depending on the IaC language, please check the language specific specs:

RMFR8 - Dependency on child and other resources

ID: RMFR8 - Category: Composition - Dependency on child and other resources

A resource module MAY contain references to other resource modules, however MUST NOT contain references to non-AVM modules nor AVM pattern modules.

See BCPFR1 and TFFR1 for more information on this.

RMFR9 - End-of-life resource versions

ID: RMFR9 - Category: Composition - End-of-life resource versions

When a given version of an Azure resource used in a resource module reaches its end-of-life (EOL) and is no longer supported by Microsoft, the module owner SHOULD ensure that:

The module is aligned with these changes and only includes supported versions of the resource. This is typically achieved through the allowed values in the parameter that specifies the resource SKU or type.
The following notice is shown under the Notes section of the module’s readme.md. (If any related public announcement is available, it can also be linked to from the Notes section.):
“Certain versions of this Azure resource reached their end of life. The latest version of this module only includes supported versions of the resource. All unsupported versions have been removed from the related parameters.”
AND the related parameter’s description:
“Certain versions of this Azure resource reached their end of life. The latest version of this module only includes supported versions of the resource. All unsupported versions have been removed from this parameter.”

RMNFR1 - Module Naming

ID: RMNFR1 - Category: Naming - Module Naming

Note

This will be updated quarterly, or ad-hoc as new RPs/ Resources are created and highlighted via a check failure.

Resource modules MUST follow the below naming conventions (all lower case):

Bicep Resource Module Naming

Naming convention: avm/res/<hyphenated resource provider name>/<hyphenated ARM resource type> (module name for registry)
Example: avm/res/compute/virtual-machine or avm/res/managed-identity/user-assigned-identity
Segments:
- res defines this is a resource module
- <hyphenated resource provider name> is the resource provider’s name after the Microsoft part, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Compute = compute, Microsoft.ManagedIdentity = managed-identity.
- <hyphenated ARM resource type> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Compute/virtualMachines = virtual-machine, BUT Microsoft.Network/trafficmanagerprofiles = trafficmanagerprofile - since trafficmanagerprofiles is all lower case as per the ARM API definition.

Bicep Child Module Naming

Naming convention: avm/res/<hyphenated resource provider name>/<hyphenated ARM resource type>/<hyphenated child resource type/<hyphenated grandchild resource type>/<hyphenated great grandchild resource type>/<etc.> (module name for registry)
Example: avm/res/network/virtual-network/subnet or avm/res/storage/storage-account/blob-service/container
Segments:
- res defines this is a resource module
- <hyphenated resource provider name> is the resource provider’s name after the Microsoft part, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network = network.
- <hyphenated ARM resource type> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network/virtualNetworks = virtual-network.
- <hyphenated child resource type (to be repeated for grandchildren, etc.)> is the singular version of the word after the resource provider, with each word starting with a capital letter separated by dashes, e.g., Microsoft.Network/virtualNetworks/subnets = subnet or Microsoft.Storage/storageAccounts/blobServices/containers = blob-service/container.

Terraform Resource Module Naming

Naming convention:
- avm-res-<resource provider>-<ARM resource type> (module name for registry)
- terraform-<provider>-avm-res-<resource provider>-<ARM resource type> (GitHub repository name to meet registry naming requirements)
Example: avm-res-compute-virtualmachine or avm-res-managedidentity-userassignedidentity
Segments:
- <provider> is the logical abstraction of various APIs used by Terraform. In most cases, this is going to be azurerm or azuread for resource modules.
- res defines this is a resource module
- <resource provider> is the resource provider’s name after the Microsoft part, e.g., Microsoft.Compute = compute.
- <ARM resource type> is the singular version of the word after the resource provider, e.g., Microsoft.Compute/virtualMachines = virtualmachine

RMNFR2 - Parameter/Variable Naming

ID: RMNFR2 - Category: Inputs - Parameter/Variable Naming

A resource module MUST use the following standard inputs:

name (no default)
location (if supported by the resource and not a global resource, then use Resource Group location, if resource supports Resource Groups, otherwise no default)

RMNFR3 - RP Collaboration

ID: RMNFR3 - Category: Composition - RP Collaboration

Module owners (Microsoft FTEs) SHOULD reach out to the respective Resource Provider teams to build a partnership and collaboration on the modules creation, existence and long term maintenance.

Review this wiki page (Microsoft Internal) for more information.

SFR1 - Preview Services

ID: SFR1 - Category: Composition - Preview Services

Modules MAY create/adopt public preview services and features at their discretion.

Preview API versions MAY be used when:

The resource/service/feature is GA but the only API version available for the GA resource/service/feature is a preview version
- For example, Diagnostic Settings (Microsoft.Insights/diagnosticSettings) the latest version of the API available with GA features, like Category Groups etc., is 2021-05-01-preview
- Otherwise the latest “non-preview” version of the API SHOULD be used

Preview services and features, SHOULD NOT be promoted and exposed, unless they are supported by the respective PG, and it’s documented publicly.

However, they MAY be exposed at the module owners discretion, but the following rules MUST be followed:

The description of each of the parameters/variables used for the preview service/feature MUST start with:
- “THIS IS A <PARAMETER/VARIABLE> USED FOR A PREVIEW SERVICE/FEATURE, MICROSOFT MAY NOT PROVIDE SUPPORT FOR THIS, PLEASE CHECK THE PRODUCT DOCS FOR CLARIFICATION”

SFR2 - WAF Aligned

ID: SFR2 - Category: Composition - WAF Aligned

Well-Architected Framework (WAF)
Reliability Hub
Azure Proactive Resiliency Library (APRL)
- Only Product Group (PG) verified
Microsoft Defender for Cloud (MDFC)

They SHOULD NOT align to these recommendations when it requires an external dependency/resource to be deployed and configured and then associated to the resources in the module.

Alignment SHOULD prioritize best-practices and security over cost optimization, but MUST allow for these to be overridden by a module consumer easily, if desired.

Tip

Read the FAQ of What does AVM mean by “WAF Aligned”? for more detailed information and examples.

SFR3 - Deployment/Usage Telemetry

ID: SFR3 - Category: Telemetry - Deployment/Usage Telemetry

Important

These will also be provided as a comment on the module proposal, once accepted, from the AVM core team.

Modules MUST provide the capability to collect deployment/usage telemetry as detailed in Telemetry further.

Telemetry Information Notice

Note

The following information notice is automatically added at the bottom of the README.md file of the module when

Bicep: Using the utilities/tools/Set-AVMModule.ps1 utility
Terraform: Executing the make docs command with the note and header ## Data Collection being placed in the module’s _footer.md beforehand

### Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the [repository](https://aka.ms/avm/telemetry). There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at <https://go.microsoft.com/fwlink/?LinkID=824704>. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Bicep

Important

The value you need to use for your module is defined in the related module index. You can look it up on the index pages for Resource Modules, Pattern Modules and Utility Modules.

The ARM deployment name used for the telemetry MUST follow the pattern and MUST be no longer than 64 characters in length: 46d3xbcp.<res/ptn>.<(short) module name>.<version>.<uniqueness>

<res/ptn> == AVM Resource or Pattern Module
<(short) module name> == The AVM Module’s, possibly shortened, name including the resource provider and the resource type, without;
- The prefixes: avm-res-
- The prefixes: avm-ptn-
<version> == The AVM Module’s MAJOR.MINOR version (only) with . (periods) replaced with - (hyphens), to allow simpler splitting of the ARM deployment name
<uniqueness> == This section of the ARM deployment name is to be used to ensure uniqueness of the deployment name.
- This is to cater for the following scenarios:
  - The module is deployed multiple times to the same:
    - Location/Region
    - Scope (Tenant, Management Group,Subscription, Resource Group)

Note

An example deployment name for the AVM Virtual Machine Resource Module would be: 46d3xbcp.res.compute-virtualmachine.1-2-3.eum3

An example deployment name for a shortened module name would be: 46d3xbcp.res.desktopvirtualization-appgroup.1-2-3.eum3

Tip

Terraform: Terraform uses a telemetry provider, the configuration of which is the same for every module and is included in the template repo.

General: See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

Terraform

The modtm telemetry provider is included in all Terraform modules and is enabled by default through the main.telemetry.tf file being automatically distributed from the template repo.

The modtm provider MUST be listed under the required_providers section in the module’s terraform.tf file using the following entry. This is also validated by the linter.

terraform {
  required_providers {
    # .. other required providers as needed
    modtm = {
      source = "Azure/modtm"
      version = "~> 0.3"
    }
  }
}

SFR4 - Telemetry Enablement Flexibility

ID: SFR4 - Category: Telemetry - Telemetry Enablement Flexibility

The telemetry enablement MUST be on/enabled by default, however this MUST be able to be disabled by a module consumer by setting the below parameter/variable value to false:

Bicep: enableTelemetry
Terraform: enable_telemetry

Note

This general specification can be modified for some use-cases, that are language specific:

Bicep

For cross-references in resource modules, the spec BCPFR7 also applies.

Terraform

Currently, no further requirements apply.

SFR5 - Availability Zones

ID: SFR5 - Category: Composition - Availability Zones

Modules that deploy zone-redundant resources MUST enable the spanning across as many zones as possible by default, typically all 3.

For both scenarios the modules MUST expose these configuration options via configurable parameters/variables.

Note

For information on the differences between zonal and zone-redundant services, see Availability zone service and regional support

SFR6 - Data Redundancy

ID: SFR6 - Category: Composition - Data Redundancy

Note

For information on the data redundancy options in Azure, see Cross-region replication in Azure

SNFR1 - Prescribed Tests

ID: SNFR1 - Category: Testing - Prescribed Tests

Modules MUST use the prescribed tooling and testing frameworks defined in the language specific specs.

SNFR10 - MIT Licensing

ID: SNFR10 - Category: Contribution/Support - MIT Licensing

A module MUST be published with the MIT License in the Azure GitHub organization.

SNFR11 - Issues Response Times

ID: SNFR11 - Category: Contribution/Support - Issues Response Times

A module owner MUST respond to logged issues as defined in the support statement. See Module Support for more information.

SNFR12 - Versions Supported

ID: SNFR12 - Category: Contribution/Support - Versions Supported

Only the latest released version of a module MUST be supported.

This avoids AVM Module owners from having to maintain multiple major release versions.

SNFR14 - Data Types

ID: SNFR14 - Category: Inputs - Data Types

A module SHOULD use either: simple data types. e.g., string, int, bool.

Complex data types (objects, arrays, maps) when the language-compliant schema is defined.

SNFR15 - Automatic Documentation Generation

ID: SNFR15 - Category: Documentation - Automatic Documentation Generation

README documentation MUST be automatically/programmatically generated. MUST include the sections as defined in the language specific requirements BCPNFR2, TFNFR2.

SNFR16 - Examples/E2E

ID: SNFR16 - Category: Documentation - Examples/E2E

An examples/e2e directory MUST exist to provide named scenarios for module deployment.

SNFR17 - Semantic Versioning

ID: SNFR17 - Category: Release - Semantic Versioning

Important

See the Bicep Contribution Guide for more information.

Modules MUST use semantic versioning (aka semver) for their versions and releases in accordance with: Semantic Versioning 2.0.0

For example all modules should be released using a semantic version that matches this pattern: X.Y.Z

X == Major Version
Y == Minor Version
Z == Patch Version

Module versioning before first Major version release `1.0.0`

Initially modules MUST be released as version 0.1.0 and incremented via Minor and Patch versions only until the AVM Core Team are confident the AVM specifications are mature enough and appropriate CI test coverage is in place, plus the module owner is happy the module has been “road tested” and is now stable enough for its first Major release of version 1.0.0.
Note
Releasing as version 0.1.0 initially and only incrementing Minor and Patch versions allows the module owner to make breaking changes more easily and frequently as it’s still not an official Major/Stable release. 👍
Until first Major version 1.0.0 is released, given a version number X.Y.Z:
- X Major version MUST NOT be bumped.
- Y Minor version MUST be bumped when introducing breaking changes (which would normally bump Major after 1.0.0 release) or feature updates (same as it will be after 1.0.0 release).
- Z Patch version MUST be bumped when introducing non-breaking, backward compatible bug fixes (same as it will be after 1.0.0 release).

SNFR18 - Breaking Changes

ID: SNFR18 - Category: Release - Breaking Changes

A module SHOULD avoid breaking changes, e.g., deprecating inputs vs. removing. If you need to implement changes that cause a breaking change, the major version should be increased.

Info

Tip

See the language specific examples to find out how you can deal with deprecations in AVM modules.

Bicep

SNFR19 - Registries Targeted

ID: SNFR19 - Category: Publishing - Registries Targeted

Modules MUST be published to their respective language public registries.

Bicep = Bicep Public Module Registry
- Within the avm directory
Terraform = HashiCorp Terraform Registry

Tip

See the language specific contribution guides for detailed guidance and sample code to use in AVM modules to achieve this requirement.

SNFR2 - E2E Testing

ID: SNFR2 - Category: Testing - E2E Testing

Each test MUST run and complete without user inputs successfully, for automation purposes.

Each test MUST also destroy/clean-up its resources and test dependencies following a run.

Tip

To see a directory and file structure for a module, see the language specific contribution guide.

Resources/Dependencies Required for E2E Tests

It is likely that to complete E2E tests, a number of resources will be required as dependencies to enable the tests to pass successfully. Some examples:

When testing the Diagnostic Settings interface for a Resource Module, you will need an existing Log Analytics Workspace to be able to send the logs to as a destination.
When testing the Private Endpoints interface for a Resource Module, you will need an existing Virtual Network, Subnet and Private DNS Zone to be able to complete the Private Endpoint deployment and configuration.

Module owners MUST:

Create the required resources that their module depends upon in the test file/directory
- They MUST either use:
  - Simple/native resource declarations/definitions in their respective IaC language,
    OR
  - Another already published AVM Module that MUST be pinned to a specific published version.
    - They MUST NOT use any local directory path references or local copies of AVM modules in their own modules test directory.

➕ Terraform & Bicep Log Analytics Workspace examples using simple/native declarations for use in E2E tests

Terraform

resource "azurerm_resource_group" "example" {
  name     = "rsg-test-001"
  location = "West Europe"
}

resource "azurerm_log_analytics_workspace" "example" {
  name                = "law-test-001"
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  sku                 = "PerGB2018"
  retention_in_days   = 30
}

Bicep

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2021-12-01-preview' = {
  name: 'law-test-001'
  location: resourceGroup().location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
    retentionInDays: 30
  }
}

Skipping Deployments (SHOULD NOT)

Note

A skipped test case is still added to the ‘Usage Examples’ section of the module’s readme and should be manually validated in regular intervals.

Details for use in E2E tests

You MUST add a note to the tests metadata description, which explains the excemption.

Sample filecontent:

The test is skipped, as only one instance of this service can be deployed to a subscription.

Note

For resource modules, the ‘defaults’ and ‘waf-aligned’ tests can’t be skipped.

The deployment of a test can be skipped by adding a .e2eignore file into a test folder (e.g. /examples/<testname>).

SNFR20 - GitHub Teams Only

ID: SNFR20 - Category: Contribution/Support - GitHub Teams Only

All GitHub repositories that AVM module are published from and hosted within MUST only assign GitHub repository permissions to GitHub teams only.

Each module MUST have separate GitHub teams assigned for module owners AND module contributors respectively. These GitHub teams MUST be created in the Azure organization in GitHub.

There MUST NOT be any GitHub repository permissions assigned to individual users.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

Important

Naming Convention

The naming convention for the GitHub teams MUST follow the below pattern:

<hyphenated module name>-module-owners-<bicep/tf> - to be assigned as the GitHub repository’s Module Owners team
<hyphenated module name>-module-contributors-<bicep/tf> - to be assigned as the GitHub repository’s Module Contributors team

Note

The naming convention for Bicep modules is slightly different than the naming convention for their respective GitHub teams.

Segments:

<hyphenated module name> == the AVM Module’s name, with each segment separated by dashes, i.e., avm-res-<resource provider>-<ARM resource type>
- See RMNFR1 for AVM Resource Module Naming
- See PMNFR1 for AVM Pattern Module Naming
module-owners or module-contributors == the role the GitHub Team is assigned to
<bicep/tf> == the language the module is written in

Examples:

avm-res-compute-virtualmachine-module-owners-bicep
avm-res-compute-virtualmachine-module-contributors-tf

Add Team Members

All officially documented module owner(s) MUST be added to the -module-owners- team. The -module-owners- team MUST NOT have any other members.

Any additional module contributors whom the module owner(s) agreed to work with MUST be added to the -module-contributors- team.

Grant Permissions - Bicep

Team memberships

Note

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<hyphenated module name>-module-owners-bicep`	AVM Bicep Module Owners - <module name>	Write	Assignment to the `avm-technical-reviewers-bicep` parent team.	Need to work in a fork.
`<hyphenated module name>-module-contributors-bicep`	AVM Bicep Module Contributors - <module name>	Triage	`avm-module-contributors-bicep` parent team.	Need to work in a fork.

Examples - GitHub teams required for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

avm-res-network-virtualnetwork-module-owners-bicep –> assign to the avm-technical-reviewers-bicep parent team.
avm-res-network-virtualnetwork-module-contributors-bicep –> assign to the avm-module-contributors-bicep parent team.

Tip

Direct link to create a new GitHub team and assign it to its parent: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Follow the guidance above (see the Permissions granted through column in the table above).
Team visibility: Visible
Team notifications: Enabled

CODEOWNERS file

As part of the “initial Pull Request” (that publishes the first version of the module), module owners MUST add an entry to the CODEOWNERS file in the BRM repository (here).

Note

Through this approach, the AVM core team will grant review permission to module owners as part of the standard PR review process.

Every CODEOWNERS entry (line) MUST include the following segments separated by a single whitespace character:

Path of the module, relative to the repo’s root, e.g.: /avm/res/network/virtual-network/
The -module-owners-team, with the @Azure/ prefix, e.g., @Azure/avm-res-network-virtualnetwork-module-owners-bicep
The GitHub team of the AVM Bicep reviewers, with the @Azure/ prefix, i.e., @Azure/avm-module-reviewers-bicep

Example - CODEOWNERS entry for the Bicep resource module of Azure Virtual Network (avm/res/network/virtual-network):

/avm/res/network/virtual-network/ @Azure/avm-res-network-virtualnetwork-module-owners-bicep @Azure/avm-module-reviewers-bicep

Grant Permissions - Terraform

Module owners MUST assign the -module-owners-and -module-contributors- teams the necessary permissions on their Terraform module repository per the guidance below.

GitHub Team Name	Description	Permissions	Permissions granted through	Where to work?
`<module name>-module-owners-tf`	AVM Terraform Module Owners - <module name>	Admin	Direct assignment to repo	Module owner can decide whether they want to work in a branch local to the repo or in a fork.
`<module name>-module-contributors-tf`	AVM Terraform Module Contributors - <module name>	Write	Direct assignment to repo	Need to work in a fork.

Tip

Direct link to create a new GitHub team: Create new team

Fill in the values as follows:

Team name: Following the naming convention described above, use the value defined in the module indexes.
Description: Follow the guidance above (see the Description column in the table above).
Parent team: Do not assign the team to any parent team.
Team visibility: Visible
Team notifications: Enabled

SNFR21 - Cross Language Collaboration

ID: SNFR21 - Category: Publishing - Cross Language Collaboration

SNFR22 - Parameters/Variables for Resource IDs

ID: SNFR22 - Category: Inputs - Parameters/Variables for Resource IDs

workspaceId is not descriptive enough and is ambiguous as to which ID is required to be input.

SNFR23 - GitHub Repo Labels

ID: SNFR23 - Category: Contribution/Support - GitHub Repo Labels

GitHub repositories where modules are held MUST use the below labels and SHOULD not use any additional labels:

➕ AVM Standard GitHub Labels

These labels are available in a CSV file from here

Name	Description	HEX
AZD 🧑‍💻	These modules are requested/used by the AZD team.	`E0BFFA`
Needs: Attention 👋	Reply has been added to issue, maintainer to review	`E99695`
Needs: Immediate Attention ‼️	Immediate attention of module owner / AVM team is needed	`FF0000`
Needs: Author Feedback 👂	Awaiting feedback from the issue/PR author	`F18A07`
Needs: External Changes ⚒️	When an issue/PR requires changes that are outside of the control of the module. e.g. to an RP.	`DE389D`
Needs: More Evidence ⚖	We are looking for more evidence to make a decision on this	`F64872`
Needs: Triage 🔍	Maintainers need to triage still	`FBCA04`
Needs: Module Owner 📣	In the AVM repository: this module needs an owner to develop or maintain it. In the BRM repository: the module owner needs to review a PR.	`FF0019`
Needs: Module Contributor 📣	This module needs secondary owner(s) or contributor(s) to develop or maintain it	`C95474`
Needs: Core Team 🧞‍♂️	This item needs the AVM Core Team to review it	`DB4503`
Status: Awaiting Release To Be Cut ✂️	This is fixed in the main branch but not in the latest release, will be fixed with next release cut	`800080`
Status: Do Not Merge ⛔	Do not merge PRs with this label attached as they are not ready or aligned to future direction etc.	`8B4513`
Status: External Contribution 🌍	This is being worked on by someone outside of the AVM module owners/contributors or AVM core team	`D8FA2C`
Status: Fixed ✅	Auto label applied when issue fixed by merged PR	`90EE90`
Status: Help Wanted 🆘	Extra attention is needed	`FF4500`
Status: In Triage 🔍	Picked up for triaging by an AVM core team member	`D4AF37`
Status: In PR 👉	This is when an issue is due to be fixed in an open PR	`EDEDED`
Status: Invalid ❌	This doesn't seem right	`E4E669`
Status: Long Term ⏳	We will do it, but will take a longer amount of time due to complexity/priorities	`B60205`
Status: No Recent Activity 💤	When an issue/PR has not been modified for X amount of days	`808080`
Status: Won't Fix 💔	This will not be worked on	`FFFFFF`
Status: Owners Identified 🤘	This module has its owners identified	`FBEF2A`
Status: Module Available 🟢	The module is published	`C8E6C9`
Status: Module Deprecated 🔴	This is a request to deprecate a module	`000000`
Status: Module Orphaned 🟡	The module has no owner and is therefore orphaned at this time	`F4A460`
Status: Ready For Repository Creation 📝	This module is approved and the owner is ready for the repository to be created (Terraform)	`136A41`
Status: Repository Created 📄	This module has had it's repository created and configured ready for owner contribution (Terraform)	`27AB03`
Status: Response Overdue 🚩	When an issue/PR has not been responded to for X amount of days	`850000`
Status: Looking For Assistance 🦆	This item is looking for anyone to help develop the code and submit a PR for resolution	`03FCC2`
Type: Bug 🐛	Something isn't working	`D73A4A`
Type: CI 🚀	This issue is related to the AVM CI	`74CFB0`
Type: Documentation 📄	Improvements or additions to documentation	`0075CA`
Type: Duplicate 🤲	This issue or pull request already exists	`CFD3D7`
Type: Feature Request ➕	New feature or request	`A2EEEF`
Type: Hygiene 🧹	things related to testing, issue triage etc.	`17016A`
Type: New Module Proposal 💡	A new module for AVM is being proposed	`ADD8E6`
Type: Question/Feedback 🙋‍♀️	Further information is requested or just some feedback	`CB6BA2`
Type: Security Bug 🔒	This is a security bug	`FFFF00`
Type: AVM 🅰️ ✌️ ⓜ️	This is an AVM related issue	`F0FFFF`
Language: Terraform 🌐	This is related to the Terraform IaC language	`7740B6`
Language: Bicep 💪	This is related to the Bicep IaC language	`1D73B3`
Class: Resource Module 📦	This is a resource module	`D3D3D3`
Class: Pattern Module 📦	This is a pattern module	`A9A9A9`
Class: Utility Module 📦	This is a utility module	`CAD1DE`
Class: Child Module 📦	This is a child module	`5E5186`

To help apply these to a module GitHub repository you can use the below PowerShell script:

➕ Set-AvmGitHubLabels.ps1

For most scenario this is the command you’ll need to call the below PowerShell script with, replacing the value for RepositoryName:

  Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -CreateCsvLabelExports $false -NoUserPrompts $true

```shell
# Linux / MacOs
# For Windows replace $PWD with your the local path or your repository
#
docker run -it -v $PWD:/repo -w /repo mcr.microsoft.com/powershell pwsh -Command '
    #Invoke-WebRequest -Uri "https://azure.github.io/Azure-Verified-Modules/scripts/Set-AvmGitHubLabels.ps1" -OutFile "Set-AvmGitHubLabels.ps1"
    $gh_version = "2.44.1"
    Invoke-WebRequest -Uri "https://github.com/cli/cli/releases/download/v2.44.1/gh_2.44.1_linux_amd64.tar.gz" -OutFile "gh_$($gh_version)_linux_amd64.tar.gz"
    apt-get update && apt-get install -y git
    tar -xzf "gh_$($gh_version)_linux_amd64.tar.gz"
    ls -lsa
    mv "gh_$($gh_version)_linux_amd64/bin/gh" /usr/local/bin/
    rm "gh_$($gh_version)_linux_amd64.tar.gz" && rm -rf "gh_$($gh_version)_linux_amd64"
    gh --version
    ls -lsa
    gh auth login
    $OrgProject = "Azure/terraform-azurerm-avm-res-kusto-cluster"
    gh auth status
    ./Set-AvmGitHubLabels.ps1 -RepositoryName $OrgProject -CreateCsvLabelExports $false -NoUserPrompts $true

  '
```

Full Script:

These Set-AvmGitHubLabels.ps1 can be downloaded from here.

  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "", Justification = "Coloured output required in this script")]
  
  <#
  .SYNOPSIS
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
  .DESCRIPTION
    This script can be used to create the Azure Verified Modules (AVM) standard GitHub labels to a GitHub repository.
  
    By default, the script will remove all pre-existing labels and apply the AVM labels. However, this can be changed by using the -RemoveExistingLabels parameter and setting it to $false. The tool will also output the labels that exist in the repository before and after the script has run to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter.
  
    The AVM labels to be created are documented here: TBC
  
  .NOTES
    Please ensure you have specified the GitHub repositry correctly. The script will prompt you to confirm the repository name before proceeding.
  
  .COMPONENT
    You must have the GitHub CLI installed and be authenticated to a GitHub account with access to the repository you are applying the labels to before running this script.
  
  .LINK
    TBC
  
  .Parameter RepositoryName
    The name of the GitHub repository to apply the labels to.
  
  .Parameter RemoveExistingLabels
    If set to $true, the default value, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will not remove any pre-existing labels.
  
  .Parameter UpdateAndAddLabelsOnly
    If set to $true, the default value, the script will only update and add labels to the repository specified in -RepositoryName. If set to $false, the script will remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
  .Parameter OutputDirectory
    The directory to output the pre-existing and post-existing labels to in a CSV file. The default value is the current directory.
  
  .Parameter CreateCsvLabelExports
    If set to $true, the default value, the script will output the pre-existing and post-existing labels to a CSV file in the current directory, or a directory specified by the -OutputDirectory parameter. If set to $false, the script will not output the pre-existing and post-existing labels to a CSV file.
  
  .Parameter GitHubCliLimit
    The maximum number of labels to return from the GitHub CLI. The default value is 999.
  
  .Parameter LabelsToApplyCsvUri
    The URI to the CSV file containing the labels to apply to the GitHub repository. The default value is https://raw.githubusercontent.com/jtracey93/label-source/main/avm-github-labels.csv.
  
  .Parameter NoUserPrompts
    If set to $true, the default value, the script will not prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels. If set to $false, the script will prompt the user to confirm they want to remove all pre-existing labels from the repository specified in -RepositoryName before applying the AVM labels.
  
    This is useful for running the script in automation workflows
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and remove all pre-existing labels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels"
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and output the pre-existing and post-existing labels to the directory C:\GitHubLabels and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -RemoveExistingLabels $false -CreateCsvLabelExports $false
  
  .EXAMPLE
    Create the AVM labels in the repository Org/MyGitHubRepo and do not create the pre-existing and post-existing labels CSV files and do not remove any pre-existing labels, just overwrite any labels that have the same name. Finally, use a custom CSV file hosted on the internet to create the labels from.
  
    Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -OutputDirectory "C:\GitHubLabels" -RemoveExistingLabels $false -CreateCsvLabelExports $false -LabelsToApplyCsvUri "https://example.com/csv/avm-github-labels.csv"
  
  #>
  
  #Requires -PSEdition Core
  
  [CmdletBinding()]
  param (
    [Parameter(Mandatory = $true)]
    [string]$RepositoryName,
  
    [Parameter(Mandatory = $false)]
    [bool]$RemoveExistingLabels = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$UpdateAndAddLabelsOnly = $true,
  
    [Parameter(Mandatory = $false)]
    [bool]$CreateCsvLabelExports = $true,
  
    [Parameter(Mandatory = $false)]
    [string]$OutputDirectory = (Get-Location),
  
    [Parameter(Mandatory = $false)]
    [int]$GitHubCliLimit = 999,
  
    [Parameter(Mandatory = $false)]
    [string]$LabelsToApplyCsvUri = "https://azure.github.io/Azure-Verified-Modules/governance/avm-standard-github-labels.csv",
  
    [Parameter(Mandatory = $false)]
    [bool]$NoUserPrompts = $false
  )
  
  # Check if the GitHub CLI is installed
  $GitHubCliInstalled = Get-Command gh -ErrorAction SilentlyContinue
  if ($null -eq $GitHubCliInstalled) {
    throw "The GitHub CLI is not installed. Please install the GitHub CLI and try again."
  }
  Write-Host "The GitHub CLI is installed..." -ForegroundColor Green
  
  # Check if GitHub CLI is authenticated
  $GitHubCliAuthenticated = gh auth status
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubCliAuthenticated -ForegroundColor Red
    throw "Not authenticated to GitHub. Please authenticate to GitHub using the GitHub CLI, `gh auth login`, and try again."
  }
  Write-Host "Authenticated to GitHub..." -ForegroundColor Green
  
  # Check if GitHub repository name is valid
  $GitHubRepositoryNameValid = $RepositoryName -match "^[a-zA-Z0-9-]+/[a-zA-Z0-9-]+$"
  if ($false -eq $GitHubRepositoryNameValid) {
    throw "The GitHub repository name $RepositoryName is not valid. Please check the repository name and try again. The format must be <OrgName>/<RepoName>"
  }
  
  # List GitHub repository provided and check it exists
  $GitHubRepository = gh repo view $RepositoryName
  if ($LASTEXITCODE -ne 0) {
    Write-Host $GitHubRepository -ForegroundColor Red
    throw "The GitHub repository $RepositoryName does not exist. Please check the repository name and try again."
  }
  Write-Host "The GitHub repository $RepositoryName exists..." -ForegroundColor Green
  
  # PRE - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($RemoveExistingLabels -or $UpdateAndAddLabelsOnly) {
    Write-Host "Getting the current GitHub repository (pre) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels -and $CreateCsvLabelExports -eq $true) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Pre-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (pre) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # Remove all pre-existing labels if -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels
  if ($null -ne $GitHubRepositoryLabels) {
    $GitHubRepositoryLabelsJson = $GitHubRepositoryLabels | ConvertFrom-Json
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $false -and $UpdateAndAddLabelsOnly -eq $false) {
      $RemoveExistingLabelsConfirmation = Read-Host "Are you sure you want to remove all $($GitHubRepositoryLabelsJson.Count) pre-existing labels from $($RepositoryName)? (Y/N)"
      if ($RemoveExistingLabelsConfirmation -eq "Y") {
        Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
        $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
          Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
          gh label delete -R $RepositoryName $_.name --yes
        }
      }
    }
    if ($RemoveExistingLabels -eq $true -and $NoUserPrompts -eq $true -and $UpdateAndAddLabelsOnly -eq $false) {
      Write-Host "Removing all pre-existing labels from $RepositoryName..." -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
        Write-Host "Removing label $($_.name) from $RepositoryName..." -ForegroundColor DarkRed
        gh label delete -R $RepositoryName $_.name --yes
      }
    }
  }
  if ($null -eq $GitHubRepositoryLabels) {
    Write-Host "No pre-existing labels to remove or not selected to be removed from $RepositoryName..." -ForegroundColor Magenta
  }
  
  # Check LabelsToApplyCsvUri is valid and contains a CSV content
  Write-Host "Checking $LabelsToApplyCsvUri is valid..." -ForegroundColor Yellow
  $LabelsToApplyCsvUriValid = $LabelsToApplyCsvUri -match "^https?://"
  if ($false -eq $LabelsToApplyCsvUriValid) {
    throw "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is not valid. Please check the URI and try again. The format must be a valid URI."
  }
  Write-Host "The LabelsToApplyCsvUri $LabelsToApplyCsvUri is valid..." -ForegroundColor Green
  
  # Create AVM lables from the AVM labels CSV file stored on the web using the convertfrom-csv cmdlet
  $avmLabelsCsv = Invoke-WebRequest -Uri $LabelsToApplyCsvUri | ConvertFrom-Csv
  
  # Check if the AVM labels CSV file contains the following columns: Name, Description, HEX
  $avmLabelsCsvColumns = $avmLabelsCsv | Get-Member -MemberType NoteProperty | Select-Object -ExpandProperty Name
  $avmLabelsCsvColumnsValid = $avmLabelsCsvColumns -contains "Name" -and $avmLabelsCsvColumns -contains "Description" -and $avmLabelsCsvColumns -contains "HEX"
  if ($false -eq $avmLabelsCsvColumnsValid) {
    throw "The labels CSV file does not contain the required columns: Name, Description, HEX. Please check the CSV file and try again. It contains the following columns: $avmLabelsCsvColumns"
  }
  Write-Host "The labels CSV file contains the required columns: Name, Description, HEX" -ForegroundColor Green
  
  # Create the AVM labels in the GitHub repository
  Write-Host "Creating/Updating the $($avmLabelsCsv.Count) AVM labels in $RepositoryName..." -ForegroundColor Yellow
  $avmLabelsCsv | ForEach-Object {
    if ($GitHubRepositoryLabelsJson.name -contains $_.name) {
      Write-Host "The label $($_.name) already exists in $RepositoryName. Updating the label to ensure description and color are consitent..." -ForegroundColor Magenta
      gh label create -R $RepositoryName "$($_.name)" -c $_.HEX -d $($_.Description) --force
    }
    else {
      Write-Host "The label $($_.name) does not exist in $RepositoryName. Creating label $($_.name) in $RepositoryName..." -ForegroundColor Cyan
      gh label create -R $RepositoryName "$($_.Name)" -c $_.HEX -d $($_.Description) --force
    }
  }
  
  # POST - Get the current GitHub repository labels and export to a CSV file in the current directory or where -OutputDirectory specifies if set to a valid directory path and the directory exists or can be created if it does not exist already
  if ($CreateCsvLabelExports -eq $true) {
    Write-Host "Getting the current GitHub repository (post) labels for $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
  
    if ($null -ne $GitHubRepositoryLabels) {
      $csvFileNamePathPre = "$OutputDirectory\$($RepositoryName.Replace('/', '_'))-Labels-Post-$(Get-Date -Format FileDateTime).csv"
      Write-Host "Exporting the current GitHub repository (post) labels for $RepositoryName to $csvFileNamePathPre" -ForegroundColor Yellow
      $GitHubRepositoryLabels | ConvertFrom-Json | Export-Csv -Path $csvFileNamePathPre -NoTypeInformation
    }
  }
  
  # If -RemoveExistingLabels is set to $true and user confirms they want to remove all pre-existing labels check that only the avm labels exist in the repository
  if ($RemoveExistingLabels -eq $true -and ($RemoveExistingLabelsConfirmation -eq "Y" -or $NoUserPrompts -eq $true) -and $UpdateAndAddLabelsOnly -eq $false) {
    Write-Host "Checking that only the AVM labels exist in $RepositoryName..." -ForegroundColor Yellow
    $GitHubRepositoryLabels = gh label list -R $RepositoryName -L $GitHubCliLimit --json name,description,color
    $GitHubRepositoryLabels | ConvertFrom-Json | ForEach-Object {
      if ($avmLabelsCsv.Name -notcontains $_.name) {
        throw "The label $($_.name) exists in $RepositoryName but is not in the CSV file."
      }
    }
    Write-Host "Only the CSV labels exist in $RepositoryName..." -ForegroundColor Green
  }
  
  Write-Host "The CSV labels have been created/updated in $RepositoryName..." -ForegroundColor Green

SNFR24 - Testing Child, Extension & Interface Resources

ID: SNFR24 - Category: Testing - Testing Child, Extension & Interface Resources

These MAY be tested in a separate E2E test and DO NOT have to be tested in each E2E test.

SNFR25 - Resource Naming

ID: SNFR25 - Category: Composition - Resource Naming

Module owners MUST also provide the ability for these default names, including the prefixes, to be overridden via a parameter/variable if the consumer wishes to.

Tip

If the resource does not have a documented abbreviation in Abbreviation examples for Azure resources, then the module owner is free to use a sensible prefix instead.

SNFR26 - Output - Parameters - Decorators

ID: SNFR26 - Output-Parameters - Decorators

Output parameters MUST implement:

Decorators in Bicep such as description & secure (if sensitive)
Arguments in Terraform such as description & sensitive (if sensitive)

Output parameters

@description('The resourceId of your resource.')
output sampleResourceId string = sampleResource.id

@description('The key of your resource.')
@secure()
output sampleResourceKey string = sampleResource.key

# Resource output
output "foo" {
  description = "MyResource foo attribute"
  value = azurerm_resource_myresource.foo
}

# Output of a sensitive attribute
output "bar" {
  description = "MyResource bar attribute"
  value     = azurerm_resource_myresource.bar
  sensitive = true
}

SNFR3 - AVM Compliance Tests

ID: SNFR3 - Category: Testing - AVM Compliance Tests

Modules MUST pass all tests that ensure compliance to AVM specifications. These tests MUST pass before a module version can be published.

Important

Please note these are still under development at this time and will be published and available soon for module owners.

SNFR4 - Unit Tests

ID: SNFR4 - Category: Testing - Unit Tests

Unit Tests test specific module functionality, without deploying resources. Used on more complex modules. In Bicep and Terraform these live in tests/unit.

SNFR5 - Upgrade Tests

ID: SNFR5 - Category: Testing - Upgrade Tests

Modules SHOULD implement upgrade testing to ensure new features are implemented in a non-breaking fashion on non-major releases.

SNFR6 - Static Analysis/Linting Tests

ID: SNFR6 - Category: Testing - Static Analysis/Linting Tests

Modules MUST use static analysis, e.g., linting, security scanning (PSRule, tflint, etc.). These tests MUST pass before a module version can be published.

There may be differences between languages in linting rules standards, but the AVM core team will try to close these and bring them into alignment over time.

SNFR7 - Idempotency Tests

ID: SNFR7 - Category: Testing - Idempotency Tests

Modules MUST implement idempotency end-to-end (deployment) testing. E.g. deploying the module twice over the top of itself.

Modules SHOULD pass the idempotency test, as we are aware that there are some exceptions where they may fail as a false-positive or legitimate cases where a resource cannot be idempotent.

For example, Virtual Machine Image names must be unique on each resource creation/update.

SNFR8 - Module Owner(s) GitHub

ID: SNFR8 - Category: Contribution/Support - Module Owner(s) GitHub

A module MUST have an owner that is defined and managed by a GitHub Team in the Azure GitHub organization.

Note

The names for the GitHub teams for each approved module are already defined in the respective Module Indexes. These teams MUST be created (and used) for each module.

SNFR9 - AVM & PG Teams GitHub Repo Permissions

ID: SNFR9 - Category: Contribution/Support - AVM & PG Teams GitHub Repo Permissions

A module owner MUST make the following GitHub teams in the Azure GitHub organization admins on the GitHub repo of the module in question:

Bicep

@Azure/avm-core-team-technical-bicep = AVM Core Team
@Azure/bicep-admins = Bicep PG team

Note

These required GitHub teams are already associated to the BRM repository and have the required permissions.

Terraform

@Azure/avm-core-team-technical-terraform = AVM Core Team
@Azure/terraform-avm = Terraform PG

Important

Module owners MUST assign these GitHub teams as admins on the GitHub repo of the module in question.

For detailed steps, please follow this guidance.

Team Definitions & RACI

Teams

In AVM there will be multiple different teams involved throughout the initiatives lifecycle and ongoing long-term support. These teams will be listed below alongside their definitions.

Important

Individuals can be members of multiple teams, at once, that are defined below.

AVM Core Team

GitHub Team: @Azure/avm-core-team

The AVM core team are responsible for:

Specifications
- Shared
- Language Specific
Contribution Guidance
Test Frameworks & Tooling
Initiative Governance
- Module Lifecycle
- Test Enforcement
- Module Support SLAs
Anything else not defined below for another team or in the RACI 👍

The team is made up of both technical and non-technical team members that are all Microsoft FTEs.

Module Owners

Important

Today, module owners MUST be Microsoft FTEs. This is to ensure that within AVM the long-term support for each module can be upheld and honoured.

Module owners are responsible for:

Module Creation
Module Maintenance (proactive & reactive)
Module Issue/Pull Request Triage & Resolution
Module Feature Request Triage & Additions
Managing Module Contributors

Ideally there SHOULD be at least 2 module owners per module and MUST be in a GitHub Team in the Azure organization.

Module Contributors

Important

Module Contributors can be anyone in any organization. However, they must be an active contributor and supporting the Module Owners.

Module Contributors are responsible for:

Assisting the Module Owners with their responsibilities

Module Contributors MUST be in a separate GitHub Team in the Azure organization, that the Module Owners manage and are maintainers of.

Product Groups

GitHub Teams:

@Azure/bicep-admins = Bicep PG team
@Azure/terraform-avm = Azure Terraform PG

The Azure Bicep & Terraform Product Groups are responsible for:

Backup/Additional support for orphaned modules to the AVM Core Team
Providing inputs and feedback on AVM
Taking on feedback and feature requests on their products, Bicep & Terraform, from AVM usage

Note

We are investigating working with all Azure Product Groups as a future investment area that they take on ownership, or contribute to, the AVM modules for their service/product.

RACI

RACI Definition

R = Responsible – Those who do the work to complete the task/responsibility.

A = Accountable – The one answerable for the correct and thorough completion of the task. There must be only one accountable person per task/responsibility. Typically has ‘sign-off’.

C = Consulted – Those whose opinions are sought.

I = Informed – Those who are kept up to date on progress.

The below table defines a RACI that is proposed to be adopted by AVM and all parties referenced in the table. This will give consumers faith and trust in these modules so that they can consume and contribute to the initiative at scale.

Action/Task/Responsibility	Module Owners	Module Contributors	AVM Core Team	Product Groups
Build/Construct an AVM Module	R, A	R, C	C, I	I
Publish a Bicep AVM Module to the Bicep Public Registry	R, A	C, I	C, I	I
Publish a Terraform AVM Module to the Terraform Registry	R, A	C, I	C, I	I
Manage and maintain tooling/testing frameworks pertaining to module quality	C, I	C, I	R, A	C, I
Manage/run the AVM central backlog (module proposals, orphaned modules, test enhancements, etc.)	C, I	C, I	R, A	C, I
Provide day-to-day (BAU) module support	R, A	R, C	I	I
Provide security fixes for orphaned modules	N/A	N/A	R, A	R, C, I

TFFR1 - Cross-Referencing Modules

ID: TFFR1 - Category: Composition - Cross-Referencing Modules

module "other-module" {
  source  = "Azure/xxx/azurerm"
  version = "1.2.3"
}

They MUST NOT use git reference to a module.

module "other-module" {
  source = "git::https://xxx.yyy/xxx.git"
}

module "other-module" {
  source = "github.com/xxx/yyy"
}

Modules MUST NOT contain references to non-AVM modules.

Tip

See Module Sources for more information.

TFFR2 - Additional Terraform Outputs

ID: TFFR2 - Category: Outputs - Additional Terraform Outputs

Remember, you SHOULD NOT output values that are already inputs (other than name).

E.g.,

# Resource output, computed attribute.
output "foo" {
  description = "MyResource foo attribute"
  value = azurerm_resource_myresource.foo
}

# Resource output for resources that are deployed using `for_each`. Again only computed attributes.
output "childresource_foos" {
  description = "MyResource children's foo attributes"
  value = {
    for key, value in azurerm_resource_mychildresource : key => value.foo
  }
}

# Output of a sensitive attribute
output "bar" {
  description = "MyResource bar attribute"
  value     = azurerm_resource_myresource.bar
  sensitive = true
}

TFFR3 - Providers - Permitted Versions

ID: TFFR3 - Category: Providers - Permitted Versions

Authors MUST only use the following Azure providers, and versions, in their modules:

provider	min version	max version
azapi	>= 2.0	< 3.0
azurerm	>= 4.0	< 5.0

Note

Authors MAY select either Azurerm, Azapi, or both providers in their module.

Authors MUST use the required_providers block in their module to enforce the provider versions.

The following is an example.

In it we use the pessimistic version constraint operator ~>.
That is to say that ~> 4.0 is equivalent to >= 4.0, < 5.0.

terraform {
  required_providers {
    # Include one or both providers, as needed
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
  }
}

TFNFR1 - Descriptions

ID: TFNFR1 - Category: Documentation - Descriptions

Where descriptions for variables and outputs spans multiple lines. The description MAY provide variable input examples for each variable using the HEREDOC format and embedded markdown.

Example:

  variable "my_complex_input" {
    type = map(object({
      param1 = string
      param2 = optional(number, null)
    }))
    description = <<DESCRIPTION
  A complex input variable that is a map of objects.
  Each object has two attributes:
  
  - `param1`: A required string parameter.
  - `param2`: (Optional) An optional number parameter.
  
  Example Input:
  
  ```terraform
  my_complex_input = {
    "object1" = {
      param1 = "value1"
      param2 = 2
    }
    "object2" = {
      param1 = "value2"
    }
  }
  ```
  DESCRIPTION
  }

TFNFR10 - No Double Quotes in ignore_changes

ID: TFNFR10 - Category: Code Style - No Double Quotes in ignore_changes

The ignore_changes attribute MUST NOT be enclosed in double quotes.

Good example:

lifecycle {
    ignore_changes = [
      tags,
    ]
}

Bad example:

lifecycle {
    ignore_changes = [
      "tags",
    ]
}

TFNFR11 - Null Comparison Toggle

ID: TFNFR11 - Category: Code Style - Null Comparison Toggle

Intuitively, we will define it like this:

variable "security_group_id" {
  type: string
}

resource "azurerm_network_security_group" "this" {
  count               = var.security_group_id == null ? 1 : 0
  name                = coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
  resource_group_name = var.resource_group_name
  location            = local.location
  tags                = var.new_network_security_group_tags
}

You can’t do this:

resource "azurerm_network_security_group" "foo" {
  name                = "example-nsg"
  resource_group_name = "example-rg"
  location            = "eastus"
}

module "bar" {
  source = "xxxx"
  ...
  security_group_id = azurerm_network_security_group.foo.id
}

For this kind of parameters, wrapping with object type is RECOMMENDED:

variable "security_group" {
  type: object({
    id   = string
  })
  default     = null
}

resource "azurerm_network_security_group" "foo" {
  name                = "example-nsg"
  resource_group_name = "example-rg"
  location            = "eastus"
}

module "bar" {
  source = "xxxx"
  ...
  security_group = {
    id = azurerm_network_security_group.foo.id
  }
}

This technique SHOULD be used under this use case only.

TFNFR12 - Dynamic for Optional Nested Objects

ID: TFNFR12 - Category: Code Style - Dynamic for Optional Nested Objects

An example from the community:

resource "azurerm_kubernetes_cluster" "main" {
  ...
  dynamic "identity" {
    for_each = var.client_id == "" || var.client_secret == "" ? [1] : []

    content {
      type                      = var.identity_type
      user_assigned_identity_id = var.user_assigned_identity_id
    }
  }
  ...
}

Please refer to the coding style in the example. Nested blocks under conditions, MUST be declared as:

for_each = <condition> ? [<some_item>] : []

TFNFR13 - Default Values with coalesce/try

ID: TFNFR13 - Category: Code Style - Default Values with coalesce/try

The following example shows how "${var.subnet_name}-nsg" SHOULD be used when var.new_network_security_group_name is null or ""

Good examples:

coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")

try(coalesce(var.new_network_security_group.name, "${var.subnet_name}-nsg"), "${var.subnet_name}-nsg")

Bad examples:

var.new_network_security_group_name == null ? "${var.subnet_name}-nsg" : var.new_network_security_group_name)

TFNFR14 - Not allowed variables

ID: TFNFR14 - Category: Inputs - Not allowed variables

TFNFR15 - Variable Definition Order

ID: TFNFR15 - Category: Code Style - Variable Definition Order

Input variables SHOULD follow this order:

All required fields, in alphabetical order
All optional fields, in alphabetical order

A variable without default value is a required field, otherwise it’s an optional one.

TFNFR16 - Variable Naming Rules

ID: TFNFR16 - Category: Code Style - Variable Naming Rules

The naming of a variable SHOULD follow HashiCorp’s naming rule.

variable used as feature switches SHOULD apply a positive statement, use xxx_enabled instead of xxx_disabled. Avoid double negatives like !xxx_disabled.

Please use xxx_enabled instead of xxx_disabled as name of a variable.

TFNFR17 - Variables with Descriptions

ID: TFNFR17 - Category: Code Style - Variables with Descriptions

The target audience of description is the module users.

For object type variable, description can be composed in HEREDOC format:

variable "kubernetes_cluster_key_management_service" {
  type: object({
    key_vault_key_id         = string
    key_vault_network_access = optional(string)
  })
  default     = null
  description = <<-EOT
  - `key_vault_key_id` - (Required) Identifier of Azure Key Vault key. See [key identifier format](https://learn.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name) for more details. When Azure Key Vault key management service is enabled, this field is required and must be a valid key identifier. When `enabled` is `false`, leave the field empty.
  - `key_vault_network_access` - (Optional) Network access of the key vault Network access of key vault. The possible values are `Public` and `Private`. `Public` means the key vault allows public access from all networks. `Private` means the key vault disables public access and enables private link. Defaults to `Public`.
EOT
}

TFNFR18 - Variables with Types

ID: TFNFR18 - Category: Code Style - Variables with Types

type MUST be defined for every variable. type SHOULD be as precise as possible, any MAY only be defined with adequate reasons.

Use bool instead of string or number for true/false
Use string for text
Use concrete object instead of map(any)

TFNFR19 - Sensitive Data Variables

ID: TFNFR19 - Category: Code Style - Sensitive Data Variables

TFNFR2 - Module Documentation Generation

ID: TFNFR2 - Category: Documentation - Module Documentation Generation

Terraform modules documentation MUST be automatically generated via Terraform Docs.

A file called .terraform-docs.yml MUST be present in the root of the module and have the following content:

  ---
  ### To generate the output file to partially incorporate in the README.md,
  ### Execute this command in the Terraform module's code folder:
  # terraform-docs -c .terraform-docs.yml .
  
  formatter: "markdown document" # this is required
  
  version: "0.16.0"
  
  header-from: "_header.md"
  footer-from: "_footer.md"
  
  recursive:
    enabled: false
    path: modules
  
  sections:
    hide: []
    show: []
  
  content: |-
    {{ .Header }}    
  
    <!-- markdownlint-disable MD033 -->
    {{ .Requirements }}
  
    {{ .Providers }}
  
    {{ .Resources }}
  
    <!-- markdownlint-disable MD013 -->
    {{ .Inputs }}
  
    {{ .Outputs }}
  
    {{ .Modules }}
  
    {{ .Footer }}
  
  output:
    file: README.md
    mode: replace
    template: |-
      <!-- BEGIN_TF_DOCS -->
      {{ .Content }}
      <!-- END_TF_DOCS -->      
  output-values:
    enabled: false
    from: ""
  
  sort:
    enabled: true
    by: required
  
  settings:
    anchor: true
    color: true
    default: true
    description: false
    escape: true
    hide-empty: false
    html: true
    indent: 2
    lockfile: true
    read-comments: true
    required: true
    sensitive: true
    type: true

TFNFR20 - Non-Nullable Defaults for collection values

ID: TFNFR20 - Category: Code Style - Non-Nullable Defaults for collection values

TFNFR21 - Discourage Nullability by Default

ID: TFNFR21 - Category: Code Style - Discourage Nullability by Default

nullable = true MUST be avoided.

TFNFR22 - Avoid sensitive = false

ID: TFNFR22 - Category: Code Style - Avoid sensitive = false

sensitive = false MUST be avoided.

TFNFR23 - Sensitive Default Value Conditions

ID: TFNFR23 - Category: Code Style - Sensitive Default Value Conditions

A default value MUST NOT be set for a sensitive input - e.g., a default password.

TFNFR24 - Handling Deprecated Variables

ID: TFNFR24 - Category: Code Style - Handling Deprecated Variables

Deprecated variable MUST be annotated as DEPRECATED at the beginning of the description, at the same time the replacement’s name SHOULD be declared. E.g.,

variable "enable_network_security_group" {
  type        = string
  default     = null
  description = "DEPRECATED, use `network_security_group_enabled` instead; Whether to generate a network security group and assign it to the subnet. Changing this forces a new resource to be created."
}

A cleanup of deprecated_variables.tf SHOULD be performed during a major version release.

TFNFR25 - Verified Modules Requirements

ID: TFNFR25 - Category: Code Style - Verified Modules Requirements

The terraform.tf file MUST only contain one terraform block.

The first line of the terraform block MUST define a required_version property for the Terraform CLI.

The required_version property MUST include a constraint on the minimum version of the Terraform CLI. Previous releases of the Terraform CLI can have unexpected behavior.

The required_version property constraint SHOULD use the ~> #.# or the >= #.#.#, < #.#.# format.

Note: You can read more about Terraform version constraints in the documentation.

Example terraform.tf file:

terraform {
  required_version = "~> 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.11"
    }
  }
}

TFNFR26 - Providers in required_providers

ID: TFNFR26 - Category: Code Style - Providers in required_providers

The terraform block in terraform.tf MUST contain the required_providers block.

Each provider used directly in the module MUST be specified with the source and version properties. Providers in the required_providers block SHOULD be sorted in alphabetical order.

Do not add providers to the required_providers block that are not directly required by this module. If submodules are used then each submodule SHOULD have its own versions.tf file.

The source property MUST be in the format of namespace/name. If this is not explicitly specified, it can cause failure.

The version property MUST include a constraint on the minimum version of the provider. Older provider versions may not work as expected.

The version property constraint SHOULD use the ~> #.# or the >= #.#.#, < #.#.# format.

Note: You can read more about Terraform version constraints in the documentation.

Good examples:

terraform {
  required_version = "~> 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
  }
}

terraform {
  required_version = ">= 1.6.6, < 2.0.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11.1, < 4.0.0"
    }
  }
}

terraform {
  required_version = ">= 1.6, < 2.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11, < 4.0"
    }
  }
}

Acceptable example (but not recommended):

terraform {
  required_version = "1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "3.11"
    }
  }
}

Bad example:

terraform {
  required_version = ">= 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.11"
    }
  }
}

TFNFR27 - Provider Declarations in Modules

ID: TFNFR27 - Category: Code Style - Provider Declarations in Modules

Good examples:

In verified module:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
      configuration_aliases = [ azurerm.alternate ]
    }
  }
}

In the root module where we call this verified module:

provider "azurerm" {
  features {}
}

provider "azurerm" {
  alias = "alternate"
  features {}
}

module "foo" {
  source = "xxx"
  providers = {
    azurerm = azurerm
    azurerm.alternate = azurerm.alternate
  }
}

Bad example:

In verified module:

provider "azurerm" {
  # Configuration options
  features {}
}

TFNFR29 - Sensitive Data Outputs

ID: TFNFR29 - Category: Code Style - Sensitive Data Outputs

An output block that contains confidential data MUST be declared with sensitive = true.

TFNFR3 - GitHub Repo Branch Protection

ID: TFNFR3 - Category: Contribution/Support - GitHub Repo Branch Protection

Module owners MUST set a branch protection policy on their GitHub Repositories for AVM modules against their default branch, typically main, to do the following:

Requires a Pull Request before merging
Require approval of the most recent reviewable push
Dismiss stale pull request approvals when new commits are pushed
Require linear history
Prevents force pushes
Not allow deletions
Require CODEOWNERS review
Do not allow bypassing the above settings
Above settings MUST also be enforced to administrators

Tip

If you use the template repository as mentioned in the contribution guide, the above will automatically be set.

TFNFR30 - Handling Deprecated Outputs

ID: TFNFR30 - Category: Code Style - Handling Deprecated Outputs

A cleanup SHOULD be performed to deprecated_outputs.tf and other logics related to compatibility during a major version upgrade.

TFNFR31 - locals.tf for Locals Only

ID: TFNFR31 - Category: Code Style - locals.tf for Locals Only

In locals.tf, file we could declare multiple locals blocks, but only locals blocks are allowed.

You MAY declare locals blocks next to a resource block or data block for some advanced scenarios, like making a fake module to execute some light-weight tests aimed at the expressions.

TFNFR32 - Alphabetical Local Arrangement

ID: TFNFR32 - Category: Code Style - Alphabetical Local Arrangement

Expressions in locals block MUST be arranged alphabetically.

Good examples:

locals {
  name = coalesce(var.name, "name")
  tags = merge(var.tags, {
    env = "prod"
  })
}

locals {
  tags = merge(var.tags, {
    env = "prod"
  })
}

locals {
  name = coalesce(var.name, "name")
}

TFNFR33 - Precise Local Types

ID: TFNFR33 - Category: Code Style - Precise Local Types

Precise local types SHOULD be used.

Good example:

{
  name = "John"
  age  = 52
}

Bad example:

{
  name = "John"
  age  = "52" # age should be number
}

TFNFR34 - Using Feature Toggles

ID: TFNFR34 - Category: Code Style - Using Feature Toggles

A toggle variable MUST be used to allow users to avoid the creation of a new resource block by default if it is added in a minor or patch version.

E.g., our previous release was v1.2.1 and next release would be v1.3.0, now we’d like to submit a pull request which contains such new resource:

resource "azurerm_route_table" "this" {
  location            = local.location
  name                = coalesce(var.new_route_table_name, "${var.subnet_name}-rt")
  resource_group_name = var.resource_group_name
}

A user who’s just upgraded the module’s version would be surprised to see a new resource to be created in a newly generated plan file.

A better approach is adding a feature toggle to be turned off by default:

variable "create_route_table" {
  type     = bool
  default  = false
  nullable = false
}

resource "azurerm_route_table" "this" {
  count               = var.create_route_table ? 1 : 0
  location            = local.location
  name                = coalesce(var.new_route_table_name, "${var.subnet_name}-rt")
  resource_group_name = var.resource_group_name
}

TFNFR35 - Reviewing Potential Breaking Changes

ID: TFNFR35 - Category: Code Style - Reviewing Potential Breaking Changes

Potential breaking(surprise) changes introduced by resource block

Adding a new resource without count or for_each for conditional creation, or creating by default
Adding a new argument assignment with a value other than the default value provided by the provider’s schema
Adding a new nested block without making it dynamic or omitting it by default
Renaming a resource block without one or more corresponding moved blocks
Change resource’s count to for_each, or vice versa

Terraform moved block could be your cure.

Potential breaking changes introduced by variable and output blocks

Deleting(Renaming) a variable
Changing type in a variable block
Changing the default value in a variable block
Changing variable’s nullable to false
Changing variable’s sensitive from false to true
Adding a new variable without default
Deleting an output
Changing an output’s value
Changing an output’s sensitive value

These changes do not necessarily trigger breaking changes, but they are very likely to, they MUST be reviewed with caution.

TFNFR36 - Setting prevent_deletion_if_contains_resources

ID: TFNFR36 - Category: Code Style - Setting prevent_deletion_if_contains_resources

TFNFR37 - Tool Usage by Module Owner

ID: TFNFR37 - Category: Code Style - Tool Usage by Module Owner

TFNFR4 - Lower snake_casing

ID: TFNFR4 - Category: Composition - Code Styling - lower snake_casing

Module owners MUST use lower snake_casing for naming the following:

Locals
Variables
Outputs
Resources (symbolic names)
Modules (symbolic names)

For example: snake_casing_example (every word in lowercase, with each word separated by an underscore _)

TFNFR5 - Test Tooling

ID: TFNFR5 - Category: Testing - Test Tooling

Module owners MUST use the below tooling for unit/linting/static/security analysis tests. These are also used in the AVM Compliance Tests.

Terraform
- terraform <validate/fmt/test>
terrafmt
Checkov
tflint (with azurerm ruleset)
Go
- Some tests are provided as part of the AVM Compliance Tests, but you are free to also use Go for your own tests.

TFNFR6 - Resource & Data Order

ID: TFNFR6 - Category: Code Style - Resource & Data Order

For the definition of resources in the same file, the resources be depended on SHOULD come first, after them are the resources depending on others.

Resources that have dependencies SHOULD be defined close to each other.

TFNFR7 - Count & for_each Use

ID: TFNFR7 - Category: Code Style - count & for_each Use

We can use count and for_each to deploy multiple resources, but the improper use of count can lead to anti pattern.

You can use count to create some kind of resources under certain conditions, for example:

resource "azurerm_network_security_group" "this" {
  count               = local.create_new_security_group ? 1 : 0
  name                = coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
  resource_group_name = var.resource_group_name
  location            = local.location
  tags                = var.new_network_security_group_tags
}

The module’s owners MUST use map(xxx) or set(xxx) as resource’s for_each collection, the map’s key or set’s element MUST be static literals.

Good example:

resource "azurerm_subnet" "pair" {
  for_each             = var.subnet_map // `map(string)`, when user call this module, it could be: `{ "subnet0": "subnet0" }`, or `{ "subnet0": azurerm_subnet.subnet0.name }`
  name                 = "${each.value}"-pair
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.1.0/24"]
}

Bad example:

resource "azurerm_subnet" "pair" {
  for_each             = var.subnet_name_set // `set(string)`, when user use `toset([azurerm_subnet.subnet0.name])`, it would cause an error.
  name                 = "${each.value}"-pair
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.1.0/24"]
}

TFNFR8 - Resource & Data Block Orders

ID: TFNFR8 - Category: Code Style - Resource & Data Block Orders

There are 3 types of assignment statements in a resource or data block: argument, meta-argument and nested block. The argument assignment statement is a parameter followed by =:

location = azurerm_resource_group.example.location

or:

tags = {
  environment = "Production"
}

Nested block is a assignment statement of parameter followed by {} block:

subnet {
  name           = "subnet1"
  address_prefix = "10.0.1.0/24"
}

Meta-arguments are assignment statements can be declared by all resource or data blocks. They are:

count
depends_on
for_each
lifecycle
provider

The order of declarations within resource or data blocks is:

All the meta-arguments SHOULD be declared on the top of resource or data blocks in the following order:

provider
count
for_each

Then followed by:

required arguments
optional arguments
required nested blocks
optional nested blocks

All ranked in alphabetical order.

These meta-arguments SHOULD be declared at the bottom of a resource block with the following order:

depends_on
lifecycle

The parameters of lifecycle block SHOULD show up in the following order:

create_before_destroy
ignore_changes
prevent_destroy

parameters under depends_on and ignore_changes are ranked in alphabetical order.

Meta-arguments, arguments and nested blocked are separated by blank lines.

dynamic nested blocks are ranked by the name comes after dynamic, for example:

  dynamic "linux_profile" {
    for_each = var.admin_username == null ? [] : ["linux_profile"]

    content {
      admin_username = var.admin_username

      ssh_key {
        key_data = replace(coalesce(var.public_ssh_key, tls_private_key.ssh[0].public_key_openssh), "\n", "")
      }
    }
  }

This dynamic block will be ranked as a block named linux_profile.

Code within a nested block will also be ranked following the rules above.

PS: You can use avmfix tool to reformat your code automatically.

TFNFR9 - Module Block Order

ID: TFNFR9 - Category: Code Style - Module Block Order

The meta-arguments below SHOULD be declared on the top of a module block with the following order:

source
version
count
for_each

blank lines will be used to separate them.

After them will be required arguments, optional arguments, all ranked in alphabetical order.

These meta-arguments below SHOULD be declared on the bottom of a resource block in the following order:

depends_on
providers

Arguments and meta-arguments SHOULD be separated by blank lines.

Contributing

Summary

This section lists all contribution guidance available to module owners and contributors.

Important

If you cannot find guidance for what you need, please let us know via GitHub Issues 👍

Bicep Contribution Guide

Important

While this page describes and summarizes important aspects of contributing to AVM, it may not reference All of the shared and language specific requirements.

Therefore, this contribution guide MUST be used in conjunction with the Bicep specifications. ALL AVM modules (Resource and Pattern modules) MUST meet the respective requirements described in these specifications!

Summary

This section lists AVM’s Bicep-specific contribution guidance.

Bicep Composition

Important

While this page describes and summarizes important aspects of the composition of AVM modules, it may not reference All of the shared and language specific requirements.

Therefore, this guide MUST be used in conjunction with the Bicep specifications. ALL AVM modules (Resource and Pattern modules) MUST meet the respective requirements described in these specifications!

Important

Before jumping on implementing your contribution, please review the AVM Module specifications, in particular the Bicep specification page, to make sure your contribution complies with the AVM module’s design and principles.

Directory and File Structure

Each Bicep AVM module that lives within the Azure/bicep-registry-modules (BRM) repository in the avm directory will have the following directories and files:

tests/ - (for unit tests and additional E2E/integration if required - e.g. Pester etc.)
- e2e/ - (all examples must deploy successfully - these will be used to automatically generate the examples in the README.md for the module)
modules/ - (for sub-modules only if used and NOT children of the primary resource. e.g. RBAC role assignments)
/... - (Module files that live in the root of module directory)
- main.bicep (AVM Module main .bicep file and entry point/orchestration module)
- main.json (auto generated and what is published to the MCR via BRM)
- version.json (BRM requirement)
- README.md (auto generated AVM Module documentation)

Directory and File Structure Example

/ Root of Azure/bicep-registry-modules
│
├───avm
│   ├───ptn
│   │   └───apptiervmss
│   │       │   main.bicep
│   │       │   main.json
│   │       │   README.md
│   │       │   version.json
│   │       │
│   │       ├───modules
│   │       └───tests
│   │           ├───unit (optional)
│   │           └───e2e
│   │               ├───defaults
│   │               ├───waf-aligned
│   │               └───max
│   │
│   └───res
│       └───compute
│           └───virtual-machine
│               │   main.bicep
│               │   main.json
│               │   README.md
│               │   version.json
│               │
│               ├───modules
│               └───tests
│                   ├───unit (optional)
│                   └───e2e
│                       ├───defaults
│                       ├───waf-aligned
│                       └───max
├───other repo dirs...
└───other repo files...

For a new module (res or ptn), the files can be created automatically, once the parent folder exists. This example shows how to create a res module res/compute/virtual-machine.

Set-Location -Path ".\avm\"
New-Item -ItemType Directory -Path ".\res\compute\virtual-machine"
Set-AVMModule -ModuleFolderPath .\res\compute\virtual-machine

Code Styling

This section points to conventions to be followed when developing a Bicep template.

Casing

Use camelCasing as per BCPNFR8.

Input Parameters and Variables

Make sure to review all specifications of Category: Inputs/Outputs within the Bicep specification pages.

Tip

See examples in specifications SNFR14 and BCPNFR1.

Resources

Resources are primarily leveraged by resource modules to declare the primary resource of the main resource type deployed by the AVM module.

Make sure to review all specifications covering resource properties and usage.

Tip

See examples in specifications SFR1 and RMFR1.

Modules

Modules enable you to reuse code from a Bicep file in other Bicep files. As such, for resource modules they’re normally leveraged for deploying child resources (e.g., file services in a storage account), cross referenced resources (e.g., network interface in a virtual machine) or extension resources (e.g., role assignments in a key vault). Pattern modules, normally reuse resource modules combined together.

Make sure to review all specifications covering module properties and usage.

Tip

See examples in specifications BCPFR1 for resource modules and PMNFR2 for pattern modules.

Outputs

Make sure to review all specifications of Category: Inputs/Outputs within the Bicep specific pages.

Tip

See examples in specification RMFR7.

Interfaces

Note

This section is only relevant for contributions to resource modules.

To meet RMFR4 and RMFR5 AVM resource modules must leverage consistent interfaces for all the optional features/extension resources supported by the AVM module primary resource.

Please refer to the Bicep Interfaces page.
If the primary resource of the AVM resource module you are developing supports any of the listed features/extension resources, please follow the corresponding provided Bicep schema to develop them.

Deprecation

Breaking changes are sometimes not avoidable. The impact should be kept as low as possible. A recommendation is to deprecate parameters, instead of completely removing them for a couple of versions. The Semantic Versioning sections offers information about versioning AVM modules.

In case you need to deprecate an input parameter, this sample shows you how this can be achieved.

Note

Since all modules are versioned, nothing will change for existing deployments, as the parameter usage does not change for any existing versions.

Example-Scenario

An AVM module is modified, and the parameters will change, which breaks backward compatibility.

parameters are changing to a custom type
the parameter structure is changing
backward compatibility will be maintained

Existing input parameters used to be defined as follows (reducing the examples to the minimum):

// main.bicep:
param item object?

// main.test.bicep:
name: 'name'
item:
  {
    variant: 'Large'
    osType: 'Windows'
  }

Testing

Before you begin to modify anything, it is recommended to create a new test case (e.g. deprecated), in addition to the already existing tests, to make sure that the changes are not breaking backward compatibility until you decide to finally remove the deprecated parameters (see BCPRMNFR1 - Category: Testing - Expected Test Directories for more details about the requirements).

module testDeployment '../../../main.bicep' = [
  for iteration in ['init', 'idem']: {
    scope: resourceGroup
    name: '${uniqueString(deployment().name, resourceLocation)}-test-${serviceShort}-${iteration}'
    params: {
      name: '${namePrefix}${serviceShort}001'
      item: {
        variant: 'Large'
        osType: 'Linux'
      }
    }
  }
]

The test should include all previously used parameters to make sure they are covered before any changes to the new parameter layout are done.

Code Changes

The new parameter structure requires a change to the used parameters and moves them to a different location and looks like:

// main.bicep:
param item itemType?

type itemtype: {
  name: string // the name parameter did not change

  properties ={
    osType: 'Linux' | 'Windows'? // the new place for the osType

    variant: {
      size: string? // the new place for the variant size
    }?
  }

  // keep these for backward compatibility in the new type
  @description('Optional. Note: This is a deprecated property, please use the corresponding `properties.osType` instead.')
  osType: string? // the old parameter location

  @description('Optional. Note: This is a deprecated property, please use the corresponding `properties.variant.size` instead.')
  variant: string? // the old parameter location
}

The original parameter item is of type object and does not give the user any clue of what the syntax is and what is expected to be added to it. The tests could bring light into the darkness, but this is not ideal. In order to retain backward compatibility, the previously used parameters need to be added to the new type, as they would be invalid otherwise. Now that the new type is in place, some logic needs to be implemented to make sure the module can handle the different sources of data (new and old parameters).

resource <modulename> 'Microsoft.xy/yz@2024-01-01' = {
  name: name
  properties: {
    osType: item.?properties.?osType ?? item.?osType ?? 'Linux' // add a default here, if needed
    variant: {
      size: item.?properties.?variant.?size ?? item.?variant
    }
  }
}

By choosing this order for the Coalesce operator, the new format takes precedence over the old syntax. Also note the safe-dereference ensures that no null reference exception will occure if the property has optional parameters.

The tests can now be changed to adapt the new parameter structure for the new version of the module. They will not cover the old parameter structure anymore.

module testDeployment '../../../main.bicep' = [
  for iteration in ['init', 'idem']: {
    scope: resourceGroup
    name: '${uniqueString(deployment().name, resourceLocation)}-test-${serviceShort}-${iteration}'
    params: {
      name: '${namePrefix}${serviceShort}001'
      location: resourceLocation
      item:{
        osType: 'Linux'
        variant: {
          size: 'Large'
        }
      }
    }
  }
]

Summary

Changes to modules (resource or pattern) can bei implemented in two ways.

Implement changes with backward compatibility
In this scenario, you need to make sure that the code does not break backward compatibility by:
- adding new parameters
- marking other parameters as deprecated
- create a test case for the old usage syntax
- increase the minor version number of the module (0.x)
Introduce breaking changes
The easier way to introduce a new major version requires fewer steps:
- adding new parameters
- create a test case for the usage
- increase the major version number of the module (x.0.0)

Note

Be aware that currently no module has been released as 1.0.0 (or beyond), which lets you implement breaking changes without increasing the major version.

Bicep Contribution Flow

High-level contribution flow


---
config:
  nodeSpacing: 20
  rankSpacing: 20
  diagramPadding: 50
  padding: 5
  flowchart:
    wrappingWidth: 300
    padding: 5
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---

flowchart TD
  A("1 - Fork the module source repository")
    click A "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#1-fork-the-module-source-repository"
  B(2 - Configure a deployment identity in Azure)
    click B "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#2-configure-a-deployment-identity-in-azure"
  C("3 - Configure CI environment for module tests")
    click C "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#3-configure-your-ci-environment"
  D("4 - Implementing your contribution<br>(Refer to Gitflow Diagram below)")
    click D "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#4-implement-your-contribution"
  E(5 - Workflow test completed successfully?)
    click E "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#5-createupdate-and-run-tests"
  F(6 - Create a pull request to the upstream repository)
    click F "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#6-create-a-pull-request-to-the-public-bicep-registry"
  A --> B
  B --> C
  C --> D
  D --> E
  E -->|yes|F
  E -->|no|D

GitFlow for contributors

The GitFlow process outlined here introduces a central anchor branch. This branch should be treated as if it were a protected branch. It serves to synchronize the forked repository with the original upstream repository. The use of the anchor branch is designed to give contributors the flexibility to work on several modules simultaneous.

---

config:
  logLevel: debug
  gitGraph:
    rotateCommitLabel: false
---

gitGraph LR:
  commit id:"Fork Repo"
  branch anchor
  checkout anchor
  commit id:"Sync Upstream/main" type: HIGHLIGHT
  branch avm-type-provider-resource-workflow
  checkout avm-type-provider-resource-workflow
  commit id:"Add Workflow File for Resource/Pattern"
  branch avm-type-provider-resource
  checkout main
  merge avm-type-provider-resource-workflow id: "merge workflow for GitHub Actions Testing" type: HIGHLIGHT
  checkout avm-type-provider-resource
  commit id:"Init"
  commit id:"Patch 1"
  commit id:"Patch 2"
  checkout main
  merge avm-type-provider-resource

Tip

When implementing the GitFlow process as described, it is advisable to configure the local clone with a remote for the upstream repository. This will enable the Git CLI and local IDE to merge changes directly from the upstream repository. Using GitHub Desktop, this is configured automatically when cloning the forked repository via the application.

PowerShell Helper Script To Setup Fork & CI Test Environment

Now defaults to OIDC setup

The PowerShell Helper Script has recently added support for the OIDC setup and configuration as documented in detail on this page. This is now the default for the script.

The easiest way to get yourself set back up, is to delete your fork repository, including the local clone of it that you have and start over with the script. This will ensure you have the correct setup for the OIDC authentication method for the AVM CI.

Important

To simplify the setup of the fork, clone and configuration of the required GitHub Environments, Secrets, User-Assigned Managed Identity (UAMI), Federated Credentials and RBAC assignments in your Azure environment for the CI framework to function correctly in your fork, we have created a PowerShell script that you can use to do steps 1, 2 & 3 below.

The script performs the following steps:

Forks the Azure/bicep-registry-modules to your GitHub Account.
Clones the repo locally to your machine, based on the location you specify in the parameter: -GitHubRepositoryPathForCloneOfForkedRepository.
Prompts you and takes you directly to the place where you can enable GitHub Actions Workflows on your forked repo.
Disables all AVM module workflows, as per Enable or Disable Workflows.
Creates an User-Assigned Managed Identity (UAMI) and federated credentials for OIDC with your forked GitHub repo and grants it the RBAC roles of Owner at Management Group level, if specified in the -GitHubSecret_ARM_MGMTGROUP_ID parameter, and at Azure Subscription level if you provide it via the -GitHubSecret_ARM_SUBSCRIPTION_ID parameter.
Creates the required GitHub Environments & required Secrets in your forked repo as per step 3, based on the input provided in parameters and the values from resources the script creates and configures for OIDC. Also set the workflow permissions to Read and write permissions as per step 3.3.

Pre-requisites

You must have the Azure PowerShell Modules installed and you need to be logged with the context set to the desired Tenant. You must have permissions to create an SPN and grant RBAC over the specified Subscription and Management Group, if provided.
You must have the GitHub CLI installed and need to be authenticated with the GitHub user account you wish to use to fork, clone and work with on AVM.

➕ New-AVMBicepBRMForkSetup.ps1 - PowerShell Helper Script

The New-AVMBicepBRMForkSetup.ps1 can be downloaded from here.

Once downloaded, you can run the script by running the below - Please change all the parameter values in the below script usage example to your own values (see the parameter documentation in the script itself)!:

.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "<pathToCreateForkedRepoIn>" -GitHubSecret_ARM_MGMTGROUP_ID "<managementGroupId>" -GitHubSecret_ARM_SUBSCRIPTION_ID "<subscriptionId>" -GitHubSecret_ARM_TENANT_ID "<tenantId>" -GitHubSecret_TOKEN_NAMEPREFIX "<unique3to5AlphanumericStringForAVMDeploymentNames>" -UAMIRsgLocation "<Azure Region/Location of your choice such as 'uksouth'>"

For more examples, see the below script’s parameters section.

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "", Justification = "Coloured output required in this script")]

#Requires -PSEdition Core
#Requires -Modules @{ ModuleName="Az.Accounts"; ModuleVersion="2.19.0" }
#Requires -Modules @{ ModuleName="Az.Resources"; ModuleVersion="6.16.2" }

<#
.SYNOPSIS
This function creates and sets up everything a contributor to the AVM Bicep project should need to get started with their contribution to a AVM Bicep Module.

.DESCRIPTION
This function creates and sets up everything a contributor to the AVM Bicep project should need to get started with their contribution to a AVM Bicep Module. This includes:

- Forking and cloning the `Azure/bicep-registry-modules` repository
- Creating a new SPN and granting it the necessary permissions for the CI tests and configuring the forked repositories secrets, as per: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#2-configure-a-deployment-identity-in-azure
- Enabling GitHub Actions on the forked repository
- Disabling all the module workflows by default, as per: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows/

Effectively simplifying this process to a single command, https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/

.PARAMETER GitHubRepositoryPathForCloneOfForkedRepository
Mandatory. The path to the GitHub repository to fork and clone. Directory will be created if does not already exist. Can use either relative paths or full literal paths.

.PARAMETER GitHubSecret_ARM_MGMTGROUP_ID
Optional. The group ID of the management group to test-deploy modules in. Is needed for resources that are deployed to the management group scope. If not provided CI tests on Management Group scoped modules will not work and you will need to manually configure the RBAC role assignments for the SPN and associated repository secret later.

.PARAMETER GitHubSecret_ARM_SUBSCRIPTION_ID
Mandatory. The ID of the subscription to test-deploy modules in. Is needed for resources that are deployed to the subscription scope.

.PARAMETER GitHubSecret_ARM_TENANT_ID
Mandatory. The tenant ID of the Azure Active Directory tenant to test-deploy modules in. Is needed for resources that are deployed to the tenant scope.

.PARAMETER GitHubSecret_TOKEN_NAMEPREFIX
Mandatory. Required. A short (3-5 character length), unique string that should be included in any deployment to Azure. Usually, AVM Bicep test cases require this value to ensure no two contributors deploy resources with the same name - which is especially important for resources that require a globally unique name (e.g., Key Vault). These characters will be used as part of each resource’s name during deployment.

.PARAMETER SPNName
Optional. The name of the SPN (Service Principal) to create. If not provided, a default name of `spn-avm-bicep-brm-fork-ci-<GitHub Organization>` will be used.

.PARAMETER UAMIName
Optional. The name of the UAMI (User Assigned Managed Identity) to create. If not provided, a default name of `id-avm-bicep-brm-fork-ci-<GitHub Organization>` will be used.

.PARAMETER UAMIRsgName
Optional. The name of the Resource Group to create for the UAMI (User Assigned Managed Identity) to create. If not provided, a default name of `rsg-avm-bicep-brm-fork-ci-<GitHub Organization>-oidc` will be used.

.PARAMETER UAMIRsgLocation
Optional. The location of the Resource Group to create for the UAMI (User Assigned Managed Identity) to create. Also UAMI will be created in this location. This is required for OIDC deployments.

.PARAMETER UseOIDC
Optional. Default is `$true`. If set to `$true`, the script will use the OIDC (OpenID Connect) authentication method for the SPN instead of secrets as per https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#31-set-up-secrets. If set to `$false`, the script will use the Client Secret authentication method for the SPN and not OIDC.

.EXAMPLE
.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "D:\GitRepos\" -GitHubSecret_ARM_MGMTGROUP_ID "alz" -GitHubSecret_ARM_SUBSCRIPTION_ID "1b60f82b-d28e-4640-8cfa-e02d2ddb421a" -GitHubSecret_ARM_TENANT_ID "c3df6353-a410-40a1-b962-e91e45e14e4b" -GitHubSecret_TOKEN_NAMEPREFIX "ex123" -UAMIRsgLocation "uksouth"

Example Subscription & Management Group scoped deployments enabled via OIDC with default generated UAMI Resource Group name of `rsg-avm-bicep-brm-fork-ci-<GitHub Organization>-oidc` and UAMI name of `id-avm-bicep-brm-fork-ci-<GitHub Organization>`.

.EXAMPLE
.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "D:\GitRepos\" -GitHubSecret_ARM_MGMTGROUP_ID "alz" -GitHubSecret_ARM_SUBSCRIPTION_ID "1b60f82b-d28e-4640-8cfa-e02d2ddb421a" -GitHubSecret_ARM_TENANT_ID "c3df6353-a410-40a1-b962-e91e45e14e4b" -GitHubSecret_TOKEN_NAMEPREFIX "ex123" -UAMIRsgLocation "uksouth" -UAMIName "my-uami-name" -UAMIRsgName "my-uami-rsg-name"

Example with provided UAMI Name & UAMI Resource Group Name.

.EXAMPLE
.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "D:\GitRepos\" -GitHubSecret_ARM_SUBSCRIPTION_ID "1b60f82b-d28e-4640-8cfa-e02d2ddb421a" -GitHubSecret_ARM_TENANT_ID "c3df6353-a410-40a1-b962-e91e45e14e4b" -GitHubSecret_TOKEN_NAMEPREFIX "ex123" -UseOIDC $false

DEPRECATED - USE OIDC INSTEAD.
Example Subscription scoped deployments enabled only with default generated SPN name of `spn-avm-bicep-brm-fork-ci-<GitHub Organization>`.

.EXAMPLE
.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "D:\GitRepos\" -GitHubSecret_ARM_MGMTGROUP_ID "alz" -GitHubSecret_ARM_SUBSCRIPTION_ID "1b60f82b-d28e-4640-8cfa-e02d2ddb421a" -GitHubSecret_ARM_TENANT_ID "c3df6353-a410-40a1-b962-e91e45e14e4b" -GitHubSecret_TOKEN_NAMEPREFIX "ex123" -SPNName "my-spn-name" -UseOIDC $false

DEPRECATED - USE OIDC INSTEAD.
Example with provided SPN name.

#>

[CmdletBinding(SupportsShouldProcess = $false)]
param (
  [Parameter(Mandatory = $true)]
  [string] $GitHubRepositoryPathForCloneOfForkedRepository,

  [Parameter(Mandatory = $false)]
  [string] $GitHubSecret_ARM_MGMTGROUP_ID,

  [Parameter(Mandatory = $true)]
  [string] $GitHubSecret_ARM_SUBSCRIPTION_ID,

  [Parameter(Mandatory = $true)]
  [string] $GitHubSecret_ARM_TENANT_ID,

  [Parameter(Mandatory = $true)]
  [string] $GitHubSecret_TOKEN_NAMEPREFIX,

  [Parameter(Mandatory = $false)]
  [string] $SPNName,

  [Parameter(Mandatory = $false)]
  [string] $UAMIName,

  [Parameter(Mandatory = $false)]
  [string] $UAMIRsgName = "rsg-avm-bicep-brm-fork-ci-oidc",

  [Parameter(Mandatory = $false)]
  [string] $UAMIRsgLocation,

  [Parameter(Mandatory = $false)]
  [bool] $UseOIDC = $true
)

# Check if the GitHub CLI is installed
$GitHubCliInstalled = Get-Command gh -ErrorAction SilentlyContinue
if ($null -eq $GitHubCliInstalled) {
  throw 'The GitHub CLI is not installed. Please install the GitHub CLI and try again. Install link for GitHub CLI: https://github.com/cli/cli#installation'
}
Write-Host 'The GitHub CLI is installed...' -ForegroundColor Green

# Check if GitHub CLI is authenticated
$GitHubCliAuthenticated = gh auth status
if ($LASTEXITCODE -ne 0) {
  Write-Host $GitHubCliAuthenticated -ForegroundColor Red
  throw "Not authenticated to GitHub. Please authenticate to GitHub using the GitHub CLI command of 'gh auth login', and try again."
}
Write-Host 'Authenticated to GitHub with following details...' -ForegroundColor Cyan
Write-Host ''
gh auth status
Write-Host ''

# Ask the user to confirm if it's the correct GitHub account
do {
  Write-Host "Is the above GitHub account correct to coninue with the fork setup of the 'Azure/bicep-registry-modules' repository? Please enter 'y' or 'n'." -ForegroundColor Yellow
  $userInput = Read-Host
  $userInput = $userInput.ToLower()

  switch ($userInput) {
    'y' {
      Write-Host ''
      Write-Host 'User Confirmed. Proceeding with the GitHub account listed above...' -ForegroundColor Green
      Write-Host ''
      break
    }
    'n' {
      Write-Host ''
      throw "User stated incorrect GitHub account. Please switch to the correct GitHub account. You can do this in the GitHub CLI (gh) by logging out by running 'gh auth logout' and then logging back in with 'gh auth login'"
    }
    default {
      Write-Host ''
      Write-Host "Invalid input. Please enter 'y' or 'n'." -ForegroundColor Red
      Write-Host ''
    }
  }
} while ($userInput -ne 'y' -and $userInput -ne 'n')

# Fork and clone repository locally
Write-Host "Changing to directory $GitHubRepositoryPathForCloneOfForkedRepository ..." -ForegroundColor Magenta

if (-not (Test-Path -Path $GitHubRepositoryPathForCloneOfForkedRepository)) {
  Write-Host "Directory does not exist. Creating directory $GitHubRepositoryPathForCloneOfForkedRepository ..." -ForegroundColor Yellow
  New-Item -Path $GitHubRepositoryPathForCloneOfForkedRepository -ItemType Directory -ErrorAction Stop
  Write-Host ''
}
Set-Location -Path $GitHubRepositoryPathForCloneOfForkedRepository -ErrorAction stop
$CreatedDirectoryLocation = Get-Location
Write-Host "Forking and cloning 'Azure/bicep-registry-modules' repository..." -ForegroundColor Magenta

gh repo fork 'Azure/bicep-registry-modules' --default-branch-only --clone=true
if ($LASTEXITCODE -ne 0) {
  throw "Failed to fork and clone the 'Azure/bicep-registry-modules' repository. Please check the error message above, resolve any issues, and try again."
}

$ClonedRepoDirectoryLocation = Join-Path $CreatedDirectoryLocation 'bicep-registry-modules'
Write-Host ''
Write-Host "Fork of 'Azure/bicep-registry-modules' created successfully directory in $CreatedDirectoryLocation ..." -ForegroundColor Green
Write-Host ''
Write-Host "Changing into cloned repository directory $ClonedRepoDirectoryLocation ..." -ForegroundColor Magenta
Set-Location $ClonedRepoDirectoryLocation -ErrorAction stop

# Check is user is logged in to Azure
$UserLoggedIntoAzure = Get-AzContext -ErrorAction SilentlyContinue
if ($null -eq $UserLoggedIntoAzure) {
  throw 'You are not logged into Azure. Please log into Azure using the Azure PowerShell module using the command of `Connect-AzAccount` to the correct tenant and try again.'
}
$UserLoggedIntoAzureJson = $UserLoggedIntoAzure | ConvertTo-Json -Depth 10 | ConvertFrom-Json
Write-Host "You are logged into Azure as '$($UserLoggedIntoAzureJson.Account.Id)' ..." -ForegroundColor Green

# Check user has access to desired subscription
$UserCanAccessSubscription = Get-AzSubscription -SubscriptionId $GitHubSecret_ARM_SUBSCRIPTION_ID -ErrorAction SilentlyContinue
if ($null -eq $UserCanAccessSubscription) {
  throw "You do not have access to the subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)'. Please ensure you have access to the subscription and try again."
}
Write-Host "You have access to the subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)' ..." -ForegroundColor Green
Write-Host ''

# Get GitHub Login/Org Name
$GitHubUserRaw = gh api user
$GitHubUserConvertedToJson = $GitHubUserRaw | ConvertFrom-Json -Depth 10
$GitHubOrgName = $GitHubUserConvertedToJson.login
$GitHubOrgAndRepoNameCombined = "$($GitHubOrgName)/bicep-registry-modules"

# Create SPN if not using OIDC
if ($UseOIDC -eq $false) {
  if ($SPNName -eq '') {
    Write-Host "No value provided for the SPN Name. Defaulting to 'spn-avm-bicep-brm-fork-ci-<GitHub Organization>' ..." -ForegroundColor Yellow

    $SPNName = "spn-avm-bicep-brm-fork-ci-$($GitHubOrgName)"
  }
  $newSpn = New-AzADServicePrincipal -DisplayName $SPNName -Description "Service Principal Name (SPN) for the AVM Bicep CI Tests in the $($GitHubOrgName) fork. See: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#2-configure-a-deployment-identity-in-azure" -ErrorAction Stop
  Write-Host "New SPN created with a Display Name of '$($newSpn.DisplayName)' and an Object ID of '$($newSpn.Id)'." -ForegroundColor Green
  Write-Host ''

  # Create RBAC Role Assignments for SPN
  Write-Host 'Starting 120 second sleep to allow the SPN to be created and available for RBAC Role Assignments (eventual consistency) ...' -ForegroundColor Yellow
  Start-Sleep -Seconds 120

  Write-Host "Creating RBAC Role Assignments of 'Owner' for the Service Principal Name (SPN) '$($newSpn.DisplayName)' on the Subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)' ..." -ForegroundColor Magenta
  New-AzRoleAssignment -ApplicationId $newSpn.AppId -RoleDefinitionName 'Owner' -Scope "/subscriptions/$($GitHubSecret_ARM_SUBSCRIPTION_ID)" -ErrorAction Stop
  Write-Host "RBAC Role Assignments of 'Owner' for the Service Principal Name (SPN) '$($newSpn.DisplayName)' created successfully on the Subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)'." -ForegroundColor Green
  Write-Host ''

  if ($GitHubSecret_ARM_MGMTGROUP_ID -eq '') {
    Write-Host "No Management Group ID provided as input parameter to '-GitHubSecret_ARM_MGMTGROUP_ID', skipping RBAC Role Assignments upon Management Groups" -ForegroundColor Yellow
    Write-Host ''
  }

  if ($GitHubSecret_ARM_MGMTGROUP_ID -ne '') {
    Write-Host "Creating RBAC Role Assignments of 'Owner' for the Service Principal Name (SPN) '$($newSpn.DisplayName)' on the Management Group with the ID of '$($GitHubSecret_ARM_MGMTGROUP_ID)' ..." -ForegroundColor Magenta
    New-AzRoleAssignment -ApplicationId $newSpn.AppId -RoleDefinitionName 'Owner' -Scope "/providers/Microsoft.Management/managementGroups/$($GitHubSecret_ARM_MGMTGROUP_ID)" -ErrorAction Stop
    Write-Host "RBAC Role Assignments of 'Owner' for the Service Principal Name (SPN) '$($newSpn.DisplayName)' created successfully on the Management Group with the ID of '$($GitHubSecret_ARM_MGMTGROUP_ID)'." -ForegroundColor Green
    Write-Host ''
  }
}

# Create UAMI if using OIDC
if ($UseOIDC) {
  if ($UAMIName -eq '') {
    Write-Host "No value provided for the UAMI Name. Defaulting to 'id-avm-bicep-brm-fork-ci-<GitHub Organization>' ..." -ForegroundColor Yellow

    $UAMIName = "id-avm-bicep-brm-fork-ci-$($GitHubOrgName)"
  }
  if ($UAMIRsgName -eq '') {
    Write-Host "No value provided for the UAMI Resource Group Name. Defaulting to 'rsg-avm-bicep-brm-fork-ci-<GitHub Organization>-oidc' ..." -ForegroundColor Yellow

    $UAMIRsgName = "rsg-avm-bicep-brm-fork-ci-$($GitHubOrgName)-oidc"
  }

  Write-Host "Selecting the subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)' to create Resource Group & UAMI in for OIDC ..." -ForegroundColor Magenta
  Select-AzSubscription -Subscription $GitHubSecret_ARM_SUBSCRIPTION_ID
  Write-Host ''

  if ($UAMIRsgLocation -eq '') {
    Write-Host "No value provided for the UAMI Location ..." -ForegroundColor Yellow
    $UAMIRsgLocation = Read-Host -Prompt "Please enter the location for the UAMI and the Resource Group to be created in for OIDC deployments. e.g. 'uksouth' or 'eastus', etc..."
    $UAMIRsgLocation = $UAMIRsgLocation.ToLower()

    $availableLocations = Get-AzLocation | Where-Object {$_.RegionType -eq 'Physical'} | Select-Object -ExpandProperty Location

    if ($availableLocations -notcontains $UAMIRsgLocation) {
      Write-Host "Invalid location provided. Please provide a valid location from the list below ..." -ForegroundColor Yellow
      Write-Host ''
      Write-Host "Available Locations: $($availableLocations -join ', ')" -ForegroundColor Yellow
      do {
        $UAMIRsgLocation = Read-Host -Prompt "Please enter the location for the UAMI and the Resource Group to be created in for OIDC deployments. e.g. 'uksouth' or 'eastus', etc..."
      } until (
        $availableLocations -icontains $UAMIRsgLocation
      )
    }
  }

  Write-Host "Creating Resource Group for UAMI with the name of '$($UAMIRsgName)' and location of '$($UAMIRsgLocation)'..." -ForegroundColor Magenta
  $newUAMIRsg = New-AzResourceGroup -Name $UAMIRsgName -Location $UAMIRsgLocation -ErrorAction Stop
  Write-Host "New Resource Group created with a Name of '$($newUAMIRsg.ResourceGroupName)' and a Location of '$($newUAMIRsg.Location)'." -ForegroundColor Green
  Write-Host ''

  Write-Host "Creating UAMI with the name of '$($UAMIName)' and location of '$($UAMIRsgLocation)' in the Resource Group with the name of '$($UAMIRsgName)..." -ForegroundColor Magenta
  $newUAMI = New-AzUserAssignedIdentity -ResourceGroupName $newUAMIRsg.ResourceGroupName -Name $UAMIName -Location $newUAMIRsg.Location -ErrorAction Stop
  Write-Host "New UAMI created with a Name of '$($newUAMI.Name)' and an Object ID of '$($newUAMI.PrincipalId)'." -ForegroundColor Green
  Write-Host ''

  # Create Federated Credentials for UAMI for OIDC
  Write-Host "Creating Federated Credentials for the User-Assigned Managed Identity Name (UAMI) for OIDC ... '$($newUAMI.Name)' for OIDC ..." -ForegroundColor Magenta
  New-AzFederatedIdentityCredentials -ResourceGroupName $newUAMIRsg.ResourceGroupName -IdentityName $newUAMI.Name -Name 'avm-gh-env-validation' -Issuer "https://token.actions.githubusercontent.com" -Subject "repo:$($GitHubOrgAndRepoNameCombined):environment:avm-validation" -ErrorAction Stop
  Write-Host ''

  # Create RBAC Role Assignments for UAMI
  Write-Host 'Starting 120 second sleep to allow the UAMI to be created and available for RBAC Role Assignments (eventual consistency) ...' -ForegroundColor Yellow
  Start-Sleep -Seconds 120

  Write-Host "Creating RBAC Role Assignments of 'Owner' for the User-Assigned Managed Identity Name (UAMI) '$($newUAMI.Name)' on the Subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)' ..." -ForegroundColor Magenta
  New-AzRoleAssignment -ObjectId $newUAMI.PrincipalId -RoleDefinitionName 'Owner' -Scope "/subscriptions/$($GitHubSecret_ARM_SUBSCRIPTION_ID)" -ErrorAction Stop
  Write-Host "RBAC Role Assignments of 'Owner' for the User-Assigned Managed Identity Name (UAMI) '$($newUAMI.Name)' created successfully on the Subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)'." -ForegroundColor Green
  Write-Host ''

  if ($GitHubSecret_ARM_MGMTGROUP_ID -eq '') {
    Write-Host "No Management Group ID provided as input parameter to '-GitHubSecret_ARM_MGMTGROUP_ID', skipping RBAC Role Assignments upon Management Groups" -ForegroundColor Yellow
    Write-Host ''
  }

  if ($GitHubSecret_ARM_MGMTGROUP_ID -ne '') {
    Write-Host "Creating RBAC Role Assignments of 'Owner' for the User-Assigned Managed Identity Name (UAMI) '$($newSpn.DisplayName)' on the Management Group with the ID of '$($GitHubSecret_ARM_MGMTGROUP_ID)' ..." -ForegroundColor Magenta
    New-AzRoleAssignment -ObjectId $newUAMI.PrincipalId -RoleDefinitionName 'Owner' -Scope "/providers/Microsoft.Management/managementGroups/$($GitHubSecret_ARM_MGMTGROUP_ID)" -ErrorAction Stop
    Write-Host "RBAC Role Assignments of 'Owner' for the User-Assigned Managed Identity Name (UAMI) '$($newUAMI.Name)' created successfully on the Management Group with the ID of '$($GitHubSecret_ARM_MGMTGROUP_ID)'." -ForegroundColor Green
    Write-Host ''
  }
}

# Set GitHub Repo Secrets (non-OIDC)
if ($UseOIDC -eq $false) {
  Write-Host "Setting GitHub Secrets on forked repository (non-OIDC) '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
  Write-Host 'Creating and formatting secret `AZURE_CREDENTIALS` with details from SPN creation process (non-OIDC) and other parameter inputs ...' -ForegroundColor Cyan

  $FormattedAzureCredentialsSecret = "{ 'clientId': '$($newSpn.AppId)', 'clientSecret': '$($newSpn.PasswordCredentials.SecretText)', 'subscriptionId': '$($GitHubSecret_ARM_SUBSCRIPTION_ID)', 'tenantId': '$($GitHubSecret_ARM_TENANT_ID)' }"
  $FormattedAzureCredentialsSecretJsonCompressed = $FormattedAzureCredentialsSecret | ConvertFrom-Json | ConvertTo-Json -Compress

  if ($GitHubSecret_ARM_MGMTGROUP_ID -ne '') {
    gh secret set ARM_MGMTGROUP_ID --body $GitHubSecret_ARM_MGMTGROUP_ID -R $GitHubOrgAndRepoNameCombined
  }
  gh secret set ARM_SUBSCRIPTION_ID --body $GitHubSecret_ARM_SUBSCRIPTION_ID -R $GitHubOrgAndRepoNameCombined
  gh secret set ARM_TENANT_ID --body $GitHubSecret_ARM_TENANT_ID -R $GitHubOrgAndRepoNameCombined
  gh secret set AZURE_CREDENTIALS --body $FormattedAzureCredentialsSecretJsonCompressed -R $GitHubOrgAndRepoNameCombined
  gh secret set TOKEN_NAMEPREFIX --body $GitHubSecret_TOKEN_NAMEPREFIX -R $GitHubOrgAndRepoNameCombined

  Write-Host ''
  Write-Host "Successfully created and set GitHub Secrets (non-OIDC) on forked repository '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Green
  Write-Host ''
}

# Set GitHub Repo Secrets & Environment (OIDC)
if ($UseOIDC) {
  Write-Host "Setting GitHub Environment (avm-validation) and required Secrets on forked repository (OIDC) '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
  Write-Host "Creating 'avm-validation' environment on forked repository' ..." -ForegroundColor Cyan

  $GitHubEnvironment = gh api --method PUT -H "Accept: application/vnd.github+json" "repos/$($GitHubOrgAndRepoNameCombined)/environments/avm-validation"
  $GitHubEnvironmentConvertedToJson = $GitHubEnvironment | ConvertFrom-Json -Depth 10

  if ($GitHubEnvironmentConvertedToJson.name -ne 'avm-validation') {
    throw "Failed to create 'avm-validation' environment on forked repository. Please check the error message above, resolve any issues, and try again."
  }

  Write-Host "Successfully created 'avm-validation' environment on forked repository' ..." -ForegroundColor Green
  Write-Host ''

  Write-Host "Creating and formatting secrets for 'avm-validation' environment with details from UAMI creation process (OIDC) and other parameter inputs ..." -ForegroundColor Cyan
  gh secret set VALIDATE_CLIENT_ID --body $newUAMI.ClientId -R $GitHubOrgAndRepoNameCombined -e 'avm-validation'
  gh secret set VALIDATE_SUBSCRIPTION_ID --body $GitHubSecret_ARM_SUBSCRIPTION_ID -R $GitHubOrgAndRepoNameCombined -e 'avm-validation'
  gh secret set VALIDATE_TENANT_ID --body $GitHubSecret_ARM_TENANT_ID -R $GitHubOrgAndRepoNameCombined -e 'avm-validation'

  Write-Host "Creating and formatting secrets for repo with details from UAMI creation process (OIDC) and other parameter inputs ..." -ForegroundColor Cyan
  if ($GitHubSecret_ARM_MGMTGROUP_ID -ne '') {
    gh secret set ARM_MGMTGROUP_ID --body $GitHubSecret_ARM_MGMTGROUP_ID -R $GitHubOrgAndRepoNameCombined
  }
  gh secret set ARM_SUBSCRIPTION_ID --body $GitHubSecret_ARM_SUBSCRIPTION_ID -R $GitHubOrgAndRepoNameCombined
  gh secret set ARM_TENANT_ID --body $GitHubSecret_ARM_TENANT_ID -R $GitHubOrgAndRepoNameCombined
  gh secret set TOKEN_NAMEPREFIX --body $GitHubSecret_TOKEN_NAMEPREFIX -R $GitHubOrgAndRepoNameCombined

  Write-Host ''
  Write-Host "Successfully created and set GitHub Secrets in 'avm-validation' environment and repo (OIDC) on forked repository '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Green
  Write-Host ''
}

Write-Host "Opening browser so you can enable GitHub Actions on newly forked repository '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
Write-Host "Please select click on the green button stating 'I understand my workflows, go ahead and enable them' to enable actions/workflows on your forked repository via the website that has appeared in your browser window and then return to this terminal session to continue ..." -ForegroundColor Yellow
Start-Process "https://github.com/$($GitHubOrgAndRepoNameCombined)/actions" -ErrorAction Stop
Write-Host ''

$GitHubWorkflowPlatformToggleWorkflows = '.Platform - Toggle AVM workflows'
$GitHubWorkflowPlatformToggleWorkflowsFileName = 'platform.toggle-avm-workflows.yml'

do {
  Write-Host "Did you successfully enable the GitHub Actions/Workflows on your forked repository '$($GitHubOrgAndRepoNameCombined)'? Please enter 'y' or 'n'." -ForegroundColor Yellow
  $userInput = Read-Host
  $userInput = $userInput.ToLower()

  switch ($userInput) {
    'y' {
      Write-Host ''
      Write-Host "User Confirmed. Proceeding to trigger workflow of '$($GitHubWorkflowPlatformToggleWorkflows)' to disable all workflows as per: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows/..." -ForegroundColor Green
      Write-Host ''
      break
    }
    'n' {
      Write-Host ''
      Write-Host 'User stated no. Ending script here. Please review and complete any of the steps you have not completed, likely just enabling GitHub Actions/Workflows on your forked repository and then disabling all workflows as per: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows/' -ForegroundColor Yellow
      exit
    }
    default {
      Write-Host ''
      Write-Host "Invalid input. Please enter 'y' or 'n'." -ForegroundColor Red
      Write-Host ''
    }
  }
} while ($userInput -ne 'y' -and $userInput -ne 'n')

Write-Host "Setting Read/Write Workflow permissions on forked repository '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
gh api --method PUT -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "/repos/$($GitHubOrgAndRepoNameCombined)/actions/permissions/workflow" -f "default_workflow_permissions=write"
Write-Host ''

Write-Host "Triggering '$($GitHubWorkflowPlatformToggleWorkflows) on '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
Write-Host ''
gh workflow run $GitHubWorkflowPlatformToggleWorkflows -R $GitHubOrgAndRepoNameCombined
Write-Host ''

Write-Host 'Starting 120 second sleep to allow the workflow run to complete ...' -ForegroundColor Yellow
Start-Sleep -Seconds 120
Write-Host ''

Write-Host "Workflow '$($GitHubWorkflowPlatformToggleWorkflows) on '$($GitHubOrgAndRepoNameCombined)' should have now completed, opening workflow in browser so you can check ..." -ForegroundColor Magenta
Start-Process "https://github.com/$($GitHubOrgAndRepoNameCombined)/actions/workflows/$($GitHubWorkflowPlatformToggleWorkflowsFileName)" -ErrorAction Stop
Write-Host ''

Write-Host "Script execution complete. Fork of '$($GitHubOrgAndRepoNameCombined)' created and configured and cloned to '$($ClonedRepoDirectoryLocation)' as per Bicep contribution guide: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/ you are now ready to proceed from step 4. Opening the Bicep Contribution Guide for you to review and continue..." -ForegroundColor Green
Start-Process 'https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/'

1. Fork the module source repository

Tip

Checkout the PowerShell Helper Script that can do this step automatically for you! 👍

Note

Each time in the following sections we refer to ‘your xyz’, it is an indicator that you have to change something in your own environment.

Bicep AVM Modules (Resource, Pattern and Utility modules) are located in the /avm directory of the Azure/bicep-registry-modules repository, as per SNFR19.

Module owners are expected to fork the Azure/bicep-registry-modules repository and work on a branch from within their fork, before creating a Pull Request (PR) back into the Azure/bicep-registry-modules repository’s upstream main branch.

To do so, simply navigate to the Public Bicep Registry repository, select the 'Fork' button to the top right of the UI, select where the fork should be created (i.e., the owning organization) and finally click ‘Create fork’.

1.1 Create a GitHub environment

Create the avm-validation environment in your fork.

➕ How to: Create an environment in GitHub

Navigate to the repository’s Settings.
In the list of settings, expand Environments. You can create a new environment by selecting New environment on the top right.
In the opening view, provide avm-validation for the environment Name. Click on the Configure environment button.

Please ref the following link for additional details: Creating an environment

2. Configure a deployment identity in Azure

AVM tests its modules via deployments in an Azure subscription. To do so, it requires a deployment identity with access to it.

Deprecating the Service Principal + Secret authentication method

Support for the ‘Service Principal + Secret’ authentication method has been deprecated and will be decommissioned in the future.

It is highly recommended to start leveraging Option 1 below to adopt OpenID Connect (OIDC) authentication and align with security best practices.

➕ Option 1 [Recommended]: OIDC - Configure a federated identity credential

Using a Managed Identity for OIDC

Make sure to use a Managed Identity for OIDC as instructed below, not a Service Principal. Azure access token issued by Managed Identities is expected to have an expiration of 24 hours by default. With Service Principal, instead, it would be only 1 hour - which is not sufficient for many deployment pipelines.

For more information, please refer to the official GitHub documentation.

Create a new or leverage an existing user-assigned managed identity with at least Contributor & User Access Administrator permissions on the Management-Group/Subscription you want to test the modules in. You may find creating an Owner role assignment is more efficient and avoids some validation failures for some modules. You might find the following links useful:
- Create a user-assigned managed identity
- Assign an appropriate role to your user-assigned managed identity

Additional roles

Some Azure resources may require additional roles to be assigned to the deployment identity. An example is the avm/res/aad/domain-service module, which requires the deployment identity to have the Domain Services Contributor Azure role to create the required Domain Services resources.

In those cases, for the first PR adding such modules to the public registry, we recommend the author to reach out to AVM maintainers or, alternatively, to create a CI environment GitHub issue in BRM, specifying the additional prerequisites. This ensures that the required additional roles get assigned in the upstream CI environment before the corresponding PR gets merged.

Configure a federated identity credential on a user-assigned managed identity to trust tokens issued by GitHub Actions to your GitHub repository.
- In the Microsoft Entra admin center, navigate to the user-assigned managed identity you created. Under Settings in the left nav bar, select Federated credentials and then Add Credential.
- In the Federated credential scenario dropdown box, select GitHub Actions deploying Azure resources
- For the Organization, specify your GitHub organization name, for the Repository the value bicep-registry-modules.
- For the Entity type, select Environment and specify the value avm-validation.
- Add a Name for the federated credential, for example, avm-gh-env-validation.
- The Issuer, Audiences, and Subject identifier fields auto-populate based on the values you entered.
- Select Add to configure the federated credential.
- You might find the following links & information useful:
  - If configuring the federated credential via API (e.g. Bicep, PowerShell etc.), you will need the following information points that are configured automatically for you via the portal experience:
    - Issuer = https://token.actions.githubusercontent.com
    - Subject = repo:<GitHub Org>/<GitHub Repo>:environment:avm-validation
    - Audience = api://AzureADTokenExchange (although this is default in the API so not required to set)
  - Configure a federated identity credential on a user-assigned managed identity
Note down the following pieces of information
- Client ID
- Tenant ID
- Subscription ID
- Parent Management Group ID

Additional references:

➕ Option 2 [Deprecated]: Configure Service Principal + Secret

Create a new or leverage an existing Service Principal with at least Contributor & User Access Administrator permissions on the Management-Group/Subscription you want to test the modules in. You may find creating an Owner role assignment is more efficient and avoids some validation failures for some modules. You might find the following links useful:
Note down the following pieces of information
- Application (Client) ID
- Service Principal Object ID (not the object ID of the application)
- Service Principal Secret (password)
- Tenant ID
- Subscription ID
- Parent Management Group ID

3. Configure your CI environment

Tip

Checkout the PowerShell Helper Script that can do this step automatically for you! 👍

To configure the forked CI environment you have to perform several steps:

3.1. Set up secrets

3.1.1 Shared repository secrets

To use the Continuous Integration environment’s workflows you should set up the following repository secrets:

Secret Name	Example	Description
`ARM_MGMTGROUP_ID`	`11111111-1111-1111-1111-111111111111`	The group ID of the management group to test-deploy modules in. Is needed for resources that are deployed to the management group scope.
`ARM_SUBSCRIPTION_ID`	`22222222-2222-2222-2222-222222222222`	The ID of the subscription to test-deploy modules in. Is needed for resources that are deployed to the subscription scope. Note: This repository secret will be deprecated in favor of the `VALIDATE_SUBSCRIPTION_ID` environment secret required by the OIDC authentication.
`ARM_TENANT_ID`	`33333333-3333-3333-3333-333333333333`	The tenant ID of the Azure Active Directory tenant to test-deploy modules in. Is needed for resources that are deployed to the tenant scope. Note: This repository secret will be deprecated in favor of the `VALIDATE_TENANT_ID` environment secret required by the OIDC authentication.
`TOKEN_NAMEPREFIX`	`cntso`	Required. A short (3-5 character length), unique string that should be included in any deployment to Azure. Usually, AVM Bicep test cases require this value to ensure no two contributors deploy resources with the same name - which is especially important for resources that require a globally unique name (e.g., Key Vault). These characters will be used as part of each resource’s name during deployment. For more information, see the `[Special case: TOKEN_NAMEPREFIX]` note below.

Special case: TOKEN_NAMEPREFIX

To lower the barrier to entry and allow users to easily define their own naming conventions, we introduced a default ’name prefix’ for all deployed resources.

This prefix is only used by the CI environment you validate your modules in, and doesn’t affect the naming of any resources you deploy as part of any solutions (applications/workloads) based on the modules.

Each workflow in AVM deploying resources uses a logic that automatically replaces “tokens” (i.e., placeholders) in any module test file. These tokens are, for example, included in the resources names (e.g. 'name: kvlt-${namePrefix}'). Tokens are stored as repository secrets to facilitate maintenance.

➕ How to: Add a repository secret to GitHub

Navigate to the repository’s Settings.
In the list of settings, expand Secrets and select Actions. You can create a new repository secret by selecting New repository secret on the top right.
In the opening view, you can create a secret by providing a secret Name, a secret Value, followed by a click on the Add secret button.

3.1.2 Authentication secrets

In addition to shared repository secrets detailed above, additional GitHub secrets are required to allow the deploying identity to authenticate to Azure.

Expand and follow the option corresponding to the deployment identity setup chosen at Step 2 and use the information you gathered during that step.

➕ Option 1 [Recommended]: Authenticate via OIDC

Create the following environment secrets in the avm-validation GitHub environment created at Step 1

Secret Name	Example	Description
`VALIDATE_CLIENT_ID`	`44444444-4444-4444-4444-444444444444`	The login credentials of the deployment principal used to log into the target Azure environment to test in. The format is described here.
`VALIDATE_SUBSCRIPTION_ID`	`22222222-2222-2222-2222-222222222222`	Same as the `ARM_SUBSCRIPTION_ID` repository secret set up above. The ID of the subscription to test-deploy modules in. Is needed for resources that are deployed to the subscription scope.
`VALIDATE_TENANT_ID`	`33333333-3333-3333-3333-333333333333`	Same as the `ARM_TENANT_ID` repository secret set up above. The tenant ID of the Azure Active Directory tenant to test-deploy modules in. Is needed for resources that are deployed to the tenant scope.

➕ How to: Add an environment secret to GitHub

Navigate to the repository’s Settings.
In the list of settings, select Environments. Click on the previously created avm-validation environment.
In the Environment secrets Section click on the Add environment secret button.
In the opening view, you can create a secret by providing a secret Name, a secret Value, followed by a click on the Add secret button.

➕ Option 2 [Deprecated]: Authenticate via Service Principal + Secret

Create the following environment repository secret:

Secret Name	Example	Description
`AZURE_CREDENTIALS`	`{"clientId": "44444444-4444-4444-4444-444444444444", "clientSecret": "<placeholder>", "subscriptionId": "22222222-2222-2222-2222-222222222222", "tenantId": "33333333-3333-3333-3333-333333333333" }`	The login credentials of the deployment principal used to log into the target Azure environment to test in. The format is described here. For more information, see the `[Special case: AZURE_CREDENTIALS]` note below.

Special case: AZURE_CREDENTIALS

This secret represent the service connection to Azure, and its value is a compressed JSON object that must match the following format:

{"clientId": "<client_id>", "clientSecret": "<client_secret>", "subscriptionId": "<subscriptionId>", "tenantId": "<tenant_id>" }

Make sure you create this object as one continuous string as shown above - using the information you collected during Step 2. Failing to format the secret as above, causes GitHub to consider each line of the JSON object as a separate secret string. If you’re interested, you can find more information about this object here.

3.2. Enable actions

Finally, ‘GitHub Actions’ are disabled by default and hence, must be enabled first.

To do so, perform the following steps:

Navigate to the Actions tab on the top of the repository page.
Next, select ‘I understand my workflows, go ahead and enable them’.

3.3. Set Read/Write Workflow permissions

To let the workflow engine publish their results into your repository, you have to enable the read / write access for the GitHub actions.

Navigate to the Settings tab on the top of your repository page.
Within the section Code and automation click on Actions and General
Make sure to enable Read and write permissions

Tip

Once you enabled the GitHub actions, your workflows will behave as they do in the upstream repository. This includes a scheduled trigger to continuously check that all modules are working and compliant with the latest tests. However, testing all modules can incur substantial costs with the target subscription. Therefore, we recommend disabling all workflows of modules you are not working on. To make this as easy as possible, we created a workflow that disables/enables workflows based on a selected toggle & naming pattern. For more information on how to use this workflow, please refer to the corresponding documentation.

4. Implement your contribution

To implement your contribution, we kindly ask you to first review the Bicep specifications and composition guidelines in particular to make sure your contribution complies with the repository’s design and principles.

If you’re working on a new module, we’d also ask you to create its corresponding workflow file. Each module has its own file, but only differs in very few details, such as its triggers and pipeline variables. As a result, you can either copy & update any other module workflow file (starting with 'avm.[res|ptn|utl].') or leverage the following template:

➕ Module workflow template

# >>> UPDATE to for example "avm.res.key-vault.vault" and remove this comment
name: "avm.[res|ptn|utl].[provider-namespace].[resource-type]"

on:
  workflow_dispatch:
    inputs:
      staticValidation:
        type: boolean
        description: "Execute static validation"
        required: false
        default: true
      deploymentValidation:
        type: boolean
        description: "Execute deployment validation"
        required: false
        default: true
      removeDeployment:
        type: boolean
        description: "Remove deployed module"
        required: false
        default: true
      customLocation:
        type: string
        description: "Default location overwrite (e.g., eastus)"
        required: false
  push:
    branches:
      - main
    paths:
      - ".github/actions/templates/avm-**"
      - ".github/workflows/avm.template.module.yml"
        # >>> UPDATE to for example ".github/workflows/avm.res.key-vault.vault.yml" and remove this comment
      - ".github/workflows/avm.[res|ptn|utl].[provider-namespace].[resource-type].yml"
        # >>> UPDATE to for example "avm/res/key-vault/vault/**" and remove this comment
      - "avm/[res|ptn|utl]/[provider-namespace]/[resource-type]/**"
      - "utilities/pipelines/**"
      - "!utilities/pipelines/platform/**"
      - "!*/**/README.md"

env:
  # >>> UPDATE to for example "avm/res/key-vault/vault" and remove this comment
  modulePath: "avm/[res|ptn|utl]/[provider-namespace]/[resource-type]"
  # >>> Update to for example ".github/workflows/avm.res.key-vault.vault.yml" and remove this comment
  workflowPath: ".github/workflows/avm.[res|ptn|utl].[provider-namespace].[resource-type].yml"

concurrency:
  group: ${{ github.workflow }}

jobs:
  ###########################
  #   Initialize pipeline   #
  ###########################
  job_initialize_pipeline:
    runs-on: ubuntu-latest
    name: "Initialize pipeline"
    steps:
      - name: "Checkout"
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: "Set input parameters to output variables"
        id: get-workflow-param
        uses: ./.github/actions/templates/avm-getWorkflowInput
        with:
          workflowPath: "${{ env.workflowPath}}"
      - name: "Get module test file paths"
        id: get-module-test-file-paths
        uses: ./.github/actions/templates/avm-getModuleTestFiles
        with:
          modulePath: "${{ env.modulePath }}"
    outputs:
      workflowInput: ${{ steps.get-workflow-param.outputs.workflowInput }}
      moduleTestFilePaths: ${{ steps.get-module-test-file-paths.outputs.moduleTestFilePaths }}
      psRuleModuleTestFilePaths: ${{ steps.get-module-test-file-paths.outputs.psRuleModuleTestFilePaths }}
      modulePath: "${{ env.modulePath }}"

  ##############################
  #   Call reusable workflow   #
  ##############################
  call-workflow-passing-data:
    name: "Run"
    permissions:
      id-token: write # For OIDC
      contents: write # For release tags
    needs:
      - job_initialize_pipeline
    uses: ./.github/workflows/avm.template.module.yml
    with:
      workflowInput: "${{ needs.job_initialize_pipeline.outputs.workflowInput }}"
      moduleTestFilePaths: "${{ needs.job_initialize_pipeline.outputs.moduleTestFilePaths }}"
      psRuleModuleTestFilePaths: "${{ needs.job_initialize_pipeline.outputs.psRuleModuleTestFilePaths }}"
      modulePath: "${{ needs.job_initialize_pipeline.outputs.modulePath}}"
    secrets: inherit

Tip

After any change to a module and before running tests, we highly recommend running the Set-AVMModule utility to update all module files that are auto-generated (e.g., the main.json & readme.md files).

5. Create/Update and run tests

Before opening a Pull Request to the Bicep Public Registry, ensure your module is ready for publishing, by validating that it meets all the Testing Specifications as per SNFR1, SNFR2, SNFR3, SNFR4, SNFR5, SNFR6, SNFR7.

For example, to meet SNFR2, ensure the updated module is deployable against a testing Azure subscription and compliant with the intended configuration.

Depending on the type of contribution you implemented (for example, a new resource module feature) we would kindly ask you to also update the e2e test run by the pipeline. For a new parameter this could mean to either add its usage to an existing test file, or to add an entirely new test as per BCPRMNFR1.

Once the contribution is implemented and the changes are pushed to your forked repository, we kindly ask you to validate your updates in your own cloud environment before requesting to merge them to the main repo. Test your code leveraging the forked AVM CI environment you configured before

Tip

In case your contribution involves changes to a module, you can also optionally leverage the Validate module locally utility to validate the updated module from your local host before validating it through its pipeline.

Creating end-to-end tests

As per BCPRMNFR1, a resource module must contain a minimum set of deployment test cases, while for pattern modules there is no restriction on the naming each deployment test must have.
In either case, you’re free to implement any additional, meaningful test that you see fit. Each test is implemented in its own test folder, containing at least a main.test.bicep and optionally any amount of extra deployment files that you may require (e.g., to deploy dependencies using a dependencies.bicep that you reference in the test template file).

To get started implementing your test in the main.test.bicep file, we recommend the following guidelines:

As per BCPNFR13, each main.test.bicep file should implement metadata to render the test more meaningful in the documentation
The main.test.bicep file should deploy any immediate dependencies (e.g., a resource group, if required) and invoke the module’s main template while providing all parameters for a given test scenario.
Parameters
- Each file should define a parameter serviceShort. This parameter should be unique to this file (i.e, no two test files should share the same) as it is injected into all resource deployments, making them unique too and account for corresponding requirements.
  - As a reference you can create a identifier by combining a substring of the resource type and test scenario (e.g., in case of a Linux Virtual Machine Deployment: vmlin).
  - For the substring, we recommend to take the first character and subsequent ‘first’ character from the resource type identifier and combine them into one string. Following you can find a few examples for reference:
    - db-for-postgre-sql/flexible-server with a test folder default could be: dfpsfsdef
    - storage/storage-account with a test folder waf-aligned could be: ssawaf
    💡 If the combination of the servicesShort with the rest of a resource name becomes too long, it may be necessary to bend the above recommendations and shorten the name.
    This can especially happen when deploying resources such as Virtual Machines or Storage Accounts that only allow comparatively short names.
- If the module deploys a resource-group-level resource, the template should further have a resourceGroupName parameter and subsequent resource deployment. As a reference for the default name you can use dep-<namePrefix><providerNamespace>.<resourceType>-${serviceShort}-rg.
- Each file should also provide a location parameter that may default to the deployments default location
It is recommended to define all major resource names in the main.test.bicep file as it makes later maintenance easier. To implement this, make sure to pass all resource names to any referenced module (including any resource deployed in the dependencies.bicep).
Further, for any test file (including the dependencies.bicep file), the usage of variables should be reduced to the absolute minimum. In other words: You should only use variables if you must use them in more than one place. The idea is to keep the test files as simple as possible
References to dependencies should be implemented using resource references in combination with outputs. In other words: You should not hardcode any references into the module template’s deployment. Instead use references such as nestedDependencies.outputs.managedIdentityPrincipalId
Important
As per BCPNFR12 you must use the header module testDeployment '../.*main.bicep' = when invoking the module’s template.
Tip
📜 Example of test file

Dependency file (dependencies.bicep) guidelines:

The dependencies.bicep should optionally be used if any additional dependencies must be deployed into a nested scope (e.g. into a deployed Resource Group).
Note that you can reuse many of the assets implemented in other modules. For example, there are many recurring implementations for Managed Identities, Key Vaults, Virtual Network deployments, etc.
A special case to point out is the implementation of Key Vaults that require purge protection (for example, for Customer Managed Keys). As this implies that we cannot fully clean up a test deployment, it is recommended to generate a new name for this resource upon each pipeline run using the output of the utcNow() function at the time.
Tip
📜 Example of test using purge protected Key Vault dependency
Tip
📜 If your test case requires any value that you cannot / should not specify in the test file itself (e.g., tenant-specific object IDs or secrets), please refer to the Custom CI secrets feature.

Reusable assets

There are a number of additional scripts and utilities available here that may be of use to module owners/contributors. These contain both scripts and Bicep templates that you can re-use in your test files (e.g., to deploy standadized dependencies, or to generate keys using deployment scripts).

Example: Certificate creation script

If you need a Deployment Script to set additional non-template resources up (for example certificates/files, etc.), we recommend to store it as a file in the shared utilities/e2e-template-assets/scripts folder and load it using the template function loadTextContent() (for example: scriptContent: loadTextContent('../../../../../../utilities/e2e-template-assets/scripts/New-SSHKey.ps1')). This approach makes it easier to test & validate the logic and further allows reusing the same logic across multiple test cases.

Example: Diagnostic Settings dependencies

To test the numerous diagnostic settings targets (Log Analytics Workspace, Storage Account, Event Hub, etc.) the AVM core team have provided a dependencies .bicep file to help create all these pre-requisite targets that will be needed during test runs.

➕ Diagnostic Settings Dependencies - Bicep File

// ========== //
// Parameters //
// ========== //

@description('Required. The name of the storage account to create.')
@maxLength(24)
param storageAccountName string

@description('Required. The name of the log analytics workspace to create.')
param logAnalyticsWorkspaceName string

@description('Required. The name of the event hub namespace to create.')
param eventHubNamespaceName string

@description('Required. The name of the event hub to create inside the event hub namespace.')
param eventHubNamespaceEventHubName string

@description('Optional. The location to deploy resources to.')
param location string = resourceGroup().location

// ============ //
// Dependencies //
// ============ //

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-08-01' = {
  name: storageAccountName
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
  properties: {
    allowBlobPublicAccess: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2021-12-01-preview' = {
  name: logAnalyticsWorkspaceName
  location: location
}

resource eventHubNamespace 'Microsoft.EventHub/namespaces@2021-11-01' = {
  name: eventHubNamespaceName
  location: location

  resource eventHub 'eventhubs@2021-11-01' = {
    name: eventHubNamespaceEventHubName
  }

  resource authorizationRule 'authorizationRules@2021-06-01-preview' = {
    name: 'RootManageSharedAccessKey'
    properties: {
      rights: [
        'Listen'
        'Manage'
        'Send'
      ]
    }
  }
}

// ======= //
// Outputs //
// ======= //

@description('The resource ID of the created Storage Account.')
output storageAccountResourceId string = storageAccount.id

@description('The resource ID of the created Log Analytics Workspace.')
output logAnalyticsWorkspaceResourceId string = logAnalyticsWorkspace.id

@description('The resource ID of the created Event Hub Namespace.')
output eventHubNamespaceResourceId string = eventHubNamespace.id

@description('The resource ID of the created Event Hub Namespace Authorization Rule.')
output eventHubAuthorizationRuleId string = eventHubNamespace::authorizationRule.id

@description('The name of the created Event Hub Namespace Event Hub.')
output eventHubNamespaceEventHubName string = eventHubNamespace::eventHub.name

6. Create a Pull Request to the Public Bicep Registry

Finally, once you are satisfied with your contribution and validated it, open a PR for the module owners or core team to review. Make sure you:

Provide a meaningful title in the form of feat: <module name> to align with the Semantic PR Check.
Provide a meaningful description.
Follow instructions you find in the PR template.
If applicable (i.e., a module is created/updated), please reference the badge status of your pipeline run. This badge will show the reviewer that the code changes were successfully validated & tested in your environment. To create a badge, first select the three dots (...) at the top right of the pipeline, and then chose the Create status badge option.
In the opening pop-up, you first need to select your branch and then click on the Copy status badge Markdown

Note

If you’re the sole owner of the module, the AVM core team must review and approve the PR. To indicate that your PR needs the core team’s attention, apply the Needs: Core Team 🧞 label on it!

Custom CI Secrets

When working on a module, and more specifically its e2e deployment validation test cases, it may be necessary to leverage tenant-specific information such as:

Entra-ID-provided Enterprise Application object ids (e.g., Backup Management Service, Azure Databricks, etc.)
(sensitive) principal credentials (e.g., a custom service principal’s application id and secret)

The challenge with the former is that the value would be different from the contributor’s test tenant compared to the Upstream AVM one. This requires the contributor to temporarily change the value to their own tenant’s value during the contribution’s creation & testing, and for the reviewer to make sure the value is changed back before merging a PR in.
The challenge with the later is more critical as it would require the contributor to store sensitive information in source control and as such publish it.

To mitigate this challenge, the AVM CI provides you with the feature to store any such information in a custom Azure Key Vault and automatically pass it into your test cases in a dynamic & secure way.

Important

Since all modules must pass the tests in the AVM environment, it is important that you inform the maintainers when you add a new custom secret. The same secret must then also be set up in the upstream environment before the pull request is merged.

To make this matter not too complicated, we would like to ask you to emphasize this requirement in the description of your PR, for example by adding a text similar to:

- [ ] @avm-core-team-technical-bicep TODO: Add custom secret 'mySecret' to AVM CI

Example use case

Let’s assume you need a tenant-specific value like the object id of Azure’s Backup Management Service Enterprise Application for one of your tests. As you want to avoid hardcoding and consequently changing its value each time you want to contribute from your Fork to the main AVM repository, you want to instead have it be automatically pulled into your test cases.

To do so, you create a new parameter in your test case’s main.test.bicep file that you call, for example,

@secure()
param backupManagementServiceEnterpriseApplicationObjectId string = ''

assuming that it would be provided with the correct value by the AVM CI. You consequently reference it in your test case as you would with any other Bicep parameter.

Next, you create a new secret of the same name with a prefix CI- in a previously created Azure Key Vault of your test subscription (e.g., CI-backupManagementServiceEnterpriseApplicationObjectId). Its value would be the object id the Enterprise Application has in the tenant of your test subscription.

Assuming that also the CI_KEY_VAULT_NAME GitHub Repository variable is configured correctly, you can now run your test pipeline and observe how the CI automatically pulls the secret and passes it into your test cases, IF, they have a parameter with a matching name.

Setup

Pre-Requisites

To use this feature, there are really only three prerequisites:

Create an Azure Key Vault in your test subscription
Grant the principal you use for testing in the CI at least `Key Vault Secrets User’ permissions on that Key Vault to enable it to pull secrets from it
Configure the name of that Key Vault as a ‘Repository variable’ CI_KEY_VAULT_NAME in your Fork.

The above will enable the CI to identify your Key Vault, look for matching secrets in it, and pull their values as needed.

Configuring a secret

Building upon the prerequisites you only have to implement two actions per value to dynamically populate them during deployment validation:

Create a @secure() parameter in your test file (main.test.bicep) that you want to populate and use it as you see fit.

For example:

@description('Required. My parameter\'s description. This value is tenant-specific and must be stored in the CI Key Vault in a secret named \'CI-MySecret\'.')
@secure()
param mySecret string = ''

Important

It is mandatory to declare the parameter as secure() as Key Vault secrets will be pulled and passed into the deployment as SecureString values.

Also, it must have an empty default to be compatible with the PSRule scans that require a value for all parameters.

Configure a secret of the same name, but with a CI- prefix and corresponding value in the Azure Key Vault you set up as per the prerequisites.

How it works

Assuming you completed both the prerequisites & setup steps and triggered your module’s workflow, the CI will perform the following actions:

When approaching the deployment validation steps, the workflow will lookup the CI_KEY_VAULT_NAME repository variable
If it has a value, it will subsequently pull all available secret references (not their values!) from that Key Vault, filtered down to only the secrets that match the CI- prefix
It will then loop through these secret references and check if any match a parameter in the targeted test.main.bicep of the same name, but without the CI- prefix
Only for a match, the workflow with then pull the secret from the Key Vault and pass its value as a SecureString as a parameter into the template deployment.

When reviewing the log during or after a run, you can see each matching and pulled secret is/was added as part of the AdditionalParameters object as seen in the following:

Background: Why not simply use GitHub secrets?

When reviewing the above, you may wonder why an Azure Key Vault was used as opposed to simple GitHub secrets.

While the simplicity of GitHub secrets would be preferred, it unfortunately turned out that they would not provide us with the level of flexibility we need for our purposes.

Most notably, GitHub secrets are not automatically available in referenced GitHub actions. Instead, you have to declare every secret you want to use explicitly in the workflow’s template, requiring the contributor to update both the module’s workflow template as well as test files each time a new value would be added.
This characteristic is not only unfortunate for our use case, but is also a lot more likely to lead to mistakes.

Further, with the use of OIDC via Managed Identities, the hurdle to bootstrap & populate an Azure Key Vault is significantly lowered.

Enable or Disable Workflows

When forking the BRM repository, all workflows from the CI environment are also part of your fork. In an earlier step it was explained, how to set them up correctly, to verify your module development.

Due to the trigger mechanism of the workflows, eventually all of them run at some point in time, creating and deleting resources on Azure in your environment. That will also happen for modules, you are not working on. This will create costs in your own subscription and it can also create a queue for workflow runs, due to the lack of enough free agents.

To limit those workflow runs, you can manually disable each pipeline you do not want to run. As this is a time consuming task, there is script in the BRM repository, to disable (or enable) pipelines in a batch process, that can also be run via a workflow. You can also use RegEx to specify which pipelines should be included and which should be excluded.

Location

You can find the script under utilities/pipelines/platform/Switch-WorkflowState.ps1)
You can find the workflow under .github/workflows/platform.toggle-avm-workflows.yml

How it works

Browse to Actions and select the workflow from the list

Run the workflow platform.toggle-avm-workflows and set the following settings:

Enable or disable workflows to enable or disable workflows
RegEx which workflows are included include a specific set of workflows, using a RegEx.
RegEx which workflows are excluded exclude a specific set of workflows, using a RegEx.

Typical use cases

Disable all but one workflow

Enable or disable workflows to Disable
RegEx which workflows are included to avm\.(?:res|ptn|utl) (this is the default setting)
RegEx which workflows are excluded to avm.res.compute.virtual-machine (use the name of your own workflow. This example uses the workflow for virtual machine)

Disable all but multiple workflows

Enable or disable workflows to Disable
RegEx which workflows are included to avm\.(?:res|ptn|utl) (this is the default setting)
RegEx which workflows are excluded to (?:avm.res.compute.virtual-machine|avm.res.compute.image|avm.res.compute.disk) (use the names of your own workflows. This example uses the workflows for virtual machine, image, and disk)

Enable all workflows

Enable or disable workflows to Enable
RegEx which workflows are included to avm\.(?:res|ptn|utl) (this is the default setting)
RegEx which workflows are excluded to ^$ (this is the default setting)

Limitations

Please keep in mind, that the workflow run disables all workflows that match the RegEx at that point in time. If you sync your fork with the original repository and new workflows are there, they will be synced to your repository and will be enabled by default. So you will need to run the workflow to disable the new ones again after the sync.

Important

The workflow can only be triggered in forks.

Owner Contribution Flow

This section describes the contribution flow for module owners who are responsible for creating and maintaining Bicep Modules.

Important

This contribution flow is for Module Owners only.

As a Bicep Module Owner you need to be aware of the AVM Contribution Process Overview, Bicep specifications (including Bicep Interfaces) as these need to be followed during pull request reviews for the modules you own. The purpose of this Owner Contribution Flow is to simplify and list the most important activities of an owner and to help you understand your responsibilities as an owner.

Note

Additional internal content for ongoing module maintenance available for Microsoft FTEs, here.

1. Owner Activities and Responsibilities

Familiarise yourself with the responsibilities as Module Owner outlined in Team Definitions & RACI and Module Owner Responsibilities in the BRM Issue Triage.

Create GitHub teams as outlined in SNFR20 and add respective parent teams:
Segments:
- avm-res-<RP>-<modulename>-module-owners-bicep
- avm-res-<RP>-<modulename>-module-contributors-bicep
Examples:
- avm-res-compute-virtualmachine-module-owners-bicep and added avm-technical-reviewers-bicep as parent.
- avm-res-compute-virtualmachine-module-contributors-bicep and added avm-module-contributors-bicep as parent.
If a secondary owner is required, add the secondary owner to the avm-res-<RP>-<modulename>-module-owners-bicep team.
Only fulltime Microsoft employees can be added at this time.
Info
Once the teams have been created the AVM Core Team will review the team name and parent team membership for accuracy. A notification will automatically be sent to the AVM Core Team to inform them that their review needs to be completed.
Add teams to CODEOWNERS file as outlined in SNFR20.
Ensure your module has been tested before raising a PR. You can do this your own or in another module contributor’s environment - if any. Also, once a PR is raised, a GitHub workflow pipeline is required to be run successfully before the PR can be merged. This is to ensure that the module is working as expected and is compliant with the AVM specifications.
Note
If you’re the sole owner of the module, the AVM core team must review and approve the PR. To indicate that your PR needs the core team’s attention, apply the Needs: Core Team 🧞 label on it!
Ensure that the module(s) you own are compliant with the AVM Bicep specifications and are working as expected.
Watch Pull Request (PR) activity for your module(s) in the BRM repository (Bicep Registry Modules repository - where all Bicep AVM modules are published) and ensure that PRs are reviewed and merged in a timely manner as outlined in SNFR11.
Watch AVM module issue and AVM question/feedback activity for your module(s) in the BRM repository.

2. Module Handover Activities

Under certain circumstances, you may find yourself unable to continue as the module owner. In such cases, it is advisable to designate a new module owner. The following steps outline this transition:

Leave a comment on the original module proposal, indicating that you’d like to hand the ownership over to somebody else. Mention the person who originally helped triage the issue or the @Azure/avm-core-team-technical-bicep team. You must wait for someone from the AVM Core Team to respond first, as the module index must be updated before you can continue handing over the ownership.
Add the new owner’s GitHub account as a “maintainer” on your modules GitHub teams.
Remove your GitHub account from your module’s GitHub teams.

If a new module owner cannot be identified then the module will need to be “Orphaned”. Please follow the step outlined when-a-module-becomes-orphaned.

3. Adopting an Orphaned Module

When adopting an orphaned module the when-a-new-owner-is-identified steps must be followed.

4. GitHub Notification Settings

As a module owner, it’s important that you receive notifications when any of your AVM modules experience activity or when you or any groups you belong to are explicitly mentioned (using the @ operator). This document describes how to configure your GitHub and Email settings to ensure you receive email notifications for these types of scenarios within GitHub.

Enable Global GitHub Notifications

Visit the GitHub Notifications Settings Page while logged in with your GitHub account.

Ensure your Default Notifications Email address is set to the email address you intend to use.
(Optional) If you would like to automatically watch repositories that you are active in, ensure Automatically watch repositories is set to “On.”
(Required) If you would like to automatically subscribe to team-level notifications whenever you join a new team, ensure Automatically watch teams is set to “On.”
(Required) To receive notifications whenever a change is made to a repository or conversation that you are Watching, ensure the Notify Me setting has at least Email enabled.
(Required)To receive notifications whenever you or a group you belong to are @mentioned, ensure the Notify Me setting has at least Email enabled.

Watch a Repository

Optionally, you may consider “watching” (following most or all activities in) an entire repository. The primary repository that owners should watch is the Bicep-Registry-Modules (BRM) repository. Notifications from this repository will notify you of issues concerning your module and any direct or team @mentions. It is important that you read and react to these messages.

To watch the BRM repository, visit Bicep-Registry-Modules, click the Watch button in the top-right of the page, then select Participating and @mentions. Optionally, if you would like to be notified for all activity within the repository, you can select All Activity.

Note

Enabling All Activity will result in a lot of notifications! If you choose to go this route, you should set up filters within your email client. See Configure Email Inbox Notification Filters.

Configure Email Inbox Notification Filters

GitHub uses a unique email address sender for each type of notification it sends. This allows us to set up filters within our email client to sort our inboxes depending on the type of notifications that was sent. The table below lists all of the relevant email addresses that may be useful for filtering notifications from GitHub.

Info

GitHub will use the following email addresses to Cc you if you’re subscribed to a conversation. The second Cc email address matches the notification reason.

Type of Notification	GitHub Email Address	Notification Reason
@Mentions	mention@noreply.github.com	You were mentioned on an issue or pull request.
@Team Mention	team_mention@noreply.github.com	A team you belong to was mentioned on an issue or pull request
Subscribed	subscribed@noreply.github.com	There was an update in a repository you’re watching.
Assign	assign@noreply.github.com	You were assigned to an issue or pull request.
Comment	comment@noreply.github.com	You commented on an issue or pull request.

For a full list of GitHub notification types, see Filtering Email Notifications.

5. Contribution Checklist

This checklist can be used in the development of AVM Bicep Modules.

Before beginning any work a new module a valid Issue: New AVM Module Proposal needs to be created. Instructions for creating the module proposal are outlined in the issue template. Pay particular attention to the questions and associated links to fill out the proposal accurately. Please do not start work on your proposed module until you receive a notification that your proposal has been accepted.
Fork the bicep-registry-modules BRM repository. If you use an existing fork, ensure it’s up to date with origin/BRM.
- Ensure all workflows are disabled by default once you forked the BRM repo, to prevent any accidental deployments into your Azure test environment resulted by an automated deployment.
Create a new branch from your forked repository to develop your module.
If you’re working on a new module you have to create its corresponding workflow file (see here).
- In order to run your e2e tests in your fork, this workflow file has to be put into the main branch first, so it can be run against your feature branch (GitHub Workflows can only be run on feature branches when they are already present in the main branch).
- Since all workflows are disabled by default you have to enable your module’s specific GitHub workflow to run your e2e tests.
Implement your contribution.

Create, update, and run tests.

In addition to testing your module via GitHub pipeline, you can also test-locally. The following helper script facilitates local testing.

➕ Local Test Helper Script

# Start pwsh if not started yet

pwsh

# Set default directory
$folder = "<your directory>/bicep-registry-modules"

# Dot source functions

. $folder/utilities/tools/Set-AVMModule.ps1
. $folder/utilities/tools/Test-ModuleLocally.ps1

# Variables

$modules = @(
    # "service-fabric/cluster", # Replace with your module
    "network/private-endpoint"  # Replace with your module
)

# Generate Readme

foreach ($module in $modules) {
    Write-Output "Generating ReadMe for module $module"
    Set-AVMModule -ModuleFolderPath "$folder/avm/res/$module" -Recurse

    # Set up test settings

    $testcases = "waf-aligned", "max", "defaults"

    $TestModuleLocallyInput = @{
        TemplateFilePath           = "$folder/avm/res/$module/main.bicep"
        ModuleTestFilePath         = "$folder/avm/res/$module/tests/e2e/max/main.test.bicep"
        PesterTest                 = $true
        ValidationTest             = $false
        DeploymentTest             = $false
        ValidateOrDeployParameters = @{
            Location         = '<your location>'
            SubscriptionId   = '<your subscriptionId>'
            RemoveDeployment = $true
        }
        AdditionalTokens           = @{
            namePrefix = '<your prefix>'
            TenantId   = '<your tenantId>'
        }
    }

    # Run tests

    foreach ($testcase in $testcases) {
        Write-Output "Running test case $testcase on module $module"
        $TestModuleLocallyInput.ModuleTestFilePath = "$folder/avm/res/$module/tests/e2e/$testcase/main.test.bicep"
        Test-ModuleLocally @TestModuleLocallyInput
    }
}

Create a PR and reference the status badge of your pipeline run - see here.
Note
If you’re the sole owner of the module, the AVM core team must review and approve the PR. To indicate that your PR needs the core team’s attention, apply the Needs: Core Team 🧞 label on it!
After a pull request has been created, it is important to update the AVM module proposal issue associated with your module, with a link to the pull request you created in BRM and mention the person who helped triage your module or the @Azure/avm-core-team-technical-bicep team.
Once your BRM pull request has been approved and merged into main update the AVM module proposal issue associated with your module, with a Merged comment and mention the person who helped triage your module, or the @Azure/avm-core-team-technical-bicep team.

Generate Bicep Module Files

As per the module design structure (BCPFR3), every module in the AVM library requires

a up-to-date ReadMe markdown (readme.md) file documenting the set of deployable resource types, input and output parameters and a set of relevant template references from the official Azure Resource Reference documentation
an up-to-date compiled template (main.json) file

The Set-AVMModule utility aims to simplify contributing to the AVM library, as it supports

idempotently generating the AVM folder structure for a module (including any child resource)
generating the module’s ReadMe file from scratch or updating it
compiling/building the module template

To ease maintenance, you can run the utility with a Recurse flag from the root of your folder to update all files automatically.

Location

You can find the script under utilities/tools/Set-AVMModule.ps1

How it works

Using the provided template path, the script

validates the module’s folder structure
- To do so, it searches for any required folder path / file missing and adds them. For several files, it will also provide some default content to get you started. The sources files for this action can be found here
compiles its bicep template
updates the readme (recursively, specified)
1. If the intended readMe file does not yet exist in the expected path, it is generated with a skeleton (with e.g., a generated header name)
2. The script then goes through all sections defined as SectionsToRefresh (by default all) and refreshes the sections’ content (for example, for the Parameters) based on the values in the ARM/JSON Template. It detects sections by their header and always regenerates the full section.
3. Once all are refreshed, the current ReadMe file is overwritten. Note: The script can be invoked combining the WhatIf and Verbose switches to just receive an console-output of the updated content.

How to use it

For details on how to use the function, please refer to the script’s local documentation.

Note

The script must be loaded (’dot-sourced’) before the function can be invoked.

. 'C:/dev/Set-AVMModule.ps1'
Set-AVMModule (...)

Tip

For modules that require the generation of files on multiple-levels (for example, a module with child modules such as the ‘Key Vault’ module with its ‘Secret’ child module) it is highly recommended to make use of the -Recurse parameter.

This parameter will ensure that the script not only generates the files for the provided module folder path, but also all its nested module folder paths.

Tip

While readme files are always generated from scratch, you can add custom content is specific places that the script will preserve:

The module’s description in the main.bicep file’s metadata
The description of parameters & outputs
A section with the header ## Notes

If the utility finds a section with the heading ## Notes, it temporarily saves this content when it regenerates the readme file and then re-inserts (i.e. appends) the section towards the end of the readme file. This section may contain images, which must be stored in a subfolder /src in the root directory of the module.

Both for the text & images, please make sure to only add what provides tangible value as the content must be manually maintained and should not run stale. Further, for images, please make sure to only store them with an appropriate resolution & size to keep their impact on the repository’s size manageable.

Validate Module Locally

Use this script to test a module from your PC locally, without a CI environment. You can use it to run only the static validation (Pester tests), a deployment validation (dryRun) or an actual deployment to Azure. In the latter cases the script also takes care to replace placeholder tokens in the used module test & template files for you.

Location

You can find the script under utilities/tools/Test-ModuleLocally.ps1

How it works

If the switch for Pester tests (-PesterTest) is provided the script will

Invoke the module test for the provided template file path and run all tests for it.

If the switch for either the validation test (-ValidationTest) or deployment test (-DeploymentTest) is provided alongside a HashTable for the token replacement (-ValidateOrDeployParameters), the script will

Either fetch all module test files of the module’s tests folder (default) or you can specify a single module test file by leveraging the -ModuleTestFilePath parameter instead.
Create a dictionary to replace all tokens in these module test files with actual values. This dictionary will consist
- of the subscriptionID & managementGroupID of the provided ValidateOrDeployParameters object,
- add all key-value pairs of the -AdditionalTokens object to it,
- and optionally also add all key-value pairs specified in the settings.yml, under the ’local tokens settings'.
If the -ValidationTest parameter was set, it runs a deployment validation using the Test-TemplateDeployment script.
If the -DeploymentTest parameter was set, it runs a deployment using the New-TemplateDeployment script (with no retries).
As a final step, it rolls the module test files back to their original state if either the -ValidationTest or -DeploymentTest parameters were provided.

How to use it

For details on how to use the function, please refer to the script’s local documentation.

Note

The script must be loaded (’dot-sourced’) before the function can be invoked.

. 'C:/dev/Test-ModuleLocally.ps1'
Test-ModuleLocally (...)

Important

Important: As the script emulates the testing logic of the CI environment, also tokens such as #_namePrefix_# are replaced by the script. However, in addition to the CI environment, it also reverses the token replacement to recover the files’ original state. As such, ensure that you use a namePrefix value that is unlikely to overlap with any string value in module folder you want to test.

For example, do not use avm, as the reverse token replacement would incorrectly replace the deployment name avmTelemetry found in each module to #_namePrefix_#Telemetry.

Bicep Contribution Prerequisites

GitHub Account Link and Access

You need to have a personal GitHub account which is linked to your Microsoft corporate identity. Once the link step is complete you must join the Azure organization.

Recommended Learning

Before you start contributing to the AVM, it is highly recommended that you complete the following Microsoft Learn paths, modules & courses:

Bicep

Git

Introduction to version control with Git

Tooling

Required Tooling

To contribute to this project the following tooling is required:

Git

If just installed, don’t forget to set both your git username & password

git config --global user.name "John Doe"
git config --global user.email "johndoe@example.com"

Bicep
Note
Must be manually kept up-to-date.
Pester
Visual Studio Code
- Bicep extension for Visual Studio Code

Recommended Tooling

The following tooling/extensions are recommended to assist you developing for the project:

Visual Studio Code Extensions

CodeTour extension for Visual Studio Code
ARM Tools extension for Visual Studio Code
ARM Template Viewer extension for Visual Studio Code
PSRule extension for Visual Studio Code
EditorConfig for VS Code
For visibility of Bracket Pairs:
- Inside Visual Studio Code, add editor.bracketPairColorization.enabled: true to your settings.json, to enable bracket pair colorization.

Desktop Tooling

GitHub Desktop
- To enhance streamlined integration during interactions with upstream repositories, GitHub Desktop will automatically configure your local git repository to use the upstream repository as a remote.

Contribution Q&A

Tip

Check out the FAQ for more answers to common questions about the AVM initiative in general.

Proposing a module

Who can propose a new module and where can I submit a new module proposal / request?

Everyone can propose a module

To propose a new module, simply create an issue/complete the form here.

Can I just propose / create any module?

For example, can I propose one for managed disks or NICs or diagnostic settings? What about patterns?

No, you cannot propose or create just any module. You can only propose modules that are aligned with requirements documented in the module specifications section.

Below, we provide some guidance on what modules you can / cannot propose.

Resource modules: resource modules have bring extra value to the end user (can’t just be simple wrappers) and MUST mapped 1:1 to RPs (resource providers) and top level resources. You MUST follow the module specifications and your modules SHOULD be WAF aligned.
- Good examples:
  - Virtual machine: the VM module is highly complex and therefore, it brings extra value to the end user by providing a wide variety of features (e.g., diagnostics, RBAC, domain join, disk encryption, backup and more).
  - Storage account: even though, this module is mainly built around one RP, it brings extra value by providing easy access to its child resources, such as file/table/queue services, as well as additional standard interfaces (e.g., diagnostics, RBAC, encryption, firewall, etc.).
- Bad examples:
  - NIC or Public IP (PIP) module: these would be simple wrappers around the NIC/PIP resource and wouldn’t bring any extra value. NICs and PIPs SHOULD be surfaced as part of the VM module (or any other primary resources that require them).
  - Diagnostic settings: these are too low-level “sub resources”, and highly dependent on their “primary resource’s” RP defined as “interfaces” and therefore MUST be used as part of a resource module holding a primary resource - see Diagnostic Settings documentation about the correct implementation.
Pattern modules: In case of pattern modules, ideally you should start from architectural patterns, published in the Azure Architecture Center, and build your pattern module by leveraging resource modules that are required to implement the pattern. AVM does not provide architectural guidance on how you should design your pattern, but you MUST follow the module specifications and your modules SHOULD be WAF aligned.
- Good examples:
  - Landing zone accelerators for N-tier web application; AKS cluster; SAP: there are numerous examples for these architectures in Azure Architecture Center that already have baked in guidance / smart defaults that are WAF Aligned, therefore these are good candidates for pattern modules. Module owners MAY leverage resource modules to implement the pattern.
  - Hub and spoke topology: it’s a common pattern that is used by many customers and there are great examples available through Azure Architecture Center, as well as Azure Landing Zones. Also a good candidate for a pattern module.
- Bad examples:
  - A pair of Virtual machines: being a simple wrapper, this solution wouldn’t bring any extra value as it doesn’t provide a complete solution.
  - Key Vault that deploys automatically generated secrets: this is aligned with the definition of a resource modules, therefore it should be categorized as such.

Where do I need to go to make sure the module I’d like to propose is not already in the works?

The AVM core team maintains the list of Bicep and Terraform modules and tracks the status of each module. Based on this list, you can check if the module you’d like to build is already in the works (e.g., it’s being worked on in a feature branch but hasn’t been published yet).

To see the formatted lists with additional information, please visit the AVM Module Indexes page.

I need a new module but I cannot own/author it for various reasons, what should I do?

Each AVM module requires a module owner and MAY have additional module contributors.

Essentially, you have 3 options:

You sign up to be a module owner (and optionally, you can find additional contributors to help you).
You find / request someone else to be the module owner (and optionally, you can be a contributor).
You propose a module and wait until the AVM core team finds a module owner for you (who then can optionally leverage the help of additional contributors).

As these options are increasingly more time consuming, we recommend you to start with considering option 1 and only if you cannot own the module, should you move to option 2 and then 3.

You can propose a new module here.

How long will it take for someone to respond and a module to be created/updated and published?

While there are SLAs defined for providing support for existing modules, there are currently no SLAs in place for the creation of new modules. The AVM core team is a small team and is currently working on automating the module creation process to make it as easy as possible for module owners to create and publish modules on their own.

Beside of providing program level governance, the AVM core team is mainly responsible for defining the module specifications, providing tooling (such as test frameworks and pipelines), guidance and support to module owners, as well as facilitating the creation of new modules by maintaining the module catalog and identifying volunteers for owning the modules. However, modules will be created and maintained by a broader community of module owners.

How do I let the AVM team know I really need an AVM module to unblock me / my project / my company?

If you’re an external user, you can propose a module here and provide as much context as possible under the “Module Details” section (e.g., why do you need the module, what’s the business impact of not having it, etc.).
If you’re a Microsoft employee and have already proposed a module here, you can reach out to the AVM core team directly via Teams to provide more details internally.

The AVM core team will then triage the request and get back to you with next steps. You can accelerate the process of creating the module by volunteering to be a module owner.

Developing a module

Who is developing a modules?

Every module has an owner that is responsible for module development and maintenance. One owner can own one or multiple modules. An owner can develop modules alone or lead a team that will develop a module.
If you want to join a team and to contribute on specific module, please contact module owner.

At this moment, only Microsoft FTEs can be module owners.

What do I need so I can start developing a module?

We suggest that you review module specification and contribution guides:

Feel free to reach out to the AVM Core team in case that additional help is needed.

What do I do about existing modules that are available doing a similar thing to my module that I am proposing to develop and release?

As part of the Module Proposal process, the AVM core team will work with you to triage your proposal. We also want to make sure that no similar existing modules from known Microsoft projects are already on their way to be migrated to AVM.

If there aren’t any, then you can proceed with developing your module from scratch once given approval to proceed by the AVM core team.
However, if there are existing modules from Microsoft projects we would invite you to help us complete the migration to AVM of this module; this may also entail working with the existing module owner/team.

For existing modules that may not be directly owned and developed by Microsoft or their employees you should first review the license applied to the GitHub repository hosting the module and understand its terms and conditions. More information on GitHub repositories and licenses can be found here in Licensing a repository Most modules will use a license that will allow you to take inspiration and copy all or parts from the module source code. However, to confirm, you should always check the license and any conditions you may have to meet by doing this.

What are the mandatory labels that needs to be used while managing issues, pull requests and discussions on GitHub repositories where module are held?

To get list of labels that MUST be created on gitHub repositories where modules are held navigate to Shared non-functional requirement 23 (SNFR23).

You SHOULD NOT use any additional labels.

There is also a PowerShell script that the AVM core team created that can help to apply those labels the GitHub module repository.

Is there any naming convention for modules name, repository name, variables, parameters…. ?

AVM specification covers all naming conventions. As example:
Module naming specification

Where module will live? Do I need to create separate repo or to place it in specific folder?

Bicep

For Bicep, both Resource and Pattern, AVM Modules will be homed in the Azure/bicep-registry-modules repository and live within an avm directory that will be located at the root of the repository.

If you are module owner, it is expected that you will fork the Azure/bicep-registry-modules repository and work on a branch from within their fork, before then creating a Pull Request (PR) back into the Azure/bicep-registry-modules repositories main branch. In Bice contribution guide, you can discover Directory and File structure that will be used and examples.

Terraform

Each Terraform AVM module will have its own GitHub Repository in the Azure GitHub Organization.
This repo will be created by the Module Owners and the AVM Core team collaboratively, including the configuration of permissions.
To read more about how to start, navigate to Terraform AVM contribution guide.

I get the error ‘The repository ********** already exists on this account’ when I try to create a new repository, what should I do?

If you get this error, it means that the repository already exists in the Azure GitHub Organization. This can happen if someone has already created a repository with the same name in the past and then archived it.

To determine if this is the case you’ll need to navigate to the Microsoft Open Source Management Portal, then search for the repository name you are trying to create. Click on the repository and you will find the owner. Reach out the owner to ask them to transfer the repo to you or delete it. You’ll want them to delete it if it was not created from the template.

Where can I test my module during development?

During initial module development module owners/developers need to use your own environment (Azure subscriptions) to test module. In later phase, during publishing process, we will conduct automated test that will use AVM dedicated environment.

Updating and managing a module

I’m already using a module today, but its missing a feature, what should I do?

You should use GitHub issues to propose changes or improvements for specific module. Issue request will be routed to module owner that MUST respond to logged issues as per the defined support statement. In case that module currently don’t have owner, AVM Core Team will handle request.

I am using module without owner. What will happened if I need update?

AVM core team will work to assign owner for every module, but it can happen during a time that there are modules without owner. If you would like to own that module, feel free to ask to take ownership. At this moment, only Microsoft FTEs can be module owners.

How will the support SLAs be automatically enforced?

All issues created in a module repo will be automatically be picked up and tracked by the GitHub Policy Service. This service will take the necessary steps when escalation is needed as per the SLAs defined in the Module Support chapter.

Process Overview

This page provides an overview of the contribution process for AVM modules.

New Module Proposal & Creation

Important

Each AVM module MUST have a Module Proposal issue created and approved by the AVM core team before it can be created/migrated!

---
config:
  nodeSpacing: 20
  rankSpacing: 20
  diagramPadding: 5
  padding: 5
  useWidth: 100
  flowchart:
    wrappingWidth: 400
    padding: 5
---
flowchart TD
    ModuleIdea[Consumer has an idea for a new AVM Module] -->CheckIndex(Check AVM Module Indexes)
        click CheckIndex "/Azure-Verified-Modules/indexes/"
    CheckIndex -->IndexExistenceCheck{Is the module<br>in the index?}
    IndexExistenceCheck -->|No|A
    IndexExistenceCheck -->|Yes|EndExistenceCheck(Review existing/proposed AVM module)
    EndExistenceCheck -->OrphanedCheck{ Is the module<br>orphaned? }
        click OrphanedCheck "/Azure-Verified-Modules/specs/shared/module-lifecycle/#orphaned-avm-modules"
    OrphanedCheck -->|No|ContactOwner[Contact module owner,<br> via GitHub issues on the related <br>repo, to discuss enhancements/<br>bugs/opportunities to contribute etc.]
    OrphanedCheck -->|Yes|OrphanOwnerYes(Locate the related issue <br> and comment on:<br> - A feature/enhancement suggestion <br> - Indicating you wish to become the owner)
        click OrphanOwnerYes "/Azure-Verified-Modules/specs/shared/module-lifecycle/#orphaned-avm-modules"
    OrphanOwnerYes -->B
    A[[ Create Module Proposal ]] -->|GitHub Issue/Form Submitted| B{ AVM Core Team<br>Triage }
        click A "https://aka.ms/avm/moduleproposal"
        click B "/Azure-Verified-Modules/help-support/issue-triage/avm-issue-triage/#avm-core-team-triage-explained"
    B -->|Module Approved for Creation| C[["Module Owner(s) Identified  & assigned to GitHub issue/proposal" ]]
    B -->|Module Rejected| D(Issue closed with reasoning)
    C -->E[[ Module index CSV files updated by AVM Core Team]]
        click E "/Azure-Verified-Modules/indexes/"
    E -->E1[[Repo/Directory Created following the <br> Contribution Guide ]]
        click E1 "/Azure-Verified-Modules/contributing/"
    E1 -->F("Module Developed by Owner(s) & their Contributors")
    F -->G[[ Module & AVM Compliance Tests ]]
        click G "/Azure-Verified-Modules/spec/SNFR3"
    G -->|Tests Fail|I(Modules/Tests Fixed <br> To Make Them Pass)
    I -->F
    G -->|Tests Pass|J[[Pre-Release v0.1.0 created]]
    J -->K[[Publish to Bicep/Terraform Registry]]
    K -->L(Take Feedback from v0.1.0 Consumers)
    L -->M{Anything<br>to be resolved <br> before 1.0.0<br>release? }
        click M "/Azure-Verified-Modules/contributing/process/#avm-preview-notice"
    M -->|Yes|FixPreV1("Module feedback incorporated by Owner(s) & their Contributors")
    FixPreV1 -->PreV1Tests[[Self & AVM Module Tests]]
    PreV1Tests -->|Tests Fail|PreV1TestsFix(Modules/Tests Fixed To Make Them Pass)
    PreV1TestsFix -->N
    M -->|No|N[[Publish 1.0.0 Release]]
    N -->O[[Publish to IaC Registry]]
    O -->P[[ Module BAU Starts ]]
        click P "/Azure-Verified-Modules/help-support/module-support/"

Provide details for module proposals

When proposing a module, please include the information in the description that is mentioned for the triage process here:

AVM Preview Notice

Important

As the overall AVM framework is not GA (generally available) yet - the CI framework and test automation is not fully functional and implemented across all supported languages yet - breaking changes are expected, and additional customer feedback is yet to be gathered and incorporated. Hence, modules MUST NOT be published at version 1.0.0 or higher at this time.

All module MUST be published as a pre-release version (e.g., 0.1.0, 0.1.1, 0.2.0, etc.) until the AVM framework becomes GA.

However, it is important to note that this DOES NOT mean that the modules cannot be consumed and utilized. They CAN be leveraged in all types of environments (dev, test, prod etc.). Consumers can treat them just like any other IaC module and raise issues or feature requests against them as they learn from the usage of the module. Consumers should also read the release notes for each version, if considering updating to a more recent version of a module to see if there are any considerations or breaking changes etc.

Module Owner Has Issue/Is Blocked/Has A Request

In the event that a module owner has an issue or is blocked due to specific AVM missing guidance, test environments, permission requirements, etc. they should follow the below steps:

Tip

Common issues/blockers/asks/request are:

Subscription level features
Resource Provider Registration
Preview Services Enablement
Entra ID (formerly Azure Active Directory) configuration (SPN creation, etc.)

Create a GitHub Issue
Discuss the issue/blocker with the AVM core team
Agree upon action/resolution/closure
Implement agreed upon action/resolution/closure

Note

Please note for module specific issues, these should be logged in the module’s source repository, not the AVM repository.

Terraform Contribution Guide

Important

While this page describes and summarizes important aspects of contributing to AVM, it only references some of the shared and language specific requirements.

Therefore, this contribution guide MUST be used in conjunction with the Terraform specifications. ALL AVM modules (Resource and Pattern modules) MUST meet the respective requirements described in these specifications!

Summary

This section lists AVM’s Terraform-specific contribution guidance.

Terraform Composition

Important

While this page describes and summarizes important aspects of the composition of AVM modules, it may not reference All of the shared and language specific requirements.

Therefore, this guide MUST be used in conjunction with the Terraform specifications. ALL AVM modules (Resource and Pattern modules) MUST meet the respective requirements described in these specifications!

Important

Before jumping on implementing your contribution, please review the AVM Module specifications, in particular the Terraform specification pages, to make sure your contribution complies with the AVM module’s design and principles.

Repositories

Each Terraform AVM module will have its own GitHub Repository in the Azure GitHub Organization as per SNFR19.

This repo will be created by the Module Owners and the AVM Core team collaboratively, including the configuration of permissions as per SNFR9

Directory and File Structure

Below is the directory and file structure expected for each AVM Terraform repository/module.
See template repo here.

tests/ - (for unit tests and additional tests if required - e.g. tflint etc.)
- unit/ - (optional, may use further sub-directories if required)
modules/ - (for sub-modules only if used)
examples/ - (all examples must deploy without successfully without requiring input - these are customer facing)
- <at least one folder> - (at least one example that uses the variable defaults minimum/required parameters/variables only)
- <other folders for examples as required>
/... - (Module files that live in the root of module directory)
- _header.md - (required for documentation generation)
- _footer.md - (required for documentation generation)
- main.tf
- locals.tf
- variables.tf
- outputs.tf
- terraform.tf
- README.md (autogenerated)
- main.resource1.tf (If a larger module you may chose to use dot notation for each resource)
- locals.resource1.tf

Directory and File Structure

/ root
│
├───.github/
│   ├───actions/
│   │   ├───avmfix/
│   │   │   └───action.yml
│   │   ├───docs-check/
│   │   │   └───action.yml
│   │   ├───e2e-getexamples/
│   │   │   └───action.yml
│   │   ├───e2e-testexamples/
│   │   │   └───action.yml
│   │   ├───linting/
│   │   │   └───action.yml
│   │   └───version-check/
│   │       └───action.yml
│   ├───policies/
│   │   ├───avmrequiredfiles.yml
│   │   └───branchprotection.yml
│   ├───workflows/
│   │   ├───e2e.yml
│   │   ├───linting.yml
│   │   └───version-check.yml
│   ├───CODEOWNERS
│   └───dependabot.yml
├───.vscode/
│   ├───extensions.json
│   └───settings.json
├───examples/
│   ├───<example_folder>/
│   │   ├───README.md
│   │   ├───_footer.md
│   │   ├───_header.md
│   │   ├───main.tf
│   │   └───variables.tf
│   ├───.terraform-docs.yml
│   └───README.md
├───modules/
│   └───README.md
├───tests/
│   └───README.md
├───.gitignore
├───.terraform-docs.yml
├───CODE_OF_CONDUCT.md
├───LICENSE
├───Makefile
├───README.md
├───SECURITY.md
├───SUPPORT.md
├───_footer.md
├───_header.md
├───avm
├───avm.bat
├───locals.tf
├───main.privateendpoint.tf
├───main.telemetry.tf
├───main.tf
├───outputs.tf
├───terraform.tf
└───variables.tf

Code Styling

This section points to conventions to be followed when developing a module.

Casing

Use snake_casing as per TFNFR3.

Input Parameters and Variables

Make sure to review all specifications of Category: Inputs/Outputs within the Terraform specification pages.

Tip

See examples in specifications SNFR14 and TFFR14.

Resources

Resources are primarily leveraged by resource modules to declare the primary resource of the main resource type deployed by the AVM module.

Make sure to review all specifications covering resource properties and usage.

Tip

See examples in specifications SFR1 and RMFR1.

Outputs

Make sure to review all specifications of Category: Inputs/Outputs within the Terraform specification pages.

Tip

See examples in specification RMFR7 and TFFR2.

Interfaces

Note

This section is only relevant for contributions to resource modules.

To meet RMFR4 and RMFR5 AVM resource modules must leverage consistent interfaces for all the optional features/extension resources supported by the AVM module primary resource.

Please refer to the Terraform Interfaces page.

Telemetry

To meet the requirements of SFR3 & SFR4, we use the modtm telemetry provider. This lightweight telemetry provider sends telemetry data to Azure Application Insights via a HTTP POST front end service.

The modtm telemetry provider is included in all Terraform modules and is enabled by default through the main.telemetry.tf file being automatically distributed from the template repo. You do not need to change this configuration.

Make sure that the modtm provider is listed under the required_providers section in the module’s terraform.tf file using the following entry. This is also validated by the linter.

terraform {
  required_providers {
    # .. other required providers as needed
    modtm = {
      source = "Azure/modtm"
      version = "~> 0.3"
    }
  }
}

Eventual Consistency

When creating modules, it is important to understand that the Azure Resource Manager (ARM) API is sometimes eventually consistent.
This means that when you create a resource, it may not be available immediately.
A good example of this is data plane role assignments.
When you create such a role assignment, it may take some time for the role assignment to be available.
We can use an optional time_sleep resource to wait for the role assignment to be available before creating resources that depend on it.

# In variables.tf...
variable "wait_for_rbac_before_foo_operations" {
  type: object({
    create  = optional(string, "30s")
    destroy = optional(string, "0s")
  })
  default     = {}
  description = <<DESCRIPTION
This variable controls the amount of time to wait before performing foo operations.
It only applies when `var.role_assignments` and `var.foo` are both set.
This is useful when you are creating role assignments on the bar resource and immediately creating foo resources in it.
The default is 30 seconds for create and 0 seconds for destroy.
DESCRIPTION
}

# In main.tf...
resource "time_sleep" "wait_for_rbac_before_foo_operations" {
  count = length(var.role_assignments) > 0 && length(var.foo) > 0 ? 1 : 0
  depends_on = [
    azurerm_role_assignment.this
  ]
  create_duration  = var.wait_for_rbac_before_foo_operations.create
  destroy_duration = var.wait_for_rbac_before_foo_operations.destroy

  # This ensures that the sleep is re-created when the role assignments change.
  triggers = {
    role_assignments = jsonencode(var.role_assignments)
  }
}

resource "azurerm_foo" "this" {
  for_each = var.foo
  depends_on = [
    time_sleep.wait_for_rbac_before_foo_operations
  ]
  # ...
}

Terraform Contribution Flow

High-level contribution flow


---
config:
  nodeSpacing: 20
  rankSpacing: 20
  diagramPadding: 50
  padding: 5
  flowchart:
    wrappingWidth: 300
    padding: 5
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---

flowchart TD
  A(1 - Fork the module source repository)
    click A "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#1-fork-the-module-source-repository"
  B(2 - Setup your Azure test environment)
    click B "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#2-prepare-your-azure-test-environment"
  C(3 - Implement your contribution)
    click C "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#3-implement-your-contribution"
  D{4 - Pre-commit<br>checks successful?}
    click D "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#4-run-pre-commit-checks"
  E(5 - Create a pull request to the upstream repository)
    click E "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#5-create-a-pull-request-to-the-upstream-repository"
  A --> B
  B --> C
  C --> D
  D -->|yes|E
  D -->|no|C

GitFlow for contributors

The GitFlow process outlined here depicts and suggests a way of working with Git and GitHub. It serves to synchronize the forked repository with the original upstream repository. It is not a strict requirement to follow this process, but it is highly recommended to do so.

---

config:
  logLevel: debug
  gitGraph:
    rotateCommitLabel: false
---

gitGraph LR:
  commit id:"fork"
  branch fork/main
  checkout fork/main
  commit id:"checkout feature" type: HIGHLIGHT
  branch feature
  checkout feature
  commit id:"checkout fix"
  branch fix
  checkout main
  merge feature id: "Pull Request 'Feature'" type: HIGHLIGHT
  checkout fix
  commit id:"Patch 1"
  commit id:"Patch 2"
  checkout main
  merge fix id: "Pull Request 'Fix'" type: HIGHLIGHT

Tip

When implementing the GitFlow process as described, it is advisable to configure the local clone of your forked repository with an additional remote for the upstream repository. This will allow you to easily synchronize your locally forked repository with the upstream repository. Remember, there is a difference between the forked repository on GitHub and the clone of the forked repository on your local machine.

Note

Each time in the following sections we refer to ‘your xyz’, it is an indicator that you have to change something in your own environment.

Prepare your developer environment

1. Fork the module source repository

Important

Each Terraform AVM module will have its own GitHub repository in the Azure GitHub Organization as per SNFR19.

This repository will be created by the Module owners and the AVM Core team collaboratively, including the configuration of permissions as per SNFR9

Module contributors are expected to fork the corresponding repository and work on a branch from within their fork, before then creating a Pull Request (PR) back into the source repository’s main branch.

To do so, simply navigate to your desired repository, select the 'Fork' button to the top right of the UI, select where the fork should be created (i.e., the owning organization) and finally click ‘Create fork’.

Note

If the module repository you want to contribute to is not yet available, please get in touch with the respective module owner which can be tracked in the Terraform Resource Modules index see PrimaryModuleOwnerGHHandle column.

Optional: The usage of local source branches

For consistent contributors but also Azure-org members in general it is possible to get invited as collaborator of the module repository which enables you to work on branches instead of forks. To get invited get in touch with the module owner since it’s the module owner’s decision who gets invited as collaborator.

2. Prepare your Azure test environment

AVM performs end-to-end (e2e) test deployments of all modules in Azure for validation. We recommend you to perform a local e2e test deployment of your module before you create a PR to the upstream repository. Especially because the e2e test deployment will be triggered automatically once you create a PR to the upstream repository.

Have/create an Azure Active Directory Service Principal with at least Contributor & User Access Administrator permissions on the Management-Group/Subscription you want to test the modules in. You might find the following links useful:

Create a service principal (Azure CLI) - Recommended
Create a service principal (Azure Portal)
Create a service principal (PowerShell)
Find Service Principal object ID
Find managed Identity Service Principal
Note down the following pieces of information
Application (Client) ID
Service Principal Secret (password)
Optional: Tenant ID
Optional: Subscription ID

# Linux/MacOs
export ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) # or set <subscription_id>
export ARM_TENANT_ID=$(az account show --query tenantId --output tsv) # or set <tenant_id>
export ARM_CLIENT_ID=<client_id>
export ARM_CLIENT_SECRET=<service_principal_password>

# Windows/Powershell
$env:ARM_SUBSCRIPTION_ID = $(az account show --query id --output tsv) # or set <subscription_id>
$env:ARM_TENANT_ID = $(az account show --query tenantId --output tsv) # or set <tenant_id>
$env:ARM_CLIENT_ID = "<client_id>"
$env:ARM_CLIENT_SECRET = "<service_principal_password>"

Change to the root of your module repository and run ./avm docscheck (Linux/MacOs) / avm.bat docscheck (Windows) to verify the container image is working as expected or needs to be pulled first. You will need this later.

3. Implement your contribution

To implement your contribution, we kindly ask you to first review the Terraform specifications and composition guidelines in particular to make sure your contribution complies with the repository’s design and principles.

Tip

To get a head start on developing your module, consider using the tooling recommended per spec TFNFR37. For example you can use the newres tool to help with creating variables.tf and main.tf if you’re developing a module using Azurerm provider.

4. Run Pre-commit Checks

Important

Make sure you have Docker installed and running on your machine.

Note

To simplify and help with the execution of commands like pre-commit, pr-check, docscheck, fmt, test-example, etc. there is now a simplified avm script available distributed to all repositories via terraform-azurerm-avm-template which combines all scripts from the avm_scripts folder in the tfmod-scaffold repository using avmmakefile.

The avm script also makes sure to pull the latest mcr.microsoft.com/azterraform:latest container image before executing any command.

4.1. Run pre-commit and pr-check

The following commands will run all pre-commit checks and the pr-check.

# Running all pre-commit checks
# `pre-commit` runs depsensure fmt fumpt autofix docs
# `pr-check` runs fmtcheck tfvalidatecheck lint unit-test

## Linux/MacOs
./avm pre-commit
./avm pr-check

## Windows
avm.bat pre-commit
avm.bat pr-check

4.2 Run e2e tests

Currently you have two options to run e2e tests:

Note

With the help of the avm script and the commands ./avm test-example (Linux/MacOs) / avm.bat test-example (Windows) you will be able to run it in a more simplified way. Currently the test-example command is not completely ready yet and will be released soon. Therefore please use the below docker command for now.

Run e2e tests with the help of the azterraform docker container image.

# Linux/MacOs

docker run --rm -v $(pwd):/src -w /src -v $HOME/.azure:/root/.azure -e TF_IN_AUTOMATION -e AVM_MOD_PATH=/src -e AVM_EXAMPLE=<example_folder> -e ARM_SUBSCRIPTION_ID -e ARM_TENANT_ID -e ARM_CLIENT_ID -e ARM_CLIENT_SECRET mcr.microsoft.com/azterraform:latest make test-example

# Powershell

docker run --rm -v ${pwd}:/src -w /src -v $HOME/.azure:/root/.azure -e TF_IN_AUTOMATION -e AVM_MOD_PATH=/src -e AVM_EXAMPLE=<example_folder> -e ARM_SUBSCRIPTION_ID -e ARM_TENANT_ID -e ARM_CLIENT_ID -e ARM_CLIENT_SECRET mcr.microsoft.com/azterraform:latest make test-example

Make sure to replace <client_id> and <service_principal_password> with the values of your service principal as well as <example_folder> (e.g. default) with the name of the example folder you want to run e2e tests for.

Run e2e tests with the help of terraform init/plan/apply.
Simply run terraform init and terraform apply in the example folder you want to run e2e tests for. Make sure to set the environment variables ARM_SUBSCRIPTION_ID, ARM_TENANT_ID, ARM_CLIENT_ID and ARM_CLIENT_SECRET before you run terraform init and terraform apply or make sure you have a valid Azure CLI session and are logged in with az login.

5. Create a pull request to the upstream repository

Once you are satisfied with your contribution and validated it, submit a pull request to the upstream repository and work with the module owner to get the module reviewed by the AVM Core team, by following the initial module review process for Terraform Modules, described here. This is a prerequisite for publishing the module. Once the review process is complete and your PR is approved, merge it into the upstream repository and the Module owner will publish the module to the HashiCorp Terraform Registry.

5.1 Create the Pull Request [Contributor]

These steps are performed by the contributor:

Navigate to the upstream repository and click on the Pull requests tab.
Click on the New pull request button.
Ensure the base repository is set to the upstream AVM repo.
Ensure the base branch is set to main.
Ensure your head repository and compare branch are set to your fork and the branch you are working on.
Click on the Create pull request button.

5.2 Review the Pull Request [Owner]

IMPORTANT: The module owner must first check for any malicious code or changes to workflow files. If they are found, the owner should close the PR and report the contributor.
Review the changes made by the contributor and determine whether end to end tests need to be run.
If end to end tests do not need to be run (e.g. doc changes, small changes, etc) then so long as the static analysis passes, the PR can be merged to main.
If end to end tests do need to be run, then follow the steps in 5.3.

5.3 Release Branch and Run End to End Tests [Owner]

IMPORTANT: The module owner must first check for any malicious code or changes to workflow files. If they are found, the owner should close the PR and report the contributor.
Create a release branch from main. Suggested naminmg convention is release/<description-of-change>.
Open the PR created by the contributor and click Edit at the top right of the PR.
Change the base branch to the release branch you just created.
Wait for the PR checks to run, validate the code looks good and then merge the PR into the release branch.
Create a new PR from the release branch to the main branch of the AVM module.
The end to end tests should trigger and you can approve the run.
Once the end to end tests have passed, merge the PR into the main branch.
If the end to end tests fail, investigate the failure. You have two options:
1. Work with the contributor to resolve the issue and ask them to submit a new PR from their fork branch to the release branch.
  1. Re-run the tests and merge to main. Repeat the loop as required.
2. If the issue is a simple fix, resolve it directly in the release branch, re-run the tests and merge to main.

Common mistakes to avoid and recommendations to follow

If you contribute to a new module then search and update TODOs (which are coming with the terraform-azurerm-avm-template) within the code and remove the TODO comments once complete
terraform.lock.hcl shouldn’t be in the repository as per the .gitignore file
Update the support.md file
\_header.md needs to be updated
support.md needs to be updated
Exclude terraform.tfvars file from the repository

Terraform Owner Contribution Flow

This section describes the contribution flow for module owners who are responsible for creating and maintaining Terraform Module repositories.

Important

This contribution flow is for Module owners only.

As a Terraform Module Owner you need to be aware of the AVM contribution process overview & Terraform specifications (including Interfaces) as as these need to be considered during pull request reviews for the modules you own.

Info

Make sure module authors/contributors tested their module in their environment before raising a PR. The PR uses e2e checks with 1ES agents in the 1ES subscriptions. At the moment their is no read access to the 1ES subscription. Also if more than two subscriptions are required for testing, that’s currently not supported.

1. Owner Activities and Responsibilities

Familiarise yourself with the responsibilities as Module Owner outlined in Team Definitions & RACI and in the TF Issue Triage.

Watch Pull Request (PR) and issue (questions/feedback) activity for your module(s) in your repository and ensure that PRs are reviewed and merged in a timely manner as outlined in SNFR11.

Info

Make sure module authors/contributors tested their module in their environment before raising a PR. Also because once a PR is raised a e2e GitHib workflow pipeline is required to be run successfully before the PR can be merged. This is to ensure that the module is working as expected and is compliant with the AVM specifications.

2. GitHub repository creation and configuration

Once your module has been approved and you are ready to start development, you need to request that a new repository be created for your module.

You do that by adding a comment to the issue with the #RFRC tag. The Status: Ready For Repository Creation 📝 label will then be applied. This will trigger the creation of the repository and the configuration of the repository with the required settings.

Info

If you need your repository to be created urgently, please message the AVM Core team in the AVM Teams channel.

Once your module is ready for development, the Status: Repository Created 📄 label will be added to the issue and you’ll be notified it is ready.

3. Module Development Activities

You can now start developing your module, following standard guidance for Terraform module development.

Some useful things to know:

Pull Request

You can raise a pull request anytime, don’t wait until the end of the development cycle. Raise the PR after you first push your branch.

You can then use the PR to run end to end tests, check linting, etc.

Once readdy for review, you can request a review per step 4.

Grept

Grept is a linting tool for repositories, ensures predefined standards, maintains codebase consistency, and quality.
It’s using the grept configuration files from the Azure-Verified-Modules-Grept repository.

You can see here which files are synced from the terraform-azurerm-avm-template repository.

Set environment variables and run Grept:

export GITHUB_REPOSITORY_OWNER=Azure
export GITHUB_REPOSITORY=Azure/terraform-azurerm-avm-res-<RP>-<modulename>"

./avm grept-apply

$env:GITHUB_REPOSITORY_OWNER="Azure"
$env:GITHUB_REPOSITORY="Azure/terraform-azurerm-avm-res-<RP>-<modulename>"

./avm grept-apply

Custom Variables and Secrets for end to end tests

The respoitory has an environment called test, it has have approvals and secrets applied to it ready to run end to end tests.

In the unusual cicumstance that you need to use your own tenant and subscription for end to end tests, you can override the secrets by setting ARM_TENANT_ID_OVERRIDE, ARM_SUBSCRIPTION_ID_OVERRIDE, and ARM_CLIENT_ID_OVERRIDE secrets.
If you need to supply additional secrets or variables for your end to end tests, you can add them to the test environment. They must be prefixed with TF_VAR_, otherwise they will be ignored.

4. Review the module

Once the development of the module has been completed, get the module reviewed from the AVM Core team by following the AVM Review of Terraform Modules process here which is a pre-requisite for the next step.

5. Publish the module

Once a module has been reviewed and the PR is merged to main. Follow the below steps to publish the module to the HashiCorp Registry.

Ensure your module is ready for publishing:

Create a release with a new tag (e.g. 0.1.0) via Github UI.
- Go to the releases tab and click on Draft a new release.
- Ensure that the Target is set to the main branch.
- Select Choose a tag and type in a new tag, such as 0.1.0 Make sure to create the tag from the main branch.
- Generate the release notes using the Generate release notes button.
- If this is a community contribution be sure to update the ‘Release Notes` to provide appropriate credit to the contributors.
Elevate your respository access using the Open Source Management Portal.
Sign in to the HashiCorp Registry using GitHub.
Publish a module by selecting the Publish button in the top right corner, then Module
Select the repository and accept the terms.

Info

Once a module gets updated and becomes a new version/release it will be automatically published with the latest published release version to the HashiCorp Registry.

Important

When an AVM Module is published to the HashiCorp Registry, it MUST follow the below requirements:

Resource Module: terraform-<provider>-avm-res-<rp>-<ARM resource type> as per RMNFR1
Pattern Module: terraform-<provider>-avm-ptn-<patternmodulename> as per PMNFR1

Terraform Core Team Repository Creation Process

This section describes the process for AVM core team members who are responsible for creating Terraform Module repositories.

Important

This contribution flow is for AVM Core Team members only.

1. Find Issues Ready for Repository Creation

When a module owner is ready to start development, they will add the Status: Ready For Repository Creation 📝 label to the proposal via a comment issue.
To find issues that are ready for repository creation, click this link
Open one of the issues to find the details you need.
1. Module name: This will be in the format avm-<type>-<name>. e.g. avm-res-network-virtualnetwork
2. Module owner GitHub handle: This will be in the content of the issue
3. Module owner display name: You may need to look this up in the open source portal
4. Module description: If this does not exist, then create one. The description will automtically be prefixed with Terraform Azure Verified <module-type> Module for ..., where <module-type> is either Resource, Pattern, or Utility
5. Resource provider namespace: You may need to look this up if not included in the issue
6. Resource type: You may need to look this up if not included in the issue
7. Module alternative names: Consider if it would be useful to search for this module using other names. If so, add them here. This is a comma separated list of names
8. Module comments: Any comments you want to add to the module index CSV file
9. Owner secondary GitHub handle: This is optional. If the module owner has a secondary GitHub handle
10. Owner secondary display name: This is optional. If the module owner has a secondary display name

2. Create the repository

Open a PowerShell terminal
Clone the https://github.com/Azure/avm-terraform-governance repository and navigate to the tf-repo-mgmt folder
```
git clone "https://github.com/Azure/avm-terraform-governance"
cd ./tf-repo-mgmt
```
Install the GitHub CLI if you don’t already have it installed: https://cli.github.com

gh auth login -h "github.com" -w -p "https" -s "delete_repo" -s "workflow" -s "read:user" -s "user:email"

Follow the prompts to login to your GitHub account.

Run the following command, replacing the values with the details you collected in step 1

# Required Inputs
$moduleProvider = "azurerm" # Only change this if you know why you need to change it (Allowed values: azurerm, azapi, azure)
$moduleName = "<module name>" # Replace with the module name (do not include the "terraform-azurerm" prefix)
$moduleDisplayName = "<module description>" # Replace with a short description of the module
$resourceProviderNamespace = "<resource provider namespace>" # Replace with the resource provider namespace of the module (NOTE: Leave empty for Pattern or Utility Modules)
$resourceType = "<resource type>" # Replace with the resource type of the module (NOTE: Leave empty for Pattern or Utility Modules)
$ownerPrimaryGitHubHandle = "<github user handle>" # Replace with the GitHub handle of the module owner
$ownerPrimaryDisplayName = "<user display name>" # Replace with the display name of the module owner

# Optional Metadata Inputs
$moduleAlternativeNames = "<alternative names>" # Replace with a comma separated list of alternative names for the module
$ownerSecondaryGitHubHandle = "<github user handle>" # Replace with the GitHub handle of the module owner
$ownerSecondaryDisplayName = "<user display name>" # Replace with the display name of the module owner

./New-Repository.ps1 `
    -moduleProvider $moduleProvider `
    -moduleName $moduleName `
    -moduleDisplayName $moduleDisplayName `
    -resourceProviderNamespace $resourceProviderNamespace `
    -resourceType $resourceType `
    -ownerPrimaryGitHubHandle $ownerPrimaryGitHubHandle `
    -ownerPrimaryDisplayName $ownerPrimaryDisplayName `
    -moduleAlternativeNames $moduleAlternativeNames `
    -ownerSecondaryGitHubHandle $ownerSecondaryGitHubHandle `
    -ownerSecondaryDisplayName $ownerSecondaryDisplayName

For example:

# Required Inputs
$moduleProvider = "azurerm" # Only change this if you know why you need to change it (Allowed values: azurerm, azapi, azure)
$moduleName = "avm-res-network-virtualnetwork" # Replace with the module name (do not include the "terraform-azurerm" prefix)
$moduleDisplayName = "Virtual Networks" # Replace with a short description of the module
$resourceProviderNamespace = "Microsoft.Network" # Replace with the resource provider namespace of the module (NOTE: Leave empty for Pattern or Utility Modules)
$resourceType = "virtualNetworks" # Replace with the resource type of the module (NOTE: Leave empty for Pattern or Utility Modules)
$ownerPrimaryGitHubHandle = "jaredfholgate" # Replace with the GitHub handle of the module owner
$ownerPrimaryDisplayName = "Jared Holgate" # Replace with the display name of the module owner

# Optional Metadata Inputs
$moduleAlternativeNames = "VNet" # Replace with a comma separated list of alternative names for the module
$ownerSecondaryGitHubHandle = "" # Replace with the GitHub handle of the module owner
$ownerSecondaryDisplayName = "" # Replace with the display name of the module owner

./New-Repository.ps1 `
    -moduleProvider $moduleProvider `
    -moduleName $moduleName `
    -moduleDisplayName $moduleDisplayName `
    -resourceProviderNamespace $resourceProviderNamespace `
    -resourceType $resourceType `
    -ownerPrimaryGitHubHandle $ownerPrimaryGitHubHandle `
    -ownerPrimaryDisplayName $ownerPrimaryDisplayName `
    -moduleAlternativeNames $moduleAlternativeNames `
    -ownerSecondaryGitHubHandle $ownerSecondaryGitHubHandle `
    -ownerSecondaryDisplayName $ownerSecondaryDisplayName

The script will stop and prompt you to fill out the Microsoft Open Source details.
Open the Open Source Portal using the link in the script output.

Click Complete Setup, then use the following table to provide the settings:

Question	Answer
Classify the repository	Production
Assign a Service tree or Opt-out	Azure Verified Modules / AVM
Direct owners	Add the module owner and yourself as direct owners. Add the avm-team-module-owners as security group.
Is this going to ship as a public open source licensed project	Yes, creating an open source licensed project
What type of open source will this be	Sample code
What license will you be releasing with	MIT
Did your team write all the code and create all of the assets you are releasing?	Yes, all created by my team
Does this project send any data or telemetry back to Microsoft?	Yes, telemetry
Does this project implement cryptography	No
Project name	Azure Verified Module (Terraform) for ‘module name’
Project version	1
Project description	Azure Verified Module (Terraform) for ‘module name’. Part of AVM project - https://aka.ms/avm
Business goals	Create IaC module that will accelerate deployment on Azure using Microsoft best practice.
Will this be used in a Microsoft product or service?	This is open source project and can be leveraged in Microsoft service and product.
Adopt security best practice?	Yes, use just-in-time elevation
Maintainer permissions	Leave empty
Write permissions	Leave empty
Repository template	Uncheck
Add .gitignore	Uncheck

Click Finish setup + start business review to complete the setup
Wait for it to process and then click View repository
If you don’t see the Elevate your access button, then refresh the browser window
Click Elevate your access and follow the prompts to elevate your access
Now head back over to the terminal and type yes and hit enter to complete the repository configuration
Open the new repository in GitHub.com and verify it all looks good.
1. On the home page
  1. The name is correct
  2. The description is correct
  3. The Terraform registry url looks good
  4. The repository has the template files in it
2. In Setting
  1. The repository is public
  2. The Collaborators and teams are correct

3. Request the GitHub App Install

Create a new issue at https://github.com/microsoft/github-operations/issues/new?template=GitHub-App-Installation-Request.md

Update the issue with the following details:

Title: [GitHub App] Installation Request - Azure Verified Modules

Body - replace <repository url> with the URL of the repository you created in step 2:

> __Note:__ If the app is listed on the [Auto-Approved list](https://docs.opensource.microsoft.com/github/apps/approvals/), you do not need to complete this form.

You complete these steps:

- [x] Confirm the app is not in the [Auto-Approved list](https://docs.opensource.microsoft.com/github/apps/approvals/)
- [x] Fill out and verify the information in this form
- [x] Update the title to reflect the org/repo and/or app name
- [x] Submit the native request within the GitHub user interface

Operations will help complete these steps:

- [ ] Approve the app if already requested on GitHub natively
- [ ] Close this issue

Finally, you'll complete any configuration with the app or your repo that is required once approved.

# My request

- GitHub App name: Azure Verified Modules

- GitHub organization in which the app would be installed: Azure

- Is this an app created by you and/or your team?

  - [x] Yes, this is an app created by me and/or my team
  - [ ] No, this is a Microsoft 1st-party app created by another team
  - [ ] No, this is a 3rd-party marketplace app

- If this __is an app created by you and/or your team__, please provide some ownership information in case future questions come up:

  - Service Tree ID: our service tree ID is: Unchanged
  - A few specific individuals at Microsoft if we have questions (corporate email list):Unchanged
  - An optional team discussion list: Unchanged

- Is this an app you/your team created to address [reduced PAT lifetimes](https://aka.ms/opensource/tsg/pat)?
  - [x] Yes
  - [ ] No

- Are you looking for this app to be installed on individual repos or all repos in an organization?

  - [x] Individual repos: <repository url>
  - [ ] All repos in an organization

- Does this app have any side-effects if it is installed into all repos in an organization? Side effects can include creating labels, issues, pull requests, automatic checks on PRs, etc.

  - [ ] Yes, it has side effects and you should be careful if installing to all repos in an org
  - [x] No side effects

- Please provide a description of the app's functionality and what are you trying to accomplish by utilizing this app:

  Unchanged

- For any major permissions (org admin, repo admin, etc.), can you explain what they are and why they are needed?

  Unchanged

- Any other notes or information can you provide about the app?

Submit the issue

4. Notify the Module Owner and Update the Issue Status

Add a comment to the issue you found in step 1 to let the module owner know that the repository has been created and is be ready for them to start development.

@<module owner> The module repository has now been created. You can find it at <repository url>.

The final step of repository configuration is still in progress, but you will be able to start developing your code immediately.

The final step is to create the environment and credentials require to run the end to end tests. If the environment called `test` is not available in 48 hours, please let me know.

Thanks

Add the Status: Repository Created 📄 label to the issue
Remove the Status: Ready For Repository Creation 📝 label from the issue

5. Merge the Pull Request for the metadata CSV file

Open the pull request for the metadata CSV file shown in the script output look here if you lost the link
Review the changes to ensure they are correct and only adding 1 new line for the module you just created
If everything looks good, merge the pull request

6. Wait for the GitHub App to be installed

Once the GitHub App has been installed, the sync to create the environment and credentials will be triggered automatically at 15:30 UTC on week days. However, you can also trigger it manually by running the following command in the tf-repo-mgmt folder:

$moduleName = "avm-res-network-virtualnetwork" # Replace with the module name (do not include the "terraform-azurerm" prefix)

./scripts/Invoke-WorkflowDispatch.ps1 `
  -inputs @{
    repositories = "$moduleName"
    plan_only = $false
  }

Terraform Contribution Prerequisites

GitHub Account Link and Access

To contribute to this project, you need to have a GitHub account which is linked to your Microsoft corporate identity account and be a member of the Azure organization.

Tooling

Required Tooling

Tip

We recommend to use Linux or MacOS for your development environment. You can use Windows Subsystem for Linux (WSL) if you are using Windows.

To contribute to this project the following tooling is required:

Git

If just installed, don’t forget to set both your git username & password

git config --global user.name "John Doe"
git config --global user.email "johndoe@example.com"

Terraform
Azure CLI
Visual Studio Code
- Terraform extension for Visual Studio Code
- EditorConfig for VS Code
Docker
- Azure Verified Terraform Scaffold (mcr.microsoft.com/azterraform:latest)

Recommended Tooling

The following tooling/extensions are recommended to assist you developing for the project:

Go (for writing tests)
tfenv - useful when working on multiple modules that use different Terraform versions from the same machine

Visual Studio Code Extensions

Go extension for Visual Studio Code
For visibility of Bracket Pairs:
- Inside Visual Studio Code, add editor.bracketPairColorization.enabled: true to your settings.json, to enable bracket pair colorization.

Review of Terraform Modules

The AVM module review is a critical step before an AVM Terraform module gets published to the Terraform Registry and made publicly available for customers, partners and wider community to consume and contribute to. It serves as a quality assurance step to ensure that the AVM Terraform module complies with the Terraform specifications of AVM. The below process outlines the steps that both the module owner and module reviewer need to follow.

The module owner completes the development of the module in their branch or fork.
The module owner submits a pull request (PR) titled AVM-Review-PR and ensures that all checks are passing on that PR as that is a pre-requisite to request a review.
The module owner assigns the avm-core-team-technical-terraform GitHub team as reviewer on the PR.

The module owner leaves the following comment as it is on the module proposal in the AVM - Module Triage project by searching for their module proposal by name there.

➕ AVM Terraform Module Review Request

I have completed my initial development of the module and I would like to request a review of my module before publishing it to the Terraform Registry. The latest code is in a PR titled [AVM-Review-PR](REPLACE WITH URL TO YOUR PR) on the module repo and all checks on that PR are passing.

The AVM team moves the module proposal from “In Development” to “In Review” in the AVM - Module Triage project.

The AVM team will assign a module reviewer who will open a blank issue on the module titled “AVM-Review” and populate it with the below mark down. This template already marks the specs as compliant which are covered by the checks that run on the PR. There are some specs which don’t need to be checked at the time of publishing the module therefore they are marked as NA.

➕ AVM Terraform Module Review Issue

Dear module owner,

As per the module ownership requirements and responsibilities at the time of [assignment](REPLACE WITH THE LINK TO THE AVM MODULE PROPOSAL), the AVM Team is opening this issue, requesting you to validate your module against the below AVM specifications and confirm its compliance.

Please don’t close this issue and merge your AVM-Review-PR until advised to do so. This review is a prerequisite for publishing your module’s v0.1.0 in the Terraform Registry. The AVM team is happy to assist with any questions you might have.

Requested Actions

Complete the below task list by ticking off the tasks.
Complete the below table by updating the Compliant column with Yes, No or NA as possible values.

Please use the comments columns to provide additional details especially if the Compliant column is updated to No or NA.

Tasks

Address comments on AVM-Review-PR if any
Ensure that all checks on AVM-Review-PR are passing
Make sure you have run grept and pre-commit and pr-check.
Tick this to acknowledge specs with comment “Module Owner to action this spec post-publish as appropriate” in the table below.
Please update the _header.md file as it contains instructions which - once actioned - need to be replaced with Module Name and Description.

ID	Spec	Compliant	Comments
1	ID: SFR1 - Category: Composition - Preview Services		NA if no preview services are used
2	ID: SFR2 - Category: Composition - WAF Aligned		Ensure only high priority reliability & security recommendations are implemented if any
3	ID: SFR3 - Category: Telemetry - Deployment/Usage Telemetry
4	ID: SFR4 - Category: Telemetry - Telemetry Enablement Flexibility	Yes	Yes if AVM Template Repo has been used
5	ID: SFR5 - Category: Composition - Availability Zones
6	ID: SFR6 - Category: Composition - Data Redundancy
7	ID: SNFR25 - Category: Composition - Resource Naming
8	ID: SNFR1 - Category: Testing - Prescribed Tests	Yes	Yes if all e2e test, version-check & linting checks passed
9	ID: SNFR2 - Category: Testing - E2E Testing	Yes	Yes if e2e tests passed
10	ID: SNFR3 - Category: Testing - AVM Compliance Tests	Yes	Yes if all e2e test, version-check & linting checks passed
11	ID: SNFR4 - Category: Testing - Unit Tests		NA if no tests created in tests folder
12	ID: SNFR5 - Category: Testing - Upgrade Tests	NA	Module Owner to action this spec post-publish as appropriate
13	ID: SNFR6 - Category: Testing - Static Analysis/Linting Tests	Yes	Yes if all linting checks passed
14	ID: SNFR7 - Category: Testing - Idempotency Tests	Yes	Yes if e2e tests passed
15	ID: SNFR24 - Category: Testing - Testing Child, Extension & Interface Resources	Yes	Yes if e2e tests passed
16	ID: SNFR8 - Category: Contribution/Support - Module Owner(s) GitHub
17	ID: SNFR20 - Category: Contribution/Support - GitHub Teams Only
18	ID: SNFR9 - Category: Contribution/Support - AVM & PG Teams GitHub Repo Permissions
19	ID: SNFR10 - Category: Contribution/Support - MIT Licensing	Yes	Yes if AVM Template Repo has been used
20	ID: SNFR11 - Category: Contribution/Support - Issues Response Times	NA	Module Owner to action this spec post-publish as appropriate
21	ID: SNFR12 - Category: Contribution/Support - Versions Supported	NA	Module Owner to action this spec post-publish as appropriate
22	ID: SNFR23 - Category: Contribution/Support - GitHub Repo Labels
23	ID: SNFR14 - Category: Inputs - Data Types
24	ID: SNFR22 - Category: Inputs - Parameters/Variables for Resource IDs
25	ID: SNFR15 - Category: Documentation - Automatic Documentation Generation	Yes	Yes if linting / docs check passed
26	ID: SNFR16 - Category: Documentation - Examples/E2E	Yes	Yes if e2e tests passed
27	ID: SNFR17 - Category: Release - Semantic Versioning	Yes	Yes if version-check check passed
28	ID: SNFR18 - Category: Release - Breaking Changes	NA	Module Owner to action this spec post-publish as appropriate
29	ID: SNFR19 - Category: Publishing - Registries Targeted	NA	Module Owner to action this spec post-publish as appropriate
30	ID: SNFR21 - Category: Publishing - Cross Language Collaboration	NA	Module Owner to action this spec post-publish as appropriate
31	ID: RMFR1 - Category: Composition - Single Resource Only
32	ID: RMFR2 - Category: Composition - No Resource Wrapper Modules
33	ID: RMFR3 - Category: Composition - Resource Groups
34	ID: RMFR4 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add	Yes	Yes if linting / terraform check passed
35	ID: RMFR5 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add Interfaces/Schemas	Yes	Yes if linting / terraform check passed
36	ID: RMFR8 - Category: Composition - Dependency on child and other resources
37	ID: RMFR6 - Category: Inputs - Parameter/Variable Naming
38	ID: RMFR7 - Category: Outputs - Minimum Required Outputs	Yes	Yes if linting / terraform check passed
39	ID: RMNFR1 - Category: Naming - Module Naming
40	ID: RMNFR2 - Category: Inputs - Parameter/Variable Naming
41	ID: RMNFR3 - Category: Composition - RP Collaboration	NA	Module Owner to action this spec post-publish as appropriate
42	ID: PMFR1 - Category: Composition - Resource Group Creation		NA if this is not a pattern module
43	ID: PMNFR1 - Category: Naming - Module Naming		NA if this is not a pattern module
44	ID: PMNFR2 - Category: Composition - Use Resource Modules to Build a Pattern Module		NA if this is not a pattern module
45	ID: PMNFR3 - Category: Composition - Use other Pattern Modules to Build a Pattern Module		NA if this is not a pattern module
46	ID: PMNFR4 - Category: Hygiene - Missing Resource Module(s)		NA if this is not a pattern module
47	ID: PMNFR5 - Category: Inputs - Parameter/Variable Naming		NA if this is not a pattern module
48	ID: TFFR1 - Category: Composition - Cross-Referencing Modules
49	ID: TFFR2 - Category: Outputs - Additional Terraform Outputs	Yes	Yes if linting / terraform check passed
50	ID: TFNFR1 - Category: Documentation - Descriptions
51	ID: TFNFR2 - Category: Documentation - Module Documentation Generation	Yes	Yes if linting / docs check passed
52	ID: TFNFR3 - Category: Contribution/Support - GitHub Repo Branch Protection	Yes	Yes if AVM Template Repo has been used
53	ID: TFNFR4 - Category: Composition - Code Styling - lower snake_casing	Yes	Yes if linting / terraform check passed
54	ID: TFNFR5 - Category: Testing - Test Tooling	Yes	Yes if linting / terraform check passed
55	ID: TFNFR6 - Category: Code Style - Resource & Data Order
56	ID: TFNFR7 - Category: Code Style - count & for_each Use
57	ID: TFNFR8 - Category: Code Style - Resource & Data Block Orders	Yes	Yes if linting / avmfix check passed
58	ID: TFNFR9 - Category: Code Style - Module Block Order
59	ID: TFNFR10 - Category: Code Style - No Double Quotes in ignore_changes
60	ID: TFNFR11 - Category: Code Style - Null Comparison Toggle
61	ID: TFNFR12 - Category: Code Style - Dynamic for Optional Nested Objects
62	ID: TFNFR13 - Category: Code Style - Default Values with coalesce/try
63	ID: TFNFR14 - Category: Inputs - Not allowed variables
64	ID: TFNFR15 - Category: Code Style - Variable Definition Order	Yes	Yes if linting / avmfix check passed
65	ID: TFNFR16 - Category: Code Style - Variable Naming Rules	Yes	Yes if linting / terraform check passed
66	ID: TFNFR17 - Category: Code Style - Variables with Descriptions	Yes	Yes if linting / terraform check passed
67	ID: TFNFR18 - Category: Code Style - Variables with Types	Yes	Yes if linting / terraform check passed
68	ID: TFNFR19 - Category: Code Style - Sensitive Data Variables
69	ID: TFNFR20 - Category: Code Style - Non-Nullable Defaults for collection values
70	ID: TFNFR21 - Category: Code Style - Discourage Nullability by Default	Yes	Yes if linting / avmfix check passed
71	ID: TFNFR22 - Category: Code Style - Avoid sensitive = false	Yes	Yes if linting / avmfix check passed
72	ID: TFNFR23 - Category: Code Style - Sensitive Default Value Conditions	Yes	Yes if linting / terraform check passed
73	ID: TFNFR24 - Category: Code Style - Handling Deprecated Variables	NA	Module Owner to action this spec post-publish as appropriate
74	ID: TFNFR25 - Category: Code Style - Verified Modules Requirements	Yes	Yes if linting / terraform check passed
75	ID: TFNFR26 - Category: Code Style - Providers in required_providers	Yes	Yes if linting / terraform check passed
76	ID: TFNFR27 - Category: Code Style - Provider Declarations in Modules	Yes	Yes if linting / terraform check passed
77	ID: TFNFR29 - Category: Code Style - Sensitive Data Outputs	Yes	Yes if linting / avmfix check passed
78	ID: TFNFR30 - Category: Code Style - Handling Deprecated Outputs	NA	Module Owner to action this spec post-publish as appropriate
79	ID: TFNFR31 - Category: Code Style - locals.tf for Locals Only
80	ID: TFNFR32 - Category: Code Style - Alphabetical Local Arrangement	Yes	Yes if linting / avmfix check passed
81	ID: TFNFR33 - Category: Code Style - Precise Local Types
82	ID: TFNFR34 - Category: Code Style - Using Feature Toggles	NA	Module Owner to action this spec post-publish as appropriate
83	ID: TFNFR35 - Category: Code Style - Reviewing Potential Breaking Changes	NA	Module Owner to action this spec post-publish as appropriate
84	ID: TFNFR36 - Category: Code Style - Setting prevent_deletion_if_contains_resources
85	ID: TFNFR37 - Category: Code Style - Tool Usage by Module Owner

The module reviewer can update the Compliance column for specs in line 42 to 47 to NA, in case the module being reviewed isn’t a pattern module.
The module reviewer reviews the code in the PR and leaves comments to request any necessary updates.
The module reviewer assigns the AVM-Review issue to the module owner and links the AVM-Review Issue to the AVM-Review-PR so that once the module reviewer approves the PR and the module owner merges the AVM-Review-PR, the AMV-Review issue is automatically closed. The module reviews responds to the module owner’s comment on the Module Proposal in AVM Repo with the following
➕ AVM Terraform Module Review Initiation Message
```
Thank you for requesting a review of your module. The AVM module review process has been initiated, please perform the **Requested Actions** on the AVM-Review issue on the module repo.
```
The module owner updates the check list and the table in the AVM-Review issue and notifies the module reviewer in a comment.
The module reviewer performs the final review and ensures that all checks in the checklist are complete and the specifications table has been updated with no requirements having compliance as ‘No’.

The module reviewer approves the AVM-Review-PR, and leaves the following comment on the AVM-Review issue with the following comment.

➕ AVM Terraform Module Review Completion Message

Thank you for contributing this module and completing the review process per AVM specs. The AVM-Review-PR has been approved and once you merge it that will close this AVM-Review issue. You may proceed with [publishing](/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/owner-contribution-flow/#7-publish-the-module) this module to the HashiCorp Terraform Registry with an initial pre-release version of v0.1.0. Please keep future versions also pre-release i.e. < 1.0.0 until AVM becomes generally available (GA) of which the AVM team will notify you.

**Requested Action**: Once published please update your [module proposal](REPLACE WITH THE LINK TO THE MODULE PROPOSAL) with the following comment.

"The initial review of this module is complete, and the module has been published to the registry. Requesting AVM team to close this module proposal and mark the module available in the module index.
Terraform Registry Link: <REPLACE WITH THE LINK OF THE MODULE IN TERRAFORM REGISTRY>
GitHub Repo Link: <REPLACE WITH THE LINK OF THE MODULE IN GITHUB>"

Once the module owner perform the requested action in the previous step, the module reviewer updates the module proposal by performing the following steps:

Assign label Status: Module Available :green_circle: to the module proposal.
Update the module index excel file and CSV file by creating a PR to update the module index and links the module proposal as an issue that gets closed once the PR is merged which will move the module proposal from “In Review” to “Done” in the AVM - Module Triage project.

Terraform Module Testing

When you author your Azure Verified Module (AVM) Terraform module, you should ensure that it is well tested.
This document outlines the testing framework and tools that are used to test AVM Terraform modules.

Testing Framework Composition

For Terraform modules, we use the following tools:

Mandatory tooling:

avmfix for advanced formatting
Conftest, and Open Policy Agent (OPA) for well architected compliance
grept (Go REPository linTer) for repository contents
terraform-docs for documentation generation
TFLint for spec compliance

Optional tooling:

terraform test for unit testing

Before Submitting a Pull Request

Before you submit a pull request to your module, you should ensure that the following checks are passed.
You can run the linting tools locally by running the following command:

Prerequisites

You need to have the following tools installed:

A container runtime - you can use Docker Desktop or Podman

Linux / MacOS / WSL

./avm pre-commit
./avm pr-check

Windows

.\avm.bat pre-commit
.\avm.bat pr-check

Doing so will shorten the development cycle and ensure that your module is compliant with the AVM specifications.

GitHub Actions and Pull Requests

We centrally manage the test workflows for your Terraform modules.
We also provide a test environment (Azure Subscription) as part of the testing framework.

Linting

The linting.yml workflow in your repo (.github/workflows/linting.yml) is responsible for static analysis of your module.
It will run the following centralized tests:

avmfix to ensure that your module is formatted correctly.
terraform-docs to ensure that your module documentation is up to date.
TFLint to ensure that your module is compliant with the AVM specifications.

End-to-end testing

The e2e.yml workflow in your repo (.github/workflows/e2e.yml) is responsible for end-to-end testing of your module examples.
It will run the following centralized test workflow: https://github.com/Azure/terraform-azurerm-avm-template/blob/main/.github/workflows/test-examples-template.yml.

It will run the following tasks:

List all the module examples in the examples directory.
Conftest will check the plan for compliance with the well-architected framework using OPA.
Your example will be tested for idempotency by running terraform apply and then terraform plan again.
Your example will be destroyed by running terraform destroy.

Currently it is not possible to run the end-to-end tests locally, however you can run terraform apply and terraform destroy commands locally to test your module examples.

OPA (Open Policy Agent) & Conftest

Conftest is the first step in the AVM end-to-end testing framework.
It will check the plan for compliance with the well-architected framework using OPA.
The policies that we use are available here: https://github.com/Azure/policy-library-avm.

If you get failures, you should examine them to understand how you can make your example compliant with the well-architected framework.

Creating exceptions

In some circumstances, you may need to create an exception for a policy, you can do so by creating a .rego file in the exceptions sub-directory of your example.
For example, to exclude the rule called "configure_aks_default_node_pool_zones", create a file called exceptions/exception.rego in your example, with the following content:

package Azure_Proactive_Resiliency_Library_v2
import rego.v1
exception contains rules if {
  rules = ["configure_aks_default_node_pool_zones"]
}

TFLint

TFLint is used to check that your module is compliant with the AVM specifications.
We use a custom ruleset for TFLint to check for AVM compliance: https://github.com/Azure/tflint-ruleset-avm.

Excluding rules

If you need to exclude a rule from TFLint, you can do so by creating one of the following in the root of your module:

avm.tflint.override.hcl - to override the rules for the root module
avm.tflint.override_module.hcl - to override the rules for submodules
avm.tflint.override_example.hcl - to override the rules for examples

These files are HCL files that contain the rules that you want to override.
Here is some example syntax:

# Disable the required resource id output rule as this is a pattern module and it does not make sense here.
rule "required_output_rmfr7" {
  enabled = false
}

Please include a comment in the file explaining why you are disabling the rule.

Excluding examples from end-to-end testing

If you have examples that you do not want to be tested, you can exclude them by creating a file called .e2eignore in the example directory.
The contents of the file should explain why the example is excluded from testing.

Global test setup and teardown

Some modules require a global setup and teardown to be run before and after ALL examples.
We provide a way to do this by creating a file called examples/setup.sh in the root of your module.
This script will be run before all examples are tested, and will be authorized with the same credentials as the examples.

You can optionally supply a teardown script that will be run after all examples are tested.
This should be called examples/teardown.sh.

Pre and post scripts per-example

Some examples require pre and post commands that are specific to that example.
Use cases here can be to modify the example files to ensure unique names or to run some commands before or after the example is tested.

You can do this by creating a file called examples/example_name/pre.sh in the example directory.
This script will be run before the example is tested, and will be authorized with the same credentials as the example.
You can optionally supply a post script that will be run after the example is tested.
This should be called examples/example_name/post.sh.

The pre and post scripts are run in the context of the example directory, so you can use relative paths to access files.

Grept and the `chore: repository governance` pull requests

We run a weekly workflow that checks the contents of your module and creates a pull request if it finds any issues.
If you see a pull request with the title chore: repository governance, it means that the workflow has found some issues with your module, so please check the pull request and merge it to ensure you are compliant.

You do not need to release a new version of your module when you merge these pull requests, as they do not change the module code.

Overriding the default test subscription (using a different Azure environment)

If your module deploys resource that are not compatible with the default test subscription, you can override these defaults by setting additional environment secrets in your GitHub repository.

You might need to do this if:

The resources you are deploying are constrained by quota or subscription limits.
You need to deploy resources at scopes higher than subscription level (e.g. management group or tenant).

To override the Azure environment, you can specify the environment in your module’s configuration or set the following environment variables in your GitHub repository settings:

Create a user-assigned managed identity in the Azure environment you want to use.
Create GitHub federated credentials for the user-assigned managed identity in the Azure environment you want to use, using the github organization and repository of your module. Select entity type ’environment’ and add test for the name.
Create appropriate role assignments for the user-assigned managed identity in the Azure environment you want to use.
Now, elevate you access to administrator by going to the open source portal: https://repos.opensource.microsoft.com/orgs/Azure/repos/REPOSITORY-NAME/jit.
Then, go to the settings of your GitHub repository and select environments.
Select the test environment.
Add the following secrets:
- ARM_CLIENT_ID_OVERRIDE - The client ID of the user-assigned managed identity.
- ARM_TENANT_ID_OVERRIDE - The tenant ID of the user-assigned managed identity.
- ARM_SUBSCRIPTION_ID_OVERRIDE - The subscription ID you want to use for the tests.

Terraform Test (Optional)

Authors may choose to use terraform test to run unit and integration tests on their modules.

Unit tests

Test files should be placed in the tests/unit directory.
They can be run using the following command:

./avm unit-test

Authors SHOULD use unit tests with mocked providers.
This ensures that the tests are fast and do not require any external dependencies.

Integration tests

Integration tests should be placed in the tests/integration directory.
They can be run using the following command:

./avm integration-test

Integration tests should deploy real resources and should be run against a real Azure subscription.
However, they are not fully integrated into the AVM GitHub Actions workflows.
Authors should run integration tests locally and ensure that they are passing but they will not be run automatically in the CI/CD pipeline.

Website Contribution Guide

Looking to contribute to the AVM Website, well you have made it to the right place/page. 👍

Follow the below instructions, especially the pre-requisites, to get started contributing to the library.

Context/Background

Before jumping into the pre-requisites and specific section contribution guidance, please familiarize yourself with this context/background on how this library is built to help you contribute going forward.

This site is built using Hugo, a static site generator, that’s source code is stored in the AVM GitHub repo (link in header of this site too) and is hosted on GitHub Pages, via the repo.

The reason for the combination of Hugo & GitHub pages is to allow us to present an easy to navigate and consume library, rather than using a native GitHub repo, which is not easy to consume when there are lots of pages and folders. Also, Hugo generates the site in such a way that it is also friendly for mobile consumers.

But I don’t have any skills in Hugo?

That’s okay and you really don’t need them. Hugo just needs you to be able to author markdown (.md) files and it does the rest when it generates the site 👍

Pre-Requisites

Read and follow the below sections to leave you in a “ready state” to contribute to AVM.

A “ready state” means you have a forked copy of the Azure/Azure-Verified-Modules repo cloned to your local machine and open in VS Code.

Run and Access a Local Copy of AVM Website During Development

When in VS Code you should be able to open a terminal and run the below commands to access a copy of the AVM website from a local web server, provided by Hugo, using the following address http://localhost:1313/Azure-Verified-Modules/:

cd docs
hugo server -D // you can add "--poll 700ms", if file changes are not detected

Software/Applications

To contribute to this website, you will need the following installed:

Tip

You can use winget to install all the pre-requisites easily for you. See the below section

Git
Visual Studio Code (VS Code)
- Extensions:
  - editorconfig.editorconfig, streetsidesoftware.code-spell-checker, ms-vsliveshare.vsliveshare, medo64.render-crlf, vscode-icons-team.vscode-icons
  - VS Code will recommend automatically to install these when you open this repo, or a fork of it, in VS Code.
Hugo Extended

winget Install Commands

To install winget follow the install instructions here.

winget install --id 'Git.Git'
winget install --id 'Microsoft.VisualStudioCode'
winget install --id 'Hugo.Hugo.Extended'

Other requirements

A GitHub profile/account
A fork of the Azure/Azure-Verified-Modules repo into your GitHub org/account and cloned locally to your .
- Instructions on forking a repo and then cloning it can be found here.

Useful Resources

Below are links to a number of useful resources to have when contributing to AVM:

Steps to do before contributing anything (after pre-requisites)

Run the following commands in your terminal of choice from the directory where you fork of the repo is located:

git checkout main
git pull
git fetch -p
git fetch -p upstream
git pull upstream main
git push

Doing this will ensure you have the latest changes from the upstream repo, and you are ready to now create a new branch from main by running the below commands:

git checkout main
git checkout -b <YOUR-DESIRED-BRANCH-NAME-HERE>

Top Tips

Sometimes the local version of the website may show some inconsistencies that don’t reflect the content you have created

If this happens, simply kill the Hugo local web server by pressing CTRL + C and then restart the Hugo web server by running hugo server -D from the docs/ directory.

Help & Support

Summary

This section provides information about AVM’s support.

GitHub Links

Issue Triage

This section provides information about the issue triage process and its automation, implemented across various AVM repositories.

AVM Issue Triage

“AVM Core Team Triage” Explained

This page provides guidance for members of the AVM Core Team on how to triage module proposals and generic issues filed in the AVM repository, as well as how to manage these GitHub issues throughout their lifecycle.

During the AVM Core Team Triage step, the following will be checked, completed and actioned by the AVM Core Team during their triage calls (which are currently twice per week).

Note

Every module needs a module proposal to be created in the AVM repository.

Tip

During the triage process, the AVM Core Team should also check the status of following queries:

Open items that need triaging: Needs: Triage 🔍
- Bicep items (that need triaging): Language: Bicep 💪 & Needs: Triage 🔍
- Terraform items (that need triaging): Language: Terraform 🌐 & Needs: Triage 🔍
Open items that need triaging AND aren’t being triaged yet: Needs: Triage 🔍 & NOT Status: In Triage 🔍
Open items that need attention: Needs: Attention 👋
Open items that need owners: Needs: Module Owner 📣
Open items with no recent activity: Status: No Recent Activity 💤
Open question/feedback items: Type: Question/Feedback 🙋‍♀️
Open items with long term status: Status: long-term ⏳
Open items that are not in a project.

Module Proposal triage

An issue is considered to be a module proposal if

it was opened through the “New AVM Module Proposal 📝” template,
it has the labels of Needs: Triage 🔍 and Type: New Module Proposal 💡 applied to it, and
it is assigned to the “AVM - Module Triage” GitHub project.

Follow these steps to triage a module proposal:

Add the Status: In Triage 🔍 label to indicate you’re in the process of triaging the issue.
Check module proposal issue/form:
- Check the Bicep or Terraform module indexes for the proposed module to make sure it is not already available or being worked on.
- Ensure the module’s details are correct as per specifications - naming, classification (resource/pattern) etc.
- Check if the module is added to the “Proposed” column on the AVM - Modules Triage GitHub project board.
- Check if the requestor is a Microsoft FTE.
- If there’s any additional clarification needed, contact the requestor through comments (using their GH handle) or internal channels - for Microsoft FTEs only! You can look them up by their name or using the Microsoft Open Source Management Portal’s People finder: “Linked people across Microsoft organizations”. Make sure you capture any decisions regarding the module in the comments section.
- Make adjustments to the module’s name/classification as needed.
- Change the name of the issue to reflect the module’s name, i.e.,
  - After the “[Module Proposal]:” prefix, change the issues name to the module’s approved name between backticks, i.e., ` and `, e.g., avm/res/sql/managed-instance for a Bicep module, or avm-res-compute-virtualmachine for a Terraform module.
  - Example:
    - “[Module Proposal]: avm/res/sql/managed-instance”
    - “[Module Proposal]: avm-res-sql-managedinstance”
- Check if the GitHub Policy Service Bot has correctly applied the module language label: Language: Bicep 💪 or Language: Terraform 🌐
Apply relevant labels
- Module classification (resource/pattern): Class: Resource Module 📦 or Class: Pattern Module 📦

Triaging pattern modules

As part of the triage of pattern modules, the following points need to be considered/clarified with the module requestor:

Shouldn’t this be a resource module? What makes it a pattern - e.g., does it deploy multiple resources?
What is it for? What problem does it fix or provides a solution for?
What is/isn’t part of it? Which resource and/or pattern modules are planned to be leveraged in it? Provide a list of resources that would be part of the planned module.
Where is it coming from/what’s backing it - e.g., Azure Architecture Center (AAC), community request, customer example. Provide an architectural diagram and related documentation if possible - or a pointer to these if they are publicly available.
Don’t let the module’s scope to grow too big, split it up to multiple smaller ones that are more maintainable - e.g., hub & spoke networking should should be split to a generic hub networking and multiple workload specific spoke networking patterns.
The module’s name should be as descriptive as possible.
Adopt strict name-to-scope mapping - e.g., hub & spoke networking shouldn’t deploy monitoring.

Scenario 1: Requestor doesn’t want to / can’t be module owner

Note

If requestor is interested in becoming a module owner, but is not a Microsoft FTE, the AVM core team will try to find a Microsoft FTE to be the module owner whom the requestor can collaborate with.

If the requestor indicated they didn’t want to or can’t become a module owner (or is not a Microsoft FTE), make sure the Needs: Module Owner 📣 label is assigned to the issue. Note: the GitHub Policy Service Bot should automatically do this, based on how the issue author responded to the related question.
Move the issue to the “Looking for owners” column on the AVM - Modules Triage GitHub project board.
Add a comment on the issue with the #RFRC tag to indicate that the repository should be created. This allows the module to be added the module indexes in the Proposed state, so that it can be found by the community and potential module owners.
Find module owners - if the requestor didn’t volunteer in the module proposal OR the requestor does not want or cannot be owner of the module:
- Try to find an owner from the AVM communities or await a module owner to comment and propose themselves on the proposal issue.
When a new potential owner is identified, continue with the steps described as follows.

Scenario 2: Requestor wants to and can become module owner

If the requestor indicated they want to become the module owner, the GitHub Policy Service Bot will add the Status: Owners Identified 🤘 label and will assign the issue to the requestor.

You MUST still confirm that the requestor is a Microsoft FTE and that they understand the implications of becoming the owner! If any of these conditions aren’t met, remove the Status: Owners Identified 🤘 label and unassign the issue from the requestor.

Make sure the requestor is a Microsoft FTE. You can look them up by their name or using the Microsoft Open Source Management Portal’s People finder: “Linked people across Microsoft organizations”.
Clarify the roles and responsibilities of the module owner:
- Clarify they understand and accept what “module ownership” means by replying in a comment to the requestor/proposed owner:

➕ Standard AVM Core Team Reply to Proposed Module Owners

<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for requesting/proposing to be an AVM module owner!

We just want to confirm **you agree to the below pages** that define what module ownership means:

- [Team Definitions & RACI](https://azure.github.io/Azure-Verified-Modules/specs/shared/team-definitions)
- [Module Specifications](https://azure.github.io/Azure-Verified-Modules/specs/module-specs)
- [Module Support](https://azure.github.io/Azure-Verified-Modules/help-support/module-support)

Any questions or clarifications needed, let us know!

If you agree, please just **reply to this issue with the exact sentence below** (as this helps with our automation 👍):

"I CONFIRM I WISH TO OWN THIS AVM MODULE AND UNDERSTAND THE REQUIREMENTS AND DEFINITION OF A MODULE OWNER"

Thanks,

The AVM Core Team

#RR
<!-- markdownlint-restore -->

Once module owner identified has confirmed they understand and accept their roles and responsibilities as an AVM module owner
- Make sure the issue is assigned to the confirmed module owner.
- Move the issue into the “In development” column on the AVM - Modules Triage GitHub Project board.
- Add a comment on the issue with the #RFRC tag to indicate that the repository should be created. This allows the module to be added the module indexes in the Proposed state, so that it can be found by the community.
- Make sure the Status: Owners Identified 🤘 label is added to the issue.
  - If applied earlier, remove the Needs: Module Owner 📣 label from the issue.
- Remove the labels of Needs: Triage 🔍 and Status: In Triage 🔍 to indicate you’re done with triaging the issue.
Update the AVM Module Indexes, following the process documented internally.
Use the following text to approve module development

➕ Final Confirmation for Proposed Module Owners - Bicep

<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for confirming that you wish to own this AVM module and understand the related requirements and responsibilities!

Before starting development, please ensure ALL the following requirements are met.

**Please use the following values explicitly as provided in the [module index](https://azure.github.io/Azure-Verified-Modules/indexes/) page**:

- For your module:
  - `ModuleName` - for naming your module
  - `TelemetryIdPrefix` - for your module's [telemetry](https://azure.github.io/Azure-Verified-Modules/spec/SFR3)
  - Folder path are defined in `RepoURL`.
  - Create GitHub teams for module owners and contributors and grant them permissions as outlined [here](https://azure.github.io/Azure-Verified-Modules/spec/SNFR20).

Check if this module exists in the other IaC language. If so, collaborate with the other owner for consistency. 👍

You can now start the development of this module! ✅ Happy coding! 🎉

**Please respond to this comment and request a review from the AVM core team once your module is ready to be published! Please include a link pointing to your PR, once available. 🙏**

Any further questions or clarifications needed, let us know!

Thanks,

The AVM Core Team
<!-- markdownlint-restore -->

➕ Final Confirmation for Proposed Module Owners - Terraform

<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for confirming that you wish to own this AVM module and understand the related requirements and responsibilities!

Check if this module exists in the other IaC language. If so, collaborate with the other owner for consistency. 👍

You can now start the development of this module! ✅ Happy coding! 🎉 If you have additional contributors, ensure you grant them permissions by adding them to the related GitHub teams, as outlined [here](https://azure.github.io/Azure-Verified-Modules/spec/SNFR20).

**Please respond to this comment and request a review from the AVM core team once your module is ready to be published! Please include a link pointing to your PR, once available. 🙏**

Any further questions or clarifications needed, let us know!

Thanks,

The AVM Core Team
<!-- markdownlint-restore -->

Important

Although, it’s not directly part of the module proposal triage process, to begin development, module owners and contributors might need additional help from the AVM core team, such as:

Update any Azure RBAC permissions for test tenants/subscription, if needed.
In case of Bicep modules only:
- Look for the module owners confirmation on the related [Module Proposal] issue that they have created the required -module-owners- and -module-contributors- GitHub teams.
- Ensure the -module-owners- and -module-contributors- GitHub teams have been assigned to their respective parent teams as outlined here.
- Ensure the CODEOWNERS file in the BRM repo has been updated.
- Ensure the AVM Module Issue template file in the BRM repo has been updated.

Post-Development issue management

Once module is developed and v0.1.0 has been published to the relevant registry

Assign the Status: Module Available 🟢 label to the issue.
Move the issue into “Done” column in AVM - Modules Triage GitHub Project.
Update the AVM Module Indexes, following the process documented internally.
Close the issue.

Important

The Module Proposal issue MUST remain open until the module is fully developed, tested and published to the relevant registry.
Do NOT close the issue before the successful publication is confirmed!
Once the module is fully developed, tested and published to the relevant registry, and the Module Proposal issue was closed, it MUST remain closed.

Orphaned modules

When a module becomes orphaned

If a module meets the criteria described in the “Orphaned Modules” chapter, the module is considered to be orphaned and the below steps must be performed.

Note

The original Module Proposal issue related to the module in question MUST remain closed and intact.

Instead, a new Orphaned Module issue must be opened that MUST remain open until the ownership is fully confirmed!

Once the Orphaned Module issue was closed, it MUST remain closed. If the module will subsequently become orphaned again, a new Orphaned Module issue must be opened.

Submit an “orphaned module” issue by using the “Orphaned AVM Module 🟡” issue template.
Make sure the Needs: Triage 🔍 , Needs: Module Owner 📣 , and the Status: Module Orphaned 🟡 labels are assigned to the issue and it is assigned to the “AVM - Module Triage” GitHub project.
Move the issue into the “Orphaned” column on the AVM - Modules Triage GitHub Project board.
Update the AVM Module Indexes, following the process documented internally.
Place an information notice as per the below guidelines:
- In case of a Bicep module:
  - Place the information notice - with the text below - in an ORPHANED.md file, in the module’s root.
  - Run the utilities/tools/Set-AVMModule.ps1 utility with the module path as an input. This re-generates the module’s README.md file, so that the README.md file will also contain the same notice in its header.
  - Make sure the content of the ORPHANED.md file is displayed in the README.md in its header (right after the title).
- In case of a Terraform module, place the information notice - with the text below - in the README.md file, in the module’s root.
- Once the information notice is placed, submit a Pull Request.

Include the following text in the information notice:

➕ Orphaned module notice for module README file

⚠️THIS MODULE IS CURRENTLY ORPHANED.⚠️

- Only security and bug fixes are being handled by the AVM core team at present.
- If interested in becoming the module owner of this orphaned module (must be Microsoft FTE), please look for the related "orphaned module" GitHub issue [here](https://aka.ms/AVM/OrphanedModules)!

Try to find a new owner using the AVM communities or await a new module owner to comment and propose themselves on the issue.

When a new owner is identified

Tip

To look for Orphaned Modules:

Click on the following link to use this saved query ➡️ Status: Module Orphaned 🟡 ⬅️.
Check the Orphaned swim lane on the Module Triage board.

When a new potential owner is identified, clarify the roles and responsibilities of the module owner:
- Clarify they understand and accept what “module ownership” means by replying in a comment to the requestor/proposed owner:

➕ Standard AVM Core Team Reply to New Owners of an Orphaned Module

<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for requesting/proposing to be an AVM module owner!

We just want to confirm **you agree to the below pages** that define what module ownership means:

- [Team Definitions & RACI](https://azure.github.io/Azure-Verified-Modules/specs/shared/team-definitions)
- [Module Specifications](https://azure.github.io/Azure-Verified-Modules/specs/module-specs)
- [Module Support](https://azure.github.io/Azure-Verified-Modules/help-support/module-support)

Any questions or clarifications needed, let us know!

If you agree, please just **reply to this issue with the exact sentence below** (as this helps with our automation 👍):

"I CONFIRM I WISH TO OWN THIS AVM MODULE AND UNDERSTAND THE REQUIREMENTS AND DEFINITION OF A MODULE OWNER"

Thanks,

The AVM Core Team

#RR
<!-- markdownlint-restore -->

Once the new module owner candidate has confirmed they understand and accept their roles and responsibilities as an AVM module owner
- Assign the issue to the confirmed module owner.
- Remove the Status: Module Orphaned 🟡 and the Needs: Module Owner 📣 labels from the issue.
- Add the Status: Module Available 🟢 and Status: Owners Identified 🤘 labels to the issue.
- Move the issue into the “Done” column on the AVM - Modules Triage GitHub Project board.
Update the AVM Module Indexes, following the process documented internally.
Get the new owner(s) and any new contributor(s) added to the related -module-owners- or -module-contributors- teams. See SNFR20 for more details.
Remove the information notice (i.e., the file that states that ⚠️THIS MODULE IS CURRENTLY ORPHANED.⚠️, etc. ):
- In case of a Bicep module:
  - Delete the ORPHANED.md file from the module’s root.
  - Run the utilities/tools/Set-AVMModule.ps1 utility with the module path as an input. This re-generates the module’s README.md file, so that it will no longer contain the orphaned module notice in its header.
  - Double check the previous steps was successful and the README.md file no longer has the information notice in its header (right after the title).
- In case of a Terraform module, remove the information notice from the README.md file in the module’s root.
- Once the information notice is removed, submit a Pull Request.
Use the following text to confirm the new ownership of an orphaned module:

➕ Final Confirmation for New Owners of an Orphaned Module

Close the Orphaned Module issue.

Deprecated modules

When a module becomes deprecated

If a module meets the criteria described in the “Deprecated Modules” chapter, the module is considered to be deprecated and the below steps must be performed.

Submit a “deprecated module” issue by using the “Deprecate AVM Module 🔴” issue template.
Make sure the Needs: Triage 🔍 and the Status: Module Deprecated 🔴 labels are assigned to the issue and it is assigned to the “AVM - Module Triage” GitHub project.
Update the AVM Module Indexes, following the process documented internally.
Place an information notice as per the below guidelines:
- In case of a Bicep module:
  - Place the information notice - with the text below - in an DEPRECATED.md file, in the module’s root.
  - Run the utilities/tools/Set-AVMModule.ps1 utility with the module path as an input. This re-generates the module’s README.md file, so that the README.md file will also contain the same notice in its header.
  - Make sure the content of the DEPRECATED.md file is displayed in the README.md in its header (right after the title).
  - Publish a new patch version, having the updated README.md stating the module is deprecated.
- In case of a Terraform module:
  - Place the information notice - with the text below - in the README.md file, in the module’s root.
  - Archive the module’s repository on GitHub.
- Once the information notice is placed, submit a Pull Request.
Keep the module’s -owners- and -contributors- GitHub teams, as these will keep granting access to the source code of the module.

Place the following information notice in the module’s repository:

➕ Deprecated module indicators

⚠️THIS MODULE IS DEPRECATED.⚠️

- It will no longer receive any updates.
- The module can still be used as is (references to any existing versions will keep working), but it is not recommended for new deployments.
- It is recommended to migrate to a replacement/alternative version of the module, if available.

General feedback/question, documentation update and other standard issues

An issue is a “General Question/Feedback ❔” if it was opened through the “General Question/Feedback ❔” issue template, and has the labels of Type: Question/Feedback 🙋‍♀️ and Needs: Triage 🔍 applied to it.

An issue is a “AVM Documentation Update 📘” if it was opened through the “AVM Documentation Update 📘” issue template, and has the labels of Type: Documentation 📄 and Needs: Triage 🔍 applied to it.

An issue is considered to be a “standard issue” or “blank issue” if it was opened without using an issue template, and hence it does NOT have any labels assigned, OR only has the Needs: Triage 🔍 label assigned.

When triaging the issue, consider adding one of the following labels as fits:

Type: Documentation 📄
Type: Feature Request ➕
Type: Bug 🐛
Type: Security Bug 🔒

To see the full list of available labels, please refer to the GitHub Repo Labels section.

Note

If an intended module proposal was mistakenly opened as a “General Question/Feedback ❔” or other standard issue, and hence, it doesn’t have the Type: New Module Proposal 💡 label associated to it, a new issue MUST be created using the “New AVM Module Proposal 📝” issue template. The mistakenly created “General Question/Feedback ❔” or other standard issue MUST be closed.

BRM Issue Triage

Overview

This page provides guidance for Bicep module owners on how to triage AVM module issues and AVM question/feedback items filed in the BRM repository (Bicep Registry Modules repository - where all Bicep AVM modules are published), as well as how to manage these GitHub issues throughout their lifecycle.

As such, the following issues are to be filed in the BRM repository:

[AVM Module Issue]: Issues specifically related to an existing AVM module, such as feature requests, bug and security bug reports.
[AVM Question/Feedback]:Generic feedback and questions, related to existing AVM module, the overall framework, or its automation (CI environment).

Do NOT file the following types of issues in the BRM repository, as they MUST be tracked in the AVM repo:

[Module Proposal]: Proposals for new AVM modules.
[Orphaned Module]: Indicate that a module is orphaned (has no owner).
[Question/Feedback]: Generic questions/requests related to the AVM site or documentation.

Note

Every module needs a module proposal to be created in the AVM repository.

Module Owner Responsibilities

During the triage process, module owners are expected to check, complete and follow up on the items described in the sections below.

Module owners MUST meet the SLAs defined on the Module Support page! While there’s automation in place to support meeting these SLAs, module owners MUST check for new issues on a regular basis.

Important

The BRM repository includes other, non-AVM modules and related GitHub issues. As a module owner, make sure you’re only triaging, managing or otherwise working on issues that are related to AVM modules!

Tip

To look for items that need triaging, click on the following link to use this saved query ➡️ Needs: Triage 🔍 ⬅️.
To look for items that need attention, click on the following link to use this saved query ➡️ Needs: Attention 👋 ⬅️.
Open items that are not in a project.

Module Issue

An issue is considered to be an “AVM module issue” if

it was opened through the [AVM Module Issue] template in the BRM repository,
it has the labels of Needs: Triage 🔍 and Type: AVM 🅰️ ✌️ ⓜ️ applied to it, and
it is assigned to the “AVM - Module Issues” GitHub project.

Note

Module issues can only be opened for existing AVM modules. Module issues MUST NOT be used to file a module proposal.

If the issue was opened as a misplaced module proposal, mention the @Azure/AVM-core-team-technical-bicep team in the comment section and ask them to move the issue to the AVM repository.

Triaging a Module Issue

Check the Module issue:
- Make sure the issue has the Type: AVM 🅰️ ✌️ ⓜ️ applied to it.
- Use the AVM module indexes to identify the module owner(s) and make sure they are assigned/mentioned/informed.
- If the module is orphaned (has no owner), make sure there’s an orphaned module issue in the AVM repository.
- Make sure the module’s details are captured correctly in the description - i.e., name, classification (resource/pattern), language (Bicep/Terraform), etc.
- Make sure the issue is categorized using one of the following type labels:
  - Type: Feature Request ➕
  - Type: Bug 🐛
  - Type: Security Bug 🔒
Apply relevant labels for module classification (resource/pattern): Class: Resource Module 📦 or Class: Pattern Module 📦
Communicate next steps to the requestor (issue author).
Remove the Needs: Triage 🔍 label.
When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
Only close the issue, once the next version of the module was fully developed, tested and published.

Triaging a Module PR

If the PR is submitted by the module owner and the module is owned by a single person, the AVM core team must review and approve the PR, (as the module owner can’t approve their on PR).
- To indicate that the PR needs the core team’s attention, apply the Needs: Core Team 🧞 label.
If the PR is submitted by a contributor (other than the module owner), or the module is owned by at least 2 people, one of the module owners should review and approve the PR.
Apply relevant labels
- Make sure the PR is categorized using one of the following type labels:
  - Type: Feature Request ➕
  - Type: Bug 🐛
  - Type: Security Bug 🔒
- For module classification (resource/pattern): Class: Resource Module 📦 or Class: Pattern Module 📦
If the module is orphaned (has no owner), make sure the related Orphaned module issue (in the AVM repository) is associated to the PR in a comment, so the new owner can easily identify all related issues and PRs when taking ownership.
Remove the Needs: Triage 🔍 label.

Give your PR a meaningful title

Prefix: Start with one of the allowed keywords - fix: or feat: is the most common for module related changes.
Description: Add a few words, describing the nature of the change.
Module name: Add the module’s full name between backticks ( ` ) to make it pop.

General Question/Feedback and other standard issues

An issue is considered to be an “AVM Question/Feedback” if

it was opened through the [AVM Question/Feedback] template in the BRM repository,
it has the labels of Needs: Triage 🔍 , Type: Question/Feedback 🙋‍♀️ and Type: AVM 🅰️ ✌️ ⓜ️ applied to it, and
it is assigned to the “AVM - Issue Triage” GitHub project.

Triaging a General Question/Feedback and other standard issues

When triaging the issue, consider adding one of the following labels as fits:
- Type: Documentation 📄
- Type: Feature Request ➕
- Type: Bug 🐛
- Type: Security Bug 🔒

To see the full list of available labels, please refer to the GitHub Repo Labels section.

Add any (additional) labels that apply.
Communicate next steps to the requestor (issue author).
Remove the Needs: Triage 🔍 label.
When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
Once the question/feedback/topic is fully addressed, close the issue.

Note

If an intended module proposal was mistakenly opened as a “AVM Question/Feedback ❔” or other standard issue, a new issue MUST be created in the AVM repo using the “New AVM Module Proposal 📝” issue template. The mistakenly created “AVM Question/Feedback ❔” or other standard issue MUST be closed.

Issue Triage Automation

This page details the automation that is in place to help with the triage of issues and PRs raised against the AVM modules.

Schedule based automation

This section details all automation rules that are based on a schedule.

Note

When calculating the number of business days in the issue/triage automation, the built-in logic considers Monday-Friday as business days. The logic doesn’t consider any holidays.

ITA01BCP.1 & ITA01BCP.2

If a bug/feature/request/general question that has the labels of Type: AVM 🅰️ ✌️ ⓜ️ and Needs: Triage 🔍 is not responded to after 3 business days, then the issue will be marked with the Status: Response Overdue 🚩 label and the AVM Core team will be mentioned in a comment on the issue to reach out to the module owner.

Schedule:

Triggered every Monday-Friday, at 12:00.

Trigger criteria:

Is an open issue.
Had no activity in the last 3 business days.
Has the Needs: Triage 🔍 and Type: AVM 🅰️ ✌️ ⓜ️ labels added.
Does not have the Status: Response Overdue 🚩 label added.

Action(s):

Add a reply, mentioning the Azure/avm-core-team-technical-bicep team.
Add the Status: Response Overdue 🚩 label.

Tip

To prevent further actions to take effect, the Status: Response Overdue 🚩 label must be removed, once this issue has been responded to.
To avoid this rule being (re)triggered, the Needs: Triage 🔍 must be removed as part of the triage process (when the issue is first responded to).

ITA01TF.1 & ITA01TF.2

If a bug/feature/request/general question that has the Needs: Triage 🔍 label added is not responded to after 3 business days, then the issue will be marked with the Status: Response Overdue 🚩 label and the AVM Core team will be mentioned in a comment on the issue to reach out to the module owner.

Schedule:

Triggered every Monday-Friday, at 12:00.

Trigger criteria:

Is an open issue.
Had no activity in the last 3 business days.
Has the Needs: Triage 🔍 label added.

Action(s):

Add a reply, mentioning the Azure/avm-core-team-technical-bicep team.
Add the Status: Response Overdue 🚩 label.

Tip

To prevent further actions to take effect, the Status: Response Overdue 🚩 label must be removed, once this issue has been responded to.
To avoid this rule being (re)triggered, the Needs: Triage 🔍 must be removed as part of the triage process (when the issue is first responded to).

ITA02BCP.1 & ITA02BCP.2

If after an additional 3 business days there’s still no update to the issue that has the labels of Type: AVM 🅰️ ✌️ ⓜ️ and Status: Response Overdue 🚩 , the AVM core team will be mentioned on the issue and a further comment stating module owner is unresponsive will be added. The Needs: Immediate Attention ‼️ label will also be added.

Schedule:

Triggered every Monday-Friday, at 12:00.

Trigger criteria:

Is an open issue.
Had no activity in the last 3 business days.
Has the Status: Response Overdue 🚩 and Type: AVM 🅰️ ✌️ ⓜ️ labels added.
Does not have the Needs: Immediate Attention ‼️ label added.

Action(s):

Add a reply, mentioning the Azure/avm-core-team-technical-bicep team.
Add the Needs: Immediate Attention ‼️ label.

Tip

To avoid this rule being (re)triggered, the Needs: Triage 🔍 and Status: Response Overdue 🚩 labels must be removed when the issue is first responded to!
Remove the Needs: Immediate Attention ‼️ label once the issue has been responded to.

ITA02TF.1 & ITA02TF.2

If after an additional 3 business days there’s still no update to the issue that has the Status: Response Overdue 🚩 label added, the AVM core team will be mentioned on the issue and a further comment stating module owner is unresponsive will be added. The Needs: Immediate Attention ‼️ label will also be added.

Schedule:

Triggered every Monday-Friday, at 12:00.

Trigger criteria:

Is an open issue.
Had no activity in the last 3 business days.
Has the Status: Response Overdue 🚩 label added.

Action(s):

Add a reply, mentioning the Azure/avm-core-team-technical-bicep team.
Add the Needs: Immediate Attention ‼️ label.

Tip

To avoid this rule being (re)triggered, the Needs: Triage 🔍 and Status: Response Overdue 🚩 labels must be removed when the issue is first responded to!
Remove the Needs: Immediate Attention ‼️ label once the issue has been responded to.

ITA03BCP

If there’s still no response after 5 days (total from start of issue being raised) on an issue that has the labels of Type: AVM 🅰️ ✌️ ⓜ️ , Needs: Triage 🔍 , Type: Security Bug 🔒 and Status: Response Overdue 🚩 , the Bicep PG GitHub Team will be mentioned on the issue to assist. The Needs: Immediate Attention ‼️ label will also be added.

Schedule:

Triggered every Monday-Friday, at 12:00.

Trigger criteria:

Is an open issue.
Had no activity in the last 5 business days.
Has the Needs: Triage 🔍 , the Type: Security Bug 🔒 , the Status: Response Overdue 🚩 , and Type: AVM 🅰️ ✌️ ⓜ️ labels added.

Action(s):

Add a reply, mentioning the Azure/bicep-admins team.
Add the Needs: Immediate Attention ‼️ label.

Tip

To avoid this rule being (re)triggered, the Needs: Triage 🔍 and Status: Response Overdue 🚩 labels must be removed when the issue is first responded to!
Remove the Needs: Immediate Attention ‼️ label once the issue has been responded to.

ITA03TF

If there’s still no response after 5 days (total from start of issue being raised) on an issue that has the labels of Needs: Triage 🔍 , Type: Security Bug 🔒 and Status: Response Overdue 🚩 , the Terraform PG GitHub Team will be mentioned on the issue to assist. The Needs: Immediate Attention ‼️ label will also be added.

Schedule:

Triggered every Monday-Friday, at 12:00.

Trigger criteria:

Is an open issue.
Had no activity in the last 5 business days.
Has the Needs: Triage 🔍 , the Type: Security Bug 🔒 , and Status: Response Overdue 🚩 labels added.

Action(s):

Add a reply, mentioning the Azure/terraform-avm team.
Add the Needs: Immediate Attention ‼️ label.

ITA04

If an issue/PR has been labelled with Needs: Author Feedback 👂 and hasn’t had a response in 4 days, label with Status: No Recent Activity 💤 and add a comment.

Schedule:

Triggered every 3 hours.

Trigger criteria:

Is an open issue/PR.
Had no activity in the last 4 days.
Has the Needs: Author Feedback 👂 label added.
Does not have the Status: No Recent Activity 💤 label added.

Action(s):

Add the Status: No Recent Activity 💤 label.
Add a reply.

Tip

To prevent further actions to take effect, one of the following conditions must be met:

The author must respond in a comment within 3 days of the automatic comment left on the issue.
The Status: No Recent Activity 💤 label must be removed.
If applicable, the Status: Long Term ⏳ or the Needs: Module Owner 📣 label must be added.

ITA05

Warning

This rule is currently disabled in the AVM and BRM repositories.

If an issue/PR has been labelled with Status: No Recent Activity 💤 and hasn’t had any update in 3 days from that point, automatically close it and comment, unless the issue/PR has a Status: Long Term ⏳ - in which case, do not close it.

Schedule:

Triggered every 3 hours.

Trigger criteria:

Is an open issue.
Had no activity in the last 3 days.
Has the Needs: Author Feedback 👂 and the Status: No Recent Activity 💤 labels added.
Does not have the Needs: Module Owner 📣 or Status: Long Term ⏳ labels added.

Action(s):

Add a reply.
Close the issue.

Tip

In case the issue needs to be reopened (e.g., the author responds after the issue was closed), the Status: No Recent Activity 💤 label must be removed.

ITA24

Remind module owner(s) to start or continue working on this module if there was no activity on the Module Proposal issue for more than 3 weeks. Add Needs: Attention 👋 label.

Schedule:

Triggered every 3 hours.

Trigger criteria:

Is an open issue.
Had no activity in the last 21 days.
Has the Type: New Module Proposal 💡 and the Status: Owners Identified 🤘 labels assigned.
Does not have the Status: Long Term ⏳ label assigned.
Does not have the Needs: Attention 👋 label assigned.

Action(s):

Add a reply.
Add the Needs: Attention 👋 label.

Tip

To silence this notification, provide an update every 3 weeks on the Module Proposal issue, or add the Status: Long Term ⏳ label.

Event based automation

This chapter details all automation rules that are based on an event.

ITA06

When a new issue or PR of any type is created add the Needs: Triage 🔍 label.

Trigger criteria:

An issue or PR is opened.

Action(s):

Add the Needs: Triage 🔍 label.
Add a reply to explain the action(s).

ITA08BCP

If AVM or “Azure Verified Modules” is mentioned in an uncategorized issue (i.e., one not using any template), apply the label of Type: AVM 🅰️ ✌️ ⓜ️ on the issue.

Trigger criteria:

An issue, issue comment, PR, or PR comment is opened, created or edited and the body or comment contains the strings of “AVM” or “Azure Verified Modules”.

Action(s):

Add the Type: AVM 🅰️ ✌️ ⓜ️ label.

ITA09

When #RR is used in an issue, add the label of Needs: Author Feedback 👂 .

Trigger criteria:

An issue comment or PR comment contains the string of “#RR”.

Action(s):

Add the Needs: Author Feedback 👂 label.

ITA10

When #wontfix is used in an issue, mark it by using the label of Status: Won’t Fix 💔 and close the issue.

Trigger criteria:

An issue comment or PR comment contains the string of “#RR”.

Action(s):

Add the Status: Won’t Fix 💔 label.
Close the issue.

ITA11

When the author replies, remove the Needs: Author Feedback 👂 label and label with Needs: Attention 👋 .

Trigger criteria:

Any action on an issue comment or PR comment except closing.
Has the Needs: Author Feedback 👂 label assigned.
The activity was initiated by the issue/PR author.

Action(s):

Remove the Needs: Author Feedback 👂 label.
Remove the Status: No Recent Activity 💤 label.
Add the Needs: Attention 👋 label.

ITA12

Clean up e-mail replies to GitHub Issues for readability.

Trigger criteria:

Any action on an issue comment.

Action(s):

Clean email reply. This is useful when someone directly responds to an email notification from GitHub, and the email signature is included in the comment.

ITA13

If the language is set to Bicep in the Module proposal, add the Language: Bicep 💪 label on the issue.

Trigger criteria:

An issue is opened with its body matching the below pattern.

### Bicep or Terraform?

Bicep

Action(s):

Add the Language: Bicep 💪 label.

ITA14

If the language is set to Terraform in the Module proposal, add the Language: Terraform 🌐 label on the issue.

Trigger criteria:

An issue is opened with its body matching the below pattern.

### Bicep or Terraform?

Terraform

Action(s):

Add the Language: Terraform 🌐 label.

ITA15

Remove the Needs: Triage 🔍 label from a PR, if it already has a “Type: XYZ label added and is assigned to someone at the time of creating it.

Trigger criteria:

A PR is opened with any of the following labels added and is assigned to someone:
- Type: Bug 🐛
- Type: Documentation 📄
- Type: Duplicate 🤲
- Type: Feature Request ➕
- Type: Hygiene 🧹
- Type: New Module Proposal 💡
- Type: Question/Feedback 🙋‍♀️
- Type: Security Bug 🔒

Action(s):

Remove the Needs: Triage 🔍 label.

ITA16

Add the Status: Owners Identified 🤘 label when someone is assigned to a Module Proposal.

Trigger criteria:

Any action on an issue except closing.
Has the Type: New Module Proposal 💡 added.
The issue is assigned to someone.

Action(s):

Add the Status: Owners Identified 🤘 label.

ITA17

If the issue author says they want to be the module owner, assign the issue to the author and respond to them.

Trigger criteria:

An issue is opened with its body matching the below pattern.
```
### Do you want to be the owner of this module?

Yes
```

Action(s):

Assign the issue to the author.

Add the below reply and explain the action(s).

@${issueAuthor}, thanks for volunteering to be a module owner!

**Please don't start the development just yet!**

The AVM core team will review this module proposal and respond to you first. Thank you!

ITA18

Send automatic response to the issue author if they don’t want to be module owner and don’t have any candidate in mind. Add the Needs: Module Owner 📣 label.

Trigger criteria:

An issue is opened with its body matching the below pattern.

  ### Do you want to be the owner of this module?

  No

  ### Module Owner's GitHub Username (handle)

  _No response_

Action(s):

Add the Needs: Module Owner 📣 label.

Add the below reply and explain the action(s).

@${issueAuthor}, thanks for submitting this module proposal!
The AVM core team will review it and will try to find a module owner.

ITA19

Send automatic response to the issue author if they don’t want to be module owner but have a candidate in mind. Add the Status: Owners Identified 🤘 label.

Trigger criteria:

An issue is opened with its body matching the below pattern…
```
  ### Do you want to be the owner of this module?

  No
```

…AND NOT matching the below pattern.

### Module Owner's GitHub Username (handle)

_No response_

Action(s):

Add the Status: Owners Identified 🤘 label.

Add the below reply and explain the action(s).

@${issueAuthor}, thanks for submitting this module proposal with a module owner in mind!

**Please don't start the development just yet!**

The AVM core team will review this module proposal and respond to you and/or the module owner first. Thank you!

ITA20

If the issue type is feature request, add the Type: Feature Request ➕ label on the issue.

Trigger criteria:

An issue is opened with its body matching the below pattern.
```
### Issue Type?

Feature Request
```

Action(s):

Add the Type: Feature Request ➕ label.

ITA21

If the issue type is bug, add the Type: Bug 🐛 label on the issue.

Trigger criteria:

An issue is opened with its body matching the below pattern.
```
### Issue Type?

Bug
```

Action(s):

Add the Type: Bug 🐛 label.

ITA22

If the issue type is security bug, add the Type: Security Bug 🔒 label on the issue.

Trigger criteria:

An issue is opened with its body matching the below pattern.
```
### Issue Type?

Security Bug
```

Action(s):

Add the Type: Security Bug 🔒 label.

ITA23

Remove the Status: In PR 👉 label from an issue when it’s closed.

Trigger criteria:

An issue is opened.

Action(s):

Remove the Status: In PR 👉 label.

ITA25

Inform module owners that they need to add the Needs: Core Team 🧞 label to their PR if they’re the sole owner of their module.

Trigger criteria:

A PR is opened.

Action(s):

Inform module owners that they need to add the Needs: Core Team 🧞 label to their PR if they’re the sole owner of their module.

ITA26

Add a label for the AVM Core Team to query called Status: Ready For Repository Creation 📝 when a module owner adds a comment to the issue to tell them.

Trigger criteria:

A comment is added to an issue that contains the #RFRC tag.

Action(s):

Adds the Status: Ready For Repository Creation 📝 label to the Issue.

ITA27

Add a comment to a PR that modifies these files based on the regex pattern, advising to disable GitHub Actions prior to merging:

“.github/actions/templates/avm-**”
“.github/workflows/avm.template.module.yml”
“utilities/pipelines/**”
“!utilities/pipelines/platform/**”

Trigger criteria:

A comment is added to an PR that modifies these files (above)

Action(s):

A comment is added to an PR that modifies these files as per below

[!WARNING]
**FAO: AVM Core Team**
When merging this PR it will trigger **all** AVM modules to be triggered! Please consider disabling the GitHub actions prior to merging and then re-enable once merged.

Where to apply these rules?

The below table details which repositories the above rules are applied to.

Rules applied for Schedule based automation

ID	AVM Core repository	BRM repository	TF repositories
ITA01BCP1-2		✔️
ITA01TF1-2			✔️
ITA02BCP1-2		✔️
ITA02TF1-2			✔️
ITA03BCP		✔️
ITA03TF			✔️
ITA04	✔️	✔️	✔️
ITA05	[✔️]	[✔️]	✔️
ITA24	✔️

Warning

The ITA05 rule is currently disabled in the AVM and BRM repositories.

Rules applied for Event based automation

ID	AVM Core repository	BRM repository	TF repositories
ITA06	✔️	✔️	✔️
ITA08BCP		✔️
ITA09	✔️	✔️	✔️
ITA10	✔️	✔️	✔️
ITA11	✔️	✔️	✔️
ITA12	✔️	✔️	✔️
ITA13	✔️
ITA14	✔️
ITA15	✔️	✔️	✔️
ITA16	✔️
ITA17	✔️
ITA18	✔️
ITA19	✔️
ITA20		✔️	✔️
ITA21		✔️	✔️
ITA22		✔️	✔️
ITA23	✔️		✔️
ITA25		✔️
ITA26	✔️
ITA27		✔️

Terraform Issue Triage

Overview

This page provides guidance for Terraform Module owners on how to triage AVM module issues and AVM question/feedback items filed in their Terraform Module Repo(s), as well as how to manage these GitHub issues throughout their lifecycle.

The following issues can be filed in a Terraform repository:

AVM Module Issue: Issues specifically related to an existing AVM module, such as feature requests, bug and security bug reports.
AVM Question/Feedback: Generic feedback and questions, related to existing AVM module, the overall framework, or its automation (CI environment).

Do NOT file the following types of issues in a Terraform repository, as they MUST be tracked in the AVM repo:

[Module Proposal]: Proposals for new AVM modules.
[Orphaned Module]: Indicate that a module is orphaned (has no owner).
[Question/Feedback]: Generic questions/requests related to the AVM site or documentation.

Note

Every module needs a module proposal to be created in the AVM repository.

Module Owner Responsibilities

During the triage process, module owners are expected to check, complete and follow up on the items described in the sections below.

Tip

To look for items that need triaging, look for issue labled with ➡️ Needs: Triage 🔍 ⬅️.
To look for items that need attention, look for issue labled with ➡️ Needs: Attention 👋 ⬅️.

Module Issue

An issue is considered to be an “AVM module issue” if

it was opened through the AVM Module Issue template in the Terraform repository,
it has the label of Needs: Triage 🔍 applied to it, and
it is assigned to the “AVM - Module Issues” GitHub project.

Note

Module issues can only be opened for existing AVM modules. Module issues MUST NOT be used to file a module proposal.

If the issue was opened as a misplaced module proposal, mention the @Azure/AVM-core-team-technical-terraform team in the comment section and ask them to move the issue to the AVM repository.

Triaging a Module Issue

Check the Module issue:
- Use the AVM module indexes to identify the module owner(s) and make sure they are assigned/mentioned/informed.
- If the module is orphaned (has no owner), make sure there’s an orphaned module issue in the AVM repository.
- Make sure the module’s details are captured correctly in the description - i.e., name, classification (resource/pattern), language (Bicep/Terraform), etc.
- Make sure the issue is categorized using one of the following type labels:
  - Type: Feature Request ➕
  - Type: Bug 🐛
  - Type: Security Bug 🔒
Apply relevant labels for module classification (resource/pattern): Class: Resource Module 📦 or Class: Pattern Module 📦
Communicate next steps to the requestor (issue author).
Remove the Needs: Triage 🔍 label.
When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
Only close the issue, once the next version of the module was fully developed, tested and published.

General Question/Feedback and other standard issues

An issue is considered to be an “AVM Question/Feedback” if

it was opened through the AVM Question/Feedback template in your Terraform repository,
it has the labels of Needs: Triage 🔍 and Type: Question/Feedback 🙋‍♀️ applied to it, and
it is assigned to the “AVM - Issue Triage” GitHub project.

Triaging a General Question/Feedback and other standard issues

When triaging the issue, consider adding one of the following labels as fits:
- Type: Documentation 📄
- Type: Feature Request ➕
- Type: Bug 🐛
- Type: Security Bug 🔒

To see the full list of available labels, please refer to the GitHub Repo Labels section.

Add any (additional) labels that apply.
Communicate next steps to the requestor (issue author).
Remove the Needs: Triage 🔍 label.
When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
Once the question/feedback/topic is fully addressed, close the issue.

Note

Known Issues

Unfortunately, there will be times where issues are out of the AVM core team and module owners/contributor’s control and the issue may be something that has to be lived with for a longer than ideal duration - for example, in case of changes that are due to the way the Azure platform, or a resource behaves, or because of an IaC language issue.

This page will detail any of the known issues that consumers may come across when using AVM modules and provide links to learn more about them and where to get involved in discussions on these known issues with the rest of the community.

Important

Issues related to an AVM module must be raised on the repo they are hosted on, not the AVM Central (Azure/Azure-Verified-Modules) repo!

Although, if you think a known issue is missing from this page please create an issue on the AVM Central Azure/Azure-Verified-Modules repo.

If you accidentally raise an issue in the wrong place, we will transfer it to its correct home. 👍

Bicep

Bicep what-if compatibility with modules

Bicep/ARM What-If has a known issue today where it short-circuits whenever a runtime function is used in a nested template. And due to the way Bicep modules work, all module declarations in a Bicep file end up as a resulting nested template deployment in the underlying generated ARM template, thereby invoking this known issue.

GitHub Issue for Further Information & Discussion

Azure/arm-template-whatif #157 - Resources in nested template not shown if reference is used in the parameter values

The ARM/Bicep Product Group has recently announced on the issue that they are making progress in this space and are aiming provide a closer ETA in the near future; see the comment here.

While this isn’t an AVM issue, we understand that consumers of AVM Bicep modules may want to use what-if and are running into this known issue. Please keep adding your support to the issue mentioned above (Azure/arm-template-whatif #157), as the Product Group are actively engaging in the discussion there. 👍

Other Related GitHub Issues

Azure/Azure-Verified-Modules #797 - [AVM Question/Feedback]: Output of what-if (if any) can’t be trusted

Terraform

Currently there are no known issues for AVM Terraform modules. 🥳

Module Support

Recent Changes to Support Statements

The AVM support statements and targets have been updated as of June 2025. To understand the changes, please review the below updates on this page.

For more information and reasoning behind the changes, please refer to the blog post we published on this topic: Tech Community: Azure Verified Modules: Support Statement & Target Response Times Update

As mentioned on the Introduction page, we understand that long-term support from Microsoft in an initiative like AVM is critical to its adoption by consumers and therefore the success of AVM. Therefore we have aligned and provide the below support statement/process for AVM modules:

Support Statements

Info

Module owners do go on holiday or have periods of leave from time to time, during these times the AVM core team will attempt to triage issues based on the below on behalf of module owners. 👍

For bugs/security issues

5 business days for a triage, meaningful response, and ETA to be provided for fix/resolution by module owner (which could be past the 5 days)
- For issues that breach the 5 business days, the AVM core team will be notified and will attempt to respond to the issue within an additional 5 business days to assist in triage.
- For security issues, the Bicep or Terraform Product Groups may step in to resolve security issues, if unresolved, after a further additional 5 business days.

For feature requests

15 business days for a meaningful response and initial triage to understand the feature request. An ETA may be provided by the module owner if possible.

AVM is Open-Source

AVM is open-source, therefore, contributions are welcome via Pull Requests or comments in Issues from anyone in the world at any time on any Pull Request or Issues to assist AVM module owners 🌐

Review the contribution guidance to get involved!

Info

All of this will be automated via the use of the Resource Management feature of the Microsoft GitHub Policy Service and GitHub Actions, where possible and appropriate.

Note

Please note that the durations stated above are for a reasonable and useful response towards resolution of the issue raised, if possible, and not for a fix within these durations; although if possible this will of course happen.

Tip

Issues that are likely related to an AVM module should be directly submitted on the module’s GitHub repository as an “AVM - Module Issue”. To identify the correct code repository, see the AVM module indexes.

If an issue is likely related to the Azure platform, its APIs or configuration, script or programming languages, etc., you need to raise a ticket with Microsoft CSS (Microsoft Customer Services & Support) where your ticket will be triaged for any platform issues. If deemed a platform issue, the ticket will be addressed accordingly. In case it’s deemed not a platform but a module issue, you will be redirected to submit a module issue on GitHub.

Orphaned Modules

Modules that have to have the AVM core team or Product Groups step in due to the module owners/contributors not responding, the AVM module will become “orphaned”; see Module Lifecycle for more info.

Info

If a module is orphaned, the AVM team will try to find a new owner by:

Listing orphaned modules in a saved GitHub issue query on the AVM module index pages for potential new owners to pick up.
In more urgent or high priority cases, selectively identifying a new module owner from the pool of existing AVM module owners/contributors to take over the module.

To raise attention to an orphaned module and allow the AVM team to better prioritize actions, customers can leave a comment on the “orphaned module” issue, explaining their use case and why they would like to see the module supported. This will help the AVM team to prioritize the module for a new owner.

Telemetry

Microsoft uses the approach detailed in this section to identify the deployments of the AVM Modules. Microsoft collects this information to provide the best experiences with their products and to operate their business. Telemetry data is captured through the built-in mechanisms of the Azure platform; therefore, it never leaves the platform, providing only Microsoft with access. Deployments are identified through a specific GUID (Globally Unique ID), indicating that the code originated from AVM. The data is collected and governed by Microsoft’s privacy policies, located at the Trust Center.

Telemetry collected as described here does not provide Microsoft with insights into the resources deployed, their configuration or any customer data stored in or processed by Azure resources deployed by using code from AVM. Microsoft does not track the usage/consumption of individual resources using telemetry described here.

Note

While telemetry gathered as described here is only accessible by Microsoft. Bicep customers have access to the exact same deployment information on the Azure portal, under the Deployments section of the corresponding scope (Resource Group, Subscription, etc.). Terraform customers can view the information sent in the main.telemetry.tf file.

See View deployment history with Azure Resource Manager for further information on how.

Technical Details

As detailed in SFR3 each AVM module contains a avmTelemetry deployment, which creates a deployment such as 46d3xbcp.res.compute-virtualmachine.1-2-3.eum3 (for Bicep) or 46d3xgtf.res.compute-virtualmachine.1-2-3.eum3 (for Terraform).

Opting Out

Albeit telemetry described in this section is optional, the implementation follows an opt-out logic, as most commercial software solutions, this project also requires continuously demonstrating evidence of usage, hence the AVM core team recommends leaving the telemetry setting on its default, enabled configuration.

This resource enables the AVM core team to query the number of deployments of a given module from Azure - and as such, get insights into its adoption.

To opt out you can set the parameters/variables listed below to false in the AVM module:

Bicep: enableTelemetry
Terraform: enable_telemetry

Telemetry vs Customer Usage Attribution

Though similar in principles, this approach is not to be confused and does not conflict with the usage of CUA IDs that are used to track Azure customer usage attribution of Azure marketplace solutions (partner solutions). The GUID-based telemetry approach described here can coexist and can be used side-by-side with CUA IDs. If you have any partner or customer scenarios that require the addition of CUA IDs, you can customize the AVM modules by adding the required CUA ID deployment while keeping the built-in telemetry solution.

Tip

If you’re a partner and want to build a solution that tracks customer usage attribution (using a CUA ID), we recommend implementing it on the consuming template’s level (i.e., the multi-module solution, such as workload/application) and apply the required naming format 'pid-' (without the suffix).

Resources

This page references additional resources available for Azure Verified Modules (AVM).

Note

Additional internal content available for Microsoft FTEs only, here.

🎥 Videos

An Introduction to Azure Verified Modules (AVM)
🆕 Microsoft Build 2025 - Accelerate your Azure platform journey with Azure Verified Modules
🆕 PowerShell and DevOps Summit 2025 - Accelerate your Azure platform journey with AVM, ALZ & Subscription Vending

Community Videos

📔 Blog posts

See the latest blog posts on Azure Verified Modules:

Azure Verified Modules - Monthly Update

See our former blog posts:

🔬 Labs

🎙️ Podcasts

AVM on the Ctrl+Alt+Azure Podcast - 226 - Azure Verified Modules with Jack Tracey

💻 Presentations

AVM Overview - Customer presentation

Community Calls

🎉 Join Our Community Calls! 🎉

🗓️ Quarterly calls, rotating time zones for global inclusion. 🌏

🌟 AVM team shares updates and stories.

🎤 Your voice matters: bring questions, stories, and suggestions.

📽️ Missed it? Watch the recording on YouTube!

Let’s make each community call a celebration of connection and collaboration!

Upcoming Events

Stay tuned, to be announced! 👂

Previous Events

1st July 2025

6th February 2025

24th September 2024

21st May 2024

Frequently Asked Questions (FAQ)

Tip

Got an unanswered question? Create a GitHub Issue so we can get it answered and added here for everyone’s benefit 👍

Note

Microsoft FTEs only: check out the internal FAQ for additional information.

Tip

Check out the Contribution Q&A for more answers to common questions about the contribution process.

Timeline, history, plans

When will we have a library that has a “usable” stand? Not complete, but the most important resources?

Bicep: AVM evolved all modules of CARML (Common Azure Resource Module Library) for its Bicep resource module collection (see here). To initially populate AVM with Bicep resource modules, all existing CARML modules have been migrated to AVM. Resource modules can now be directly leveraged to support the IaC needs of a wide variety of Azure workloads. Pattern modules can also be developed building on these resource modules.
Terraform: In case of Terraform, there were significantly less modules available in TFVM (Terraform Verified Modules Library) compared to CARML, hence, most Terraform modules have been and are being built as people volunteer to be module owners. We’ve been prioritizing the development of the Terraform modules based on our learnings from former initiatives, as well as customer demand - i.e., which ones are the most frequently deployed modules.

What happened to existing initiatives like CARML and TFVM?

The AVM team worked/works closely with the teams behind the following initiatives:

CARML (Common Azure Resource Modules Library)
TFVM (Terraform Verified Modules)
BRM (Bicep Registry Modules) - this is where the AVM Bicep modules are published.

Note

AVM is a straight-line evolution of CARML & TFVM.

All previously existing assets from these two libraries have been incorporated into AVM as resource or pattern modules.
All previously existing (non-AVM) modules that were published in the Public Bicep Registry (stored in the /modules folder of the BRM repository) have either been retired or transformed into an AVM module - while some are still being worked on.

CARML to AVM Evolution

CARML can be considered AVM’s predecessor. It was started by Industry Solutions Delivery (ISD) and the Customer Success Unit (CSU) and has been contributed to by many across Microsoft and has also had external contributions.

A lot of CARML’s principles and architecture decisions have formed the basis for AVM. Following a small number of changes to make them AVM compliant, all CARML modules have been transitioned to AVM as resource or pattern modules.

In summary, CARML evolved to and has been rebranded as the Bicep version of AVM. A notice has been placed on the CARML repo redirecting users and contributors to the AVM central repository.

Terraform Timeline and Approach

As the AVM core team is not directly responsible for the development of the modules (that’s the responsibility of the module owners), there’s no specific timeline available for the publication of Terraform modules.

However, the AVM core team is focused on the following activities to facilitate and optimize the development process:

Leveraging customer demand, telemetry and learnings from former initiatives to prioritize the development of Terraform modules.
Providing automated tools and processes (CI environment and automated tests).
Accelerating the build-out of the Terraform module owners’ community.
Recruiting new volunteers to build and maintain Terraform modules.

Will existing Landing Zone Accelerators (Platform & Application) be migrated to become AVM pattern modules and/or built from AVM resource modules?

Not in the short/immediate term. Existing Landing Zone Accelerators (Platform & Application) will not be forced to convert their existing code bases, if available in either language, to AVM or to use AVM.

However, over time if new features or functionality are required by Landing Zone Accelerators, that team SHOULD consider migrating/refactoring that part of their code base to be constructed with the relevant AVM module if available. For example, the Bicep version of the “Sub Vending” solution is migrating to AVM shortly.

If the relevant AVM module isn’t available to use to assist the Landing Zone Accelerator, then a new AVM module proposal should be made, and if desired, the Landing Zone Accelerator team may decide to own this proposed module 👍

Does/will AVM cover Microsoft 365, Azure DevOps, GitHub, etc.?

While the principles and practices of AVM are largely applicable to other clouds and services such as, Microsoft 365 & Azure DevOps, the AVM program (today) only covers Azure cloud resources and architectures.

However, if you think this program, or a similar one, should exist to cover these other Microsoft Cloud offerings, please give a 👍 or leave a comment on this GitHub Issue #71 in the AVM repository.

Will AVM also become a part of azd cli?

Yes, the AVM team is partnering with the AZD team and they are already using Bicep AVM modules from the public registry.

Will AVM support OpenTofu?

Please see our OpenTofu support statement in this discussion on GitHub.

Definitions, comparisons

What is the difference between the Bicep Registry and AVM? (How) Do they come together?

The Public Bicep Registry (backed by the BRM repository) is Microsoft’s official Bicep Registry for 1st party-supported Bicep modules. It has existed for a while now and has seen quite some contributions.

As various teams inside Microsoft have come together to establish a “One Microsoft” IaC approach and library, we started the AVM initiative to bridge the gaps by defining specifications for both Bicep and Terraform modules.

In the BRM repo today, “vanilla modules” (non-AVM modules) can be found in the /modules folder, while AVM modules are located in the /avm folder. Both are being published to the same endpoint, the Public Bicep Registry. AVM Bicep modules are published in a dedicated namespace, using the avm/res & avm/ptn prefixes to make them distinguishable from the Public Registry’s “vanilla modules”.

Note

Going forward, AVM will become the single Microsoft standard for Bicep modules, published to the Public Bicep Registry, via the BRM repository.

In the upcoming period, existing “vanilla” modules will be retired or migrated to AVM, and new modules will be developed according to the AVM specifications.

AVM - with its modules published in the Public Bicep Registry (backed by the BRM repository) - represents the only standard from Microsoft for Bicep modules in the Public Registry.

Bicep private registries and TemplateSpecs are different ways of inner-sourcing, sharing and internally leveraging Bicep modules within an organization. We’re planning to provide guidance for theses scenarios in the future.

AVM has nothing to do with Radius (yet), but the AVM core team is constantly looking for additional synergies inside Microsoft.

What does AVM mean by “WAF Aligned”?

Tip

WAF == Well-Architected Framework (as per our glossary)

At a high-level “WAF Aligned” means, where possible and appropriate, AVM Modules will align to recommendations and default input parameters/variables to values that algin to high impact/priority/severity recommendations in the following frameworks and resources:

Well-Architected Framework (WAF)
Reliability Hub
Azure Proactive Resiliency Library (APRL)
- Only Product Group (PG) verified

For security recommendations we will also utilize the following frameworks and resources; again only for high impact/priority/severity recommendations:

Microsoft Defender for Cloud (MDFC)

Will all AVM modules be 100% “WAF Aligned” out of the box and good to go?

Not quite, but they’ll certainly be on the right path. By default, modules will only have to set defaults for input parameters/variables to values that align to high impact/priority recommendations, as detailed above.

To understand this further you first must understand that some of the “WAF Aligned” recommendations, from the sources above are more than just setting a string or boolean value to something particular to meet the recommendation; some will require additional resources to be created and exist and then linked together to help satisfy the recommendation.

In these scenarios the AVM modules will not enforce the additional resources to be deployed and configured, but will provide sufficient flexibility via their input parameters/variables to be able to support the configuration, if so desired by the module consumer.

Tip

This is why we only enforce AVM module alignment to high impact/priority recommendations, as the the majority of recommendations that are not high impact/priority will require additional resources to be used together to be compliant, as the below example will show.

Some examples

Recommendation	Will Be Set By Default in AVM Modules?
TLS version should always be set the latest/highest version TLS 1.3	Yes, as string value
Key Vault should use RBAC instead of access policies for authorization	Yes, as string/boolean value
Container registries should use private link	No, as requires additional Private Endpoint and DNS configuration as well as, potentially, additional costs
API Management services should use a virtual network	No, as requires additional Virtual Network and Subnet configuration as well as, potentially, additional costs

Important

While every Well-Architected Framework pillar’s recommendations should equally be considered by the module owners/contributors, within AVM we are taking an approach to prioritize reliability and security over cost optimization. This provides consumers of the AVM modules, by default, more resilient and secure resources and patterns.

However, please note these defaulted values can be altered via input parameter/variables in each of the modules so that you can meet your specific requirements.

What is a “Primary Resource” in the context of AVM?

The definition of a Primary Resource is detailed in the glossary.

How does AVM align and assist with the Secure Future Initiative (SFI)?

AVM modules are continuously being improved with the security and reliability recommendations of the Well-Architected Framework (for more details, see what AVM means by “WAF-aligned”). The AVM team is continuously reviewing SFI recommendations and if required rolling out updates to the AVM initiative to remain SFI compliant as well as assisting module owners to ensure their modules help their consumers align to SFI where appropriate.

Contribution, module ownership

Can I be an AVM module owner if I’m not a Microsoft FTE?

Every module MUST have an owner who is responsible for module development and maintenance. One owner can own one or multiple modules. An owner can develop modules alone or lead a team that will develop a module.

Today, only Microsoft FTEs can be module owners. This is to ensure we can enforce and provide the long-term support required by this initiative.

However, you can still contribute to AVM as a non-Microsoft FTE. For more details, see how you can contribute to AVM without being a module owner below.

How can I contribute to AVM without being a module owner?

Yes, you can contribute to a module without being its owner, but you’ll still need a module owner whom you can collaborate with. For context, see the answer to this question.

Tip

If you’re a Microsoft FTE, you should consider volunteering to be a module owner. You can propose a new module, or look for orphaned modules and volunteer to be the owner for any of them.

If you’re not a Microsoft FTE or don’t want to be a module owner, you can still contribute to AVM. You have multiple options:

You can propose a new module and provide as much context as possible under the “Module Details” section (e.g., why do you need the module, what’s the business impact of not having it, etc.). The AVM core team will try to find a Microsoft FTE to be the module owner whom you can collaborate with.
You can contact the current owner of any existing module and offer to contribute to it. You can find the current owners of all AVM modules in the module indexes.
You can look for orphaned modules and use the comment section to indicate that you’d be interested in contributing to this module, once a new owner is found.

Are there different ways to contribute to AVM?

Yes, there are multiple ways to contribute to AVM!

You can contribute to modules:

Become an owner (preferred):
- Propose and develop a new module (Bicep or Terraform) or pick up a module someone else proposed.
- Become the owner of an orphaned module (mainly Bicep) - look for “orphaned module” issues here or see the “Orphaned” swimlane here
Become an administrative owner and work with other contributors or co-owners on developing and maintaining modules.
Volunteer as a co-owner or module contributor to an existing module, and work along other contributors and the (administrative) module owner.
You can submit a PR with a small proposed change without officially becoming a module owner or contributor.

Or you can contribute to the AVM website/documentation, by following this guidance.

Note

New modules can’t be created and published without having a module owner assigned.

Where can I find modules I can contribute to?

You can find modules missing owners in the following places:

All new modules looking for owners or see the “Looking for owners” swimlane here
- New Bicep modules looking for owners or see the “Looking for owners” swimlane here
- New Terraform modules looking for owners or see the “Looking for owners” swimlane here
All Orphaned modules or see the “Orphaned” swimlane here
- Orphaned Bicep modules or see the “Orphaned” swimlane here
- Orphaned Terraform modules or see the “Orphaned” swimlane here
All modules looking for contributors
- Bicep modules looking for contributors
- Terraform modules looking for contributors

Tip

To indicate your interest in owning or contributing to a module, just leave a comment on the respective issue.

Note

If any of these queries don’t return any results, it means that no module in the selected category is looking for an owner or contributor at the moment.

I want to become the owner of XYZ modules, where can I indicate this, and what are the expected actions from me?

If exists, you can comment on the Module Proposal issue of the module that you are interested in and the AVM Core Team will do the triage providing information about next steps.

Having an understanding of roles & responsibilities is useful as well, you can find this information on the Team Definitions & RACI | Azure Verified Modules page.

Can I submit a PR with new features to an existing module? If so, is this a good way to contribute too?

Of course! As all modules are open source, anyone can submit a PR to an existing module. But we’d suggest opening an issue first to discuss the suggested changes with the module owner before investing time in the code.

Are there any videos on how to get started with contribution? E.g., how to set up a local environment for development, how to write a unit test etc.?

No videos on the technical details of contribution are available (yet), but a detailed, written guidance can be found for both Bicep and Terraform, here:

Support

Is AVM a Microsoft official service/product/library or is this classified as an OSS backed by Microsoft?

AVM is an officially supported OSS project from Microsoft, across all organizations.

AVM is owned, developed & supported by Microsoft, you may raise a GitHub issue on this repository or the module’s repository directly to get support or log feature requests.

You can also log a support ticket and these will be redirected to the AVM team and the module owner(s).

See Module Support for more information.

So, does CSS support AVM?

Yes, and if they cannot resolve it (and/or it’s not related to a Microsoft service/platform/api/etc.) they will pass the ticket to the module owner(s) to resolve.

For Microsoft FTEs only: see the Internal wiki for support workflow for more details -AVM - Support Workflow - Overview

How are AVM modules updated/maintained?

Module owners are tasked to do with two types of maintenance:

Proactive: keeping track of the modules’ underlying technology evolving, and keep modules up to date with the latest features and API versions.
Reactive: sometimes, mistakes are made that result in bugs and/or there might be features consumers ask for faster than module owners could proactively implement them. Consumers can request feature updates and bug fixes for existing modules here.

Can AVM module be used in production before it is marked as “GA” / v1.0?

As the overall AVM framework is not GA (generally available) yet - the CI framework and test automation is not fully functional and implemented across all supported languages yet - breaking changes are expected, and additional customer feedback is yet to be gathered and incorporated. Hence, modules must not be published at version 1.0.0 or higher at this time. All module must be published as a pre-release version (e.g., 0.1.0, 0.1.1, 0.2.0, etc.) until the AVM framework becomes GA.

However, it is important to note that this does not mean that the modules cannot be consumed and utilized. They can be leveraged in all types of environments (dev, test, prod etc.). Consumers can treat them just like any other IaC module and raise issues or feature requests against them as they learn from the usage of the module. Consumers should also read the release notes for each version, if considering updating to a more recent version of a module to see if there are any considerations or breaking changes etc.

Why did the AVM team change the support statements and targets in June 2025?

The AVM team has updated the support statements and targets to better align with the current state of the AVM initiative and to ensure that module owners can provide meaningful responses and resolutions to issues raised by consumers. The changes were made to improve clarity, set realistic expectations, and enhance the overall support experience for AVM modules and their consumers.

More information about the changes can be found in the blog post, Tech Community: Azure Verified Modules: Support Statement & Target Response Times Update, we published on this topic.

Technical questions

Should pattern modules leverage resource modules? What if (some of) the required resource modules are not available?

The initial focus of development and migration from CARML/TFVM has solely been on resource modules. Now that the most important resource modules are published, pattern modules can leverage them as and where needed. This however doesn’t mean that the development of pattern modules is blocked in any way if a resource module is not available, since they may use native resources (“vanilla code”). If you’re about to develop a pattern module and would need a resource modules that doesn’t exist today, please consider building the resource module first, so that others can leverage it for their pattern modules as well.

Please see PMNFR2 for more details.

Does AVM have same limitations as ARM (4 MB) size and 255 parameters only?

Yes, as AVM is just a collection of official Bicep/Terraform modules, it still has same Bicep/Terraform language or Azure platform limitations.

Does/will AVM support Managed Identity, and Microsoft Entra objects automation?

Managed Identities - Yes, they are supported in all resources today.
Entra objects - May come as new modules if/when the Graph provider will be released which is still in private preview.

How does AVM ensure code quality?

AVM utilizes a number of validation pipelines for both Bicep and Terraform. These pipelines are run on every PR and ensure that the code is compliant with the AVM specifications and that the module is working as expected.

For example, in case of Bicep, as part of the PR process, we’re asking contributors to provide a workflow status badge as a proof of successful validation using our testing pipelines.

The validation includes 2 main stages run in sequence:

Static validation: to ensure that the module complies to AVM specifications.
Deployment validation: to ensure all test examples are working from a deployment perspective.

These same validations are also run in the BRM repository after merge. The new version of the contributed module is published to the Public Bicep Registry only if all validations are successful.

Does AVM use semantic versioning?

Yes! For generic guidance, see SNFR17 - Semantic Versioning.
For Bicep specific guidance, see BCPNFR14 - Versioning.

What’s the guidance on transitioning to new module versions?

AVM is not different compared to any other solution using semantic versioning.

Customer should consider updating to a newer version of a module if:

They need a new feature the new version has introduced.
It fixes a bug they were having.
They’d like ot use the latest and greatest version.

To do this they just change the version in their module declaration for either Terraform or Bicep and then run it through their pipelines to roll it out.

The high level steps are:

Check module documentation for any version-incompatibility notes.
Increase the version (point to the selected published version of the module).
Do a what-if (Bicep) or terraform plan (Terraform) & review the changes proposed.
- If all good, proceed to deployment/apply.
- If not, make required changes to make the plan/what-if as expected.

Using AVM

How can I use Bicep modules through the Public Registry?

Please see the Bicep Quickstart guide here.

Do I need to allow a specific URL to access the Public Registry?

In a regulated environment, network traffic might be limited, especially when using private build agents. The AVM Bicep templates are served from the Microsoft Container Registry. To access this container registry, the URL https://mcr.microsoft.com must be accessible from the network. So, if your network settings or firewall rules prevent access to this URL, you would need to allow it to ensure proper functioning.

Aren’t AVM resource modules too complex for people less skilled in IaC technologies?

TLDR: Resource modules have complexity inside, so they can be flexibly used from the outside.

Resource modules are written in a flexible way; therefore, you don’t need to modify them from project to project, use case to use case, as they aim to cover most of the functionality that a given resource type can provide, in a way that you can interact with any module just by using the required parameters - i.e., you don’t have to know how the template of the particular module works inside, just take a look at the README.md file of the given module to learn how to leverage it.

Resource modules are multi-purpose; therefore, they contain a lot of dynamic expressions (functions, variables, etc.), so there’s no need to maintain multiple instances for different use cases. They can be deployed in different configurations just by changing the input parameters. They should be perceived by the user as black boxes, where they don’t have to worry about the internal complexity of the code, as they only interact with them by their parameters.

Can I call a Bicep child module directly? E.g., can I update or add a secret in an existing Key Vault, or a route in an existing route table?

As per the way the Public Registry is implemented today, it is not possible to publish child-modules separate from its parents. As such, you cannot reference e.g. a avm/res/key-vault/vault/key module directly from the registry, but can only deploy it through its parent avm/res/key-vault/vault - UNLESS you actually grab the module folder locally.

However, we kept the door open to make this possible in the future if there is a demand for it.

If I use AVM modules in my solution, do I need to have the MIT license in my own repo also? Do I need to add or reference AVM’s license in my solution?

Microsoft is not in the position of providing legal guidance on what licensing model your product/solution/etc. (the “Software”) leveraging Azure Verified Modules can or should be under. Generally speaking, the MIT license is permissive and allows you to freely use, modify, and distribute the code and does not mandate you to have your entire Software under the MIT license, but you must follow the requirements for the MIT-licensed code that you carry. As stated in the AVM LICENSE reference here, the described “copyright notice and permission notice shall be included in all copies or substantial portions of the Software”.

Glossary

Terms, Abbreviations, and Acronyms

This page holds a table of all the terms, abbreviations, and acronyms that are used across this site.

Term/Abbreviation/Acronym	Definition
AVM	Azure Verified Modules
IaC	Infrastructure-as-Code
CARML	Common Azure Resource Modules Library - `Azure/ResourceModules`
TFVM	Terraform Verified Modules - `Azure/terrafrom-azure-mdoules`
FY	Microsoft Fiscal Year (July to June)
CY	Calendar Year (January to December)
CSU	Microsoft Customer Success Unit
ISD	Microsoft Industry Solution Delivery
CSS	Microsoft Customer Services & Support
LZA	Landing Zone Accelerators - e.g., Azure Virtual Desktop (AVD), Azure VMware Solution (AVS), etc.
RP/RPs	Azure Resource Providers
PG/PGs	Microsoft Product Group(s)
AAC	Azure Architecture Center
WAF	Well-Architected Framework
One Microsoft	“We are a family of individuals united by a single, shared mission. It’s our ability to work together that makes our dreams believable and, ultimately, achievable. We will build on the ideas of others and collaborate across boundaries to bring the best of Microsoft to our customers as one. We are proud to be part of team Microsoft.” See Microsoft cultural attributes
FTE/FTEs	Full Time Employee(s)
GA	Generally Available
MDFC	Microsoft Defender for Cloud
MCSB	Microsoft Cloud Security Benchmark
MCR	Microsoft Container Registry. Which is what the Bicep Public Registry uses to publish it’s modules via.
PR	Pull Request
Primary Resource	A primary resource is the main Azure service/product a Resource Module provides / is built around.

Azure Verified Modules

Introduction

Value Proposition

Modules

Next Steps

Subsections of Azure Verified Modules

Overview

Summary

Subsections of Overview

Introduction

What is Azure Verified Modules?

Definition of “Verified” Summary

Why Azure Verified Modules?

How will we create, support and enforce Azure Verified Modules?

Module Indexes

Summary

Subsections of Module Indexes

Bicep Modules

Summary

Status Badges

Subsections of Bicep

Bicep Resource Modules

Module catalog

Published modules - 🟢 & 🟡

Proposed modules - ⚪

Deprecated modules - 🔴

All modules - 📇

Module Publication History - 📅

Modules published in July 2025

Modules published in June 2025

Modules published in May 2025

Modules published in March 2025

Modules published in February 2025

Modules published in January 2025

Modules published in December 2024

Modules published in October 2024

Modules published in September 2024

Modules published in June 2024

Modules published in May 2024

Modules published in April 2024

Modules published in March 2024

Modules published in February 2024

Modules published in January 2024

Modules published in December 2023

Modules published in November 2023

Modules published in October 2023

For Module Owners & Contributors

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

Bicep Pattern Modules

Module catalog

Published modules - 🟢 & 🟡

Proposed modules - ⚪

Deprecated modules - 🔴

All modules - 📇

Module Publication History - 📅

Modules published in July 2025

Modules published in June 2025

Modules published in April 2025

Modules published in March 2025

Modules published in February 2025

Modules published in December 2024

Modules published in October 2024

Modules published in September 2024

Modules published in August 2024

Modules published in July 2024

Modules published in June 2024

Modules published in May 2024

Modules published in April 2024

For Module Owners & Contributors

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors

Bicep Utility Modules

Module catalog

Published modules - 🟢 & 🟡

Proposed modules - ⚪

Deprecated modules - 🔴

All modules - 📇

Module Publication History - 📅

Modules published in October 2024

For Module Owners & Contributors

Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors