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

Info

To publish a new version of an existing module (i.e., anything that is not being published for the first time ever), there’s no need to submit any issues in the AVM repository; contributors can just submit a Pull Request in the module’s repository with the suggested changes.

➕ Who needs to approve the PR?

Approval for changes to existing modules depends on the language:

Bicep: Module owners are requested for review based on their root metadata.json, but ordinary code changes may be approved and merged by any eligible BRM repository team member under repository rules. Authors cannot approve their own changes. Changes to metadata.json require metadata code-owner review; other protected paths follow their CODEOWNERS rules.

Terraform: Module-owner approval remains required in Terraform module repositories:

This approval guidance applies to Terraform module repositories. See the Terraform review and merge process.

PR is submitted by a module ownerPR is submitted by anyone, other than the module owner
Module has a single module ownerAn eligible AVM core team member or another Terraform module owner approves the PRModule owner approves the PR
Module has multiple module ownersAnother owner of the module (other than the submitter) approves the PROne of the owners of the module approves the PR

Changes to metadata.json require approval from an eligible member of either @Azure/azure-verified-modules-engineering-owners or @Azure/azure-verified-modules-module-owners. Either team is sufficient; approval from both is not required. Being listed in the module’s owners array does not by itself authorize approval. Follow the metadata review process; code changes in the same pull request still need the normal reviews described above.

Reviewer notifications and triage labels help find reviewers; they do not replace either language’s repository rules.

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:

  1. The module owner is responsible for finding a replacement owner and providing a handover.
  2. 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
  3. The AVM core team will continue to try and re-assign the module ownership.
  4. 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.
  5. 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. For the required steps, review the related article: When a module becomes orphaned.

Set "owners": [] in the root metadata.json to remove all individual and team handles, following the metadata review process. Keep the tracking issue open until ownership is confirmed; the four-hourly catalog sync publishes the status in the public index.

When a new owner is identified, follow the related guidance.

Notification of a Module Becoming Orphaned

Important

The tracking issue and generated module index communicate the module’s orphaned status. For both Bicep and Terraform, no ORPHANED.md file or manual README.md notice is required. Orphaning and adoption are metadata-only ownership changes; do not regenerate the README or release a module version for them.

Issue-routing automation reads module ownership data; no per-module automation change is required when a module becomes orphaned.

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:

  1. The module will show as deprecated in the AVM module index.
  2. The module will no longer be shown through VS Code IntelliSense.
  3. 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.
  4. 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.

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.
- If the underlying Azure service is not deprecated/retired, this module may 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. For the required steps, review the related article: When a module becomes deprecated.

The catalog derives Deprecated from Bicep’s DEPRECATED.md or the Terraform repository’s archived flag. Complete the notices and other retirement steps above; the four-hourly catalog sync then publishes the change.

A Bicep marker deprecates its module and all descendants. A child marker does not deprecate the parent or siblings. Archiving a Terraform repository deprecates every module entry in that repository.

A module deprecated before it was ever published to the registry is removed from the indexes rather than listed as Deprecated.

Changing owners does not deprecate or reactivate a module.

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

  1. 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.
  2. Identify the available versions of the module, e.g., 0.1.0, 0.1.1, etc.
  3. 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
  4. 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-hub

Terraform modules will be listed in the HashiCorp Terraform Registry indefinitely.