Subsections of Help & Support

Subsections of Issue Triage

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:

Module Proposal triage

An issue is considered to be a module proposal if

Follow these steps to triage a module proposal:

  1. Add the  Status: In Triage 🔍  label to indicate you’re in the process of triaging the issue.

  2. 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 internal “1ES Open Source Assistant Browser Extension”. 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 🌐 

  3. 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.

  1. 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.
  2. Move the issue to the “Looking for owners” column on the AVM - Modules Triage GitHub project board.
  3. 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.
  4. 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.

  1. Make sure the requestor is a Microsoft FTE. You can look them up by their name or using the Microsoft internal “1ES Open Source Assistant Browser Extension”.
  2. 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 -->
  1. 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.
    • 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.
  2. Update the AVM Module Indexes, following the process documented internally.
  3. Use the following text to approve module development
➕ Final Confirmation for Proposed Module Owners
<!-- 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)
- For your module's repository:
  - Repo name and 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).
  - Grant permissions for the AVM core team and PG teams on your GitHub repo as described [here](https://azure.github.io/Azure-Verified-Modules/spec/SNFR9).

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 -->
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:

  1. Update any Azure RBAC permissions for test tenants/subscription, if needed.
  2. 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

  1. Assign the  Status: Module Available 🟢  label to the issue.
  2. Move the issue into “Done” column in AVM - Modules Triage GitHub Project.
  3. Update the AVM Module Indexes, following the process documented internally.
  4. 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 AVM Modules” chapter, the modules is considered to be orphaned and the below steps must be performed.

An issue is considered to be an orphaned module if

  • it was opened through the “Orphaned AVM Module 👀” template,
  • it has the labels of  Needs: Triage 🔍 ,  Needs: Module Owner 📣  and the  Status: Module Orphaned 👀  applied to it, and
  • it is assigned to the “AVM - Module Triage” GitHub project.
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.

  1. Create a new issue using the “Orphaned AVM Module 👀” issue template.
  2. Make sure the  Needs: Triage 🔍 ,  Needs: Module Owner 📣 , and the  Status: Module Orphaned 👀  labels are assigned to the issue.
  3. Move the issue into the “Orphaned” column on the AVM - Modules Triage GitHub Project board.
  4. Update the AVM Module Indexes, following the process documented internally.
  5. 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)!
  1. 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:

  1. 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 -->
  1. 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.
  2. Update the AVM Module Indexes, following the process documented internally.
  3. 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.
  4. 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.
  5. Use the following text to confirm the new ownership of an orphaned module:
➕ Final Confirmation for New Owners of an Orphaned Module
<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for confirming that you wish to own this AVM module and understand the related requirements and responsibilities!

We just want to ask you to double check a few important things.

**Please use the following values explicitly as provided in the [module index](https://azure.github.io/Azure-Verified-Modules/indexes/) page**:

- You must be the owner of the GitHub teams as outlined [here](https://azure.github.io/Azure-Verified-Modules/spec/SNFR20).
- Please check that your name has been updated in the module index page (this should happen shortly after you confirmed ownership).

You can now take ownership of this module and start improving it as needed! ✅ Happy coding! 🎉

Any further questions or clarifications needed, let us know!

Thanks,

The AVM Core Team
<!-- markdownlint-restore -->
  1. Close the Orphaned Module issue.

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:

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

Module Issue

An issue is considered to be an “AVM module issue” if

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

  1. 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 🔒 
  2. Apply relevant labels for module classification (resource/pattern):  Class: Resource Module 📦  or  Class: Pattern Module 📦 
  3. Communicate next steps to the requestor (issue author).
  4. Remove the  Needs: Triage 🔍  label.
  5. When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
  6. Only close the issue, once the next version of the module was fully developed, tested and published.

Triaging a Module PR

  1. 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.
  2. 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.
  3. 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 📦 
  4. 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.
  5. 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.

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.

Triaging a General Question/Feedback and other standard issues

  1. 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.

  1. Add any (additional) labels that apply.
  2. Communicate next steps to the requestor (issue author).
  3. Remove the  Needs: Triage 🔍  label.
  4. When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
  5. 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-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.

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-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-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.

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-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 added.
  • Does not have the  Status: Long Term ⏳  label added.

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 added.
  • 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.

Where to apply these rules?

The below table details which repositories the above rules are applied to.

Rules applied for Schedule based automation

IDAVM Core repositoryBRM repositoryTF 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

IDAVM Core repositoryBRM repositoryTF repositories
ITA06✔️✔️✔️
ITA08BCP✔️
ITA09✔️✔️✔️
ITA10✔️✔️✔️
ITA11✔️✔️✔️
ITA12✔️✔️✔️
ITA13✔️
ITA14✔️
ITA15✔️✔️✔️
ITA16✔️
ITA17✔️
ITA18✔️
ITA19✔️
ITA20✔️✔️
ITA21✔️✔️
ITA22✔️✔️
ITA23✔️✔️
ITA25✔️

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:

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.

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

  1. 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 🔒 
  2. Apply relevant labels for module classification (resource/pattern):  Class: Resource Module 📦  or  Class: Pattern Module 📦 
  3. Communicate next steps to the requestor (issue author).
  4. Remove the  Needs: Triage 🔍  label.
  5. When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
  6. 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

  1. 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.

  1. Add any (additional) labels that apply.
  2. Communicate next steps to the requestor (issue author).
  3. Remove the  Needs: Triage 🔍  label.
  4. When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
  5. 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.

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

Terraform

Currently there are no known issues for AVM Terraform modules. 🥳

Module Support

As mentioned on the Overview 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.

Important

Issues with an AVM module should be raised on the repo they are hosted on, not the AVM Central (Azure/Azure-Verified-Modules) repo!

Not an issue if you raise in the wrong place, we will transfer it to it’s correct home 👍

Azure Verified Modules are supported by the AVM teams, as defined here, using GitHub issues in the following order of precedence:

  1. Module owners/contributors
  2. If there is no response within 3 business days, then the AVM core team will step in by:
    • First attempting to contact the module owners/contributors to prompt them to act.
    • If there is no response within a further 24 hours (on business days), the AVM core team will take ownership, triage, and provide a response within a further 2 business days.
  3. In the event of a security issue being unaddressed after 5 business days, escalation to the product group (Bicep/Terraform) to assist the AVM core team, will occur to provide additional support towards resolution; if required.
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.

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.

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.

Important

You can also raise a ticket with Microsoft CSS (Microsoft Customer Services & Support) and your ticket will be triaged by them for any platform issues and if deemed not the platform but a module issue, it will be redirected to the AVM team and the module owner(s).

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).