diff --git a/docs/content/concepts/what-why-how.md b/docs/content/concepts/what-why-how.md deleted file mode 100644 index 1ca3317..0000000 --- a/docs/content/concepts/what-why-how.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: What, Why, How -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -{{< toc >}} - -## 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.). - -{{< hint type=tip icon=gdoc_heart title="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. - -{{< /hint >}} - -### Definition of "Verified" Summary - -- The modules are supported by Microsoft, across it's many internal organizations, as described in [Module Support](/Azure-Verified-Modules/help-support/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"?'](/Azure-Verified-Modules/faq/#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: - -1. Publishing AVM modules to their respective public registries for consumption - - For Bicep this will be the [Bicep Public Module Registry](https://aka.ms/BRM) - - For Terraform this will be the [HashiCorp Terraform Registry](https://registry.terraform.io/) -2. Creating, publishing and maintaining the Azure Verified Modules specifications (this site) - - Including IaC language specific specifications (today Bicep and Terraform) -3. Creating easy to follow AVM module contribution and publishing guidance for each IaC language (today Bicep and Terraform) -4. Enforcing tests for each AVM module is compliant with the AVM specifications, where possible, via Unit and Integration tests -5. Enforcing End-to-End Deployment tests of each AVM module -6. 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 - diff --git a/docs/content/contributing/_index.md b/docs/content/contributing/_index.md index cda3415..8082ba2 100644 --- a/docs/content/contributing/_index.md +++ b/docs/content/contributing/_index.md @@ -7,15 +7,15 @@ geekdocAnchor: true This section lists all contribution guidance available to module owners and contributors. -- [Process Overview](/Azure-Verified-Modules/contributing/process/) -- [Bicep Contribution Guide](/Azure-Verified-Modules/contributing/bicep/) -- [Terraform Contribution Guide](/Azure-Verified-Modules/contributing/terraform/) -- [Contribution Q&A](/Azure-Verified-Modules/contributing/q-and-a/) -- [Website Contribution Guide](/Azure-Verified-Modules/contributing/website/) +- [Process Overview](/azinsider/contributing/process/) +- [Bicep Contribution Guide](/azinsider/contributing/bicep/) +- [Terraform Contribution Guide](/azinsider/contributing/terraform/) +- [Contribution Q&A](/azinsider/contributing/q-and-a/) +- [Website Contribution Guide](/azinsider/contributing/website/) - [Code of Conduct](https://opensource.microsoft.com/codeofconduct/) {{< hint type=important >}} -If you cannot find guidance for what you need, please let us know via [GitHub Issues](https://github.com/Azure/Azure-Verified-Modules/issues) πŸ‘ +If you cannot find guidance for what you need, please let us know via [GitHub Issues](https://github.com/daveRendon/azinsider/issues) πŸ‘ {{< /hint >}} diff --git a/docs/content/contributing/bicep/_index.md b/docs/content/contributing/bicep/_index.md deleted file mode 100644 index 1867b4b..0000000 --- a/docs/content/contributing/bicep/_index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Bicep Contribution Guide -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocToC: 2 -geekdocCollapseSection: true ---- - -{{< toc >}} - -{{< hint type=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 [Shared Specification](/Azure-Verified-Modules/specs/shared/) and the [Bicep specific](/Azure-Verified-Modules/specs/bicep/) specifications. **ALL AVM modules** (Resource and Pattern modules) **MUST meet the respective requirements described in these specifications**! -{{< /hint >}} - -This section lists AVM's Bicep-specific contribution guidance. - -- [Prerequisites](/Azure-Verified-Modules/contributing/bicep/prerequisites/) -- [Composition](/Azure-Verified-Modules/contributing/bicep/composition/) -- [Bicep contribution flow](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/) diff --git a/docs/content/contributing/bicep/bicep-contribution-flow/_index.md b/docs/content/contributing/bicep/bicep-contribution-flow/_index.md deleted file mode 100644 index aed6136..0000000 --- a/docs/content/contributing/bicep/bicep-contribution-flow/_index.md +++ /dev/null @@ -1,335 +0,0 @@ ---- -title: Bicep Contribution Flow -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -{{< toc >}} - -## High-level contribution flow - -{{< mermaid class="text-center" >}} -flowchart TD -A(1. Setup your Azure test environment) - click A "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#1-setup-your-azure-test-environment" -B(2. Fork the module source repository) - click B "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#2-fork-the-module-source-repository" -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
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 -{{< /mermaid >}} - -## 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. -{{< mermaid class="text-center" >}} -%%{init: { '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 -{{< /mermaid >}} - -{{< hint type=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. - -{{< /hint >}} - -
- -## 1. Setup your Azure test environment - -{{< hint type=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. - -{{< /hint >}} - -AVM tests the deployments in an Azure subscription. To do so, it requires a service principal with access to it. - -In this first step, make sure you - -- 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 Portal)](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) - - [Create a service principal (PowerShell)](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-authenticate-service-principal-powershell) - - [Find Service Principal object ID](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/assign-roles-azure-service-principals#find-your-spn-and-tenant-id) - - [Find managed Identity Service Principal](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-view-managed-identity-service-principal-portal) -- 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 - -
- -## 2. Fork the module source repository - -Bicep AVM Modules (both Resource and Pattern modules) will be homed in the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) repository and live within an `avm` directory that will be located at the root of the repository, as per [SNFR19](/Azure-Verified-Modules/specs/shared/#id-snfr19---category-publishing---registries-targeted). - -Module owners are expected to fork the [`Azure/bicep-registry-modules`](https://github.com/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`](https://github.com/Azure/bicep-registry-modules) repository's `main` branch. - -To do so, simply navigate to the [Public Bicep Registry](https://github.com/Azure/bicep-registry-modules) 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'. - -
- -## 3. Configure your CI environment - -To configure the forked CI environment you have to perform several steps: - -- [3.1 Set up secrets](#31-set-up-secrets) -- [3.2 Enable actions](#32-enable-actions) -- [3.3 Set Read/Write Workflow permissions](#33-set-readwrite-workflow-permissions) - -### 3.1. Set up secrets - -To use the environment's pipelines you should use the information you gathered during the [Azure setup](#1-setup-your-azure-test-environment) to 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. | -| `ARM_SUBSCRIPTION_ID` | `22222222-2222-2222-2222-222222222222` | The ID of the subscription to test-deploy modules in. | -| `ARM_TENANT_ID` | `33333333-3333-3333-3333-333333333333` | The tenant ID of the Azure Active Directory tenant to test-deploy modules in. | -| `AZURE_CREDENTIALS` | `{"clientId": "44444444-4444-4444-4444-444444444444", "clientSecret": "", "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](https://github.com/Azure/login#configure-deployment-credentials). For more information, see the `[Special case: AZURE_CREDENTIALS]` note below. | -| `TOKEN_NAMEPREFIX` | `cntso` | Optional. A short (3-5 character length), unique string that should be included in any deployment to Azure. For more information, see the `[Special case: TOKEN_NAMEPREFIX]` note below. | - -

- -{{< expand "βž• How to: Add a repository secret to GitHub" "expand/collapse" >}} - -1. Navigate to the repository's `Settings`. - -Navigate to settings - -2. 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. - -Navigate to secrets - -3. 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. - -Add secret - -{{< /expand >}} - -

- -{{< hint type=important title="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: - -```JSON -{"clientId": "", "clientSecret": "", "subscriptionId": "", "tenantId": "" } -``` - -**Make sure you create this object as one continuous string as shown above** - using the information you collected during [Step 1](#1-setup-your-azure-test-environment). 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](https://github.com/Azure/login#configure-deployment-credentials). - -{{< /hint >}} - -{{< hint type=note title-="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 multi-module solutions (applications/workloads) based on the modules. - -Each pipeline 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. - -{{< /hint >}} - -### 3.2. Enable actions - -Finally, 'GitHub Actions' are disabled by default and hence, must be enabled first. - -To do so, perform the following steps: - -1. Navigate to the `Actions` tab on the top of the repository page. - -1. Next, select '`I understand my workflows, go ahead and enable them`'. - -Enable Actions - -### 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. - -1. Navigate to the `Settings` tab on the top of your repository page. - -1. Within the section `Code and automation` click on `Actions` and `General` - -1. Make sure to enable `Read and write permissions` - -Workflow Permissions - -
- -{{< hint type=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](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows). - -{{< /hint >}} - -## 4. Implement your contribution - -To implement your contribution, we kindly ask you to first review the [shared](/Azure-Verified-Modules/specs/shared/) & [Bicep-specific](/Azure-Verified-Modules/specs/bicep/) specifications and [composition guidelines](/Azure-Verified-Modules/contributing/bicep/composition/) 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].'`) or leverage the following template: - -{{< expand "βž• Module workflow template" "expand/collapse" >}} - -{{< include file="/static/includes/avm.[res-ptn].workflow.template.yml" language="yaml" options="linenos=false" >}} - -{{< /expand >}} - -{{< hint type=tip >}} - -After any change to a module and before running tests, we highly recommend running the [Set-AVMModule](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/generate-bicep-module-files) utility to update all module files that are auto-generated (e.g., the `main.json` & `readme.md` files). - -{{< /hint >}} - -
- -## 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](/Azure-Verified-Modules/specs/shared/#id-snfr1---category-testing---prescribed-tests), [SNFR2](/Azure-Verified-Modules/specs/shared/#id-snfr2---category-testing---e2e-testing), [SNFR3](/Azure-Verified-Modules/specs/shared/#id-snfr3---category-testing---avm-unit-tests), [SNFR4](/Azure-Verified-Modules/specs/shared/#id-snfr4---category-testing---additional-unit-tests), [SNFR5](/Azure-Verified-Modules/specs/shared/#id-snfr5---category-testing---upgrade-tests), [SNFR6](/Azure-Verified-Modules/specs/shared/#id-snfr6---category-testing---static-analysislinting-tests), [SNFR7](/Azure-Verified-Modules/specs/shared/#id-snfr7---category-testing---idempotency-tests). - -For example, to meet [SNFR2](/Azure-Verified-Modules/specs/shared/#id-snfr2---category-testing---e2e-testing), 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](/Azure-Verified-Modules/specs/bicep/#id-bcprmnfr1---category-testing---expected-test-directories). - -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 - -{{< hint type=tip >}} - -In case your contribution involves changes to a module, you can also optionally leverage the [Validate module locally](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/validate-bicep-module-locally) utility to validate the updated module from your local host before validating it through its pipeline. - -{{< /hint >}} - -### Creating `e2e` tests - -As per [BCPRMNFR1](/Azure-Verified-Modules/specs/bicep/#id-bcprmnfr1---category-testing---expected-test-directories), 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](/Azure-Verified-Modules/specs/bicep/#id-bcpnfr13---category-testing---test-file-metadata), 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-.-${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` - - {{< hint type=important >}} - - As per [BCPNFR12](/Azure-Verified-Modules/specs/bicep/#id-bcpnfr12---category-testing---deployment-test-naming) you must use the header `module testDeployment '../.*main.bicep' =` when invoking the module's template. - - {{< /hint >}} - - {{< hint type=tip >}} - - πŸ“œ [Example of test file](https://github.com/Azure/bicep-registry-modules/blob/main/avm/utilities/tools/helper/src/src.main.test.bicep) - - {{< /hint >}} - -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. - - {{< hint type=tip >}} - - πŸ“œ [Example of test using purge protected Key Vault dependency](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/cognitive-services/account/tests/e2e/system-assigned-cmk-encryption/main.test.bicep#L43) - - {{< /hint >}} - -
- -### Reusable assets - -There are a number of additional scripts and utilities available [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/utilities/e2e-template-assets) 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 `avm/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. - -{{< expand "βž• Diagnostic Settings Dependencies - Bicep File" "expand/collapse" >}} - -{{< include file="/static/includes/diagnostic.dependencies.bicep" language="bicep" options="linenos=false" >}} - -{{< /expand >}} - -
- -## 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: - -1. Provide a meaningful title in the form of _feat: ``_ to align witht the Semantic PR Check. -2. Provide a meaningful description. -3. Follow instructions you find in the PR template. -4. 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. - - Badge dropdown - - In the opening pop-up, you first need to select your branch and then click on the `Copy status badge Markdown` - - Status Badge - - diff --git a/docs/content/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows.md b/docs/content/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows.md deleted file mode 100644 index 19f4c73..0000000 --- a/docs/content/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows.md +++ /dev/null @@ -1,63 +0,0 @@ -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. - ---- - -### _Navigation_ - -- [Location](#location) -- [How it works](#how-it-works) -- [Typical use cases](#typical-use-cases) - - [Disable all but one workflow](#disable-all-but-one-workflow) - - [Disable all but multiple workflows](#disable-all-but-multiple-workflows) - - [Enable all workflows](#enable-all-workflows) -- [Limitations](#limitations) - ---- -# Location - -You can find the script under [`avm/utilities/pipelines/platform/Switch-WorkflowState.ps1)`](https://github.com/Azure/bicep-registry-modules/blob/main/avm/utilities/pipelines/platform/Switch-WorkflowState.ps1) -You can find the workflow under [`.github/workflows/avm.platform.toggle-avm-workflows.yml`](https://github.com/Azure/bicep-registry-modules/blob/main/.github/workflows/platform.toggle-avm-workflows.yml) - -# How it works - -Browse to `Actions` and select the workflow from the list - -Select Toggle Workflows - -Run the workflow `avm.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. - -Run Toggle Workflows - -# Typical use cases - -## Disable all but one workflow -- `Enable or disable workflows` to `Disable` -- `RegEx which workflows are included` to `avm\.(?:res|ptn)` (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)` (this is the default setting) -- `RegEx which workflows are excluded` to `(?:avm.res.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)` (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. - -{{< hint type=important >}} - -The workflow can only be triggered in forks. - -{{< /hint >}} diff --git a/docs/content/contributing/bicep/bicep-contribution-flow/generate-bicep-module-files.md b/docs/content/contributing/bicep/bicep-contribution-flow/generate-bicep-module-files.md deleted file mode 100644 index 2ee1d7c..0000000 --- a/docs/content/contributing/bicep/bicep-contribution-flow/generate-bicep-module-files.md +++ /dev/null @@ -1,48 +0,0 @@ -As per the module design structure ([BCPFR3](/Azure-Verified-Modules/specs/bicep/#id-bcpfr3---category-composition---directory-and-file-structure)), 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. - ---- - -### _Navigation_ - -- [Location](#location) -- [How it works](#how-it-works) -- [How to use it](#how-to-use-it) - ---- -# Location - -You can find the script under [`avm/utilities/tools/Set-AVMModule.ps1`](https://github.com/Azure/bicep-registry-modules/blob/main/avm/utilities/tools/Set-AVMModule.ps1) - -# How it works - -Using the provided template path, the script -1. 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](https://github.com/Azure/bicep-registry-modules/tree/main/avm/utilities/tools/helper/src) -1. compiles its bicep template -1. 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) - 1. 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. - 1. 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. - -{{< hint type=note >}} - -The script must be loaded ('*dot-sourced*') before the function can be invoked. -```PowerShell -. 'C:/dev/Set-AVMModule.ps1' -Set-AVMModule (...) -``` - -{{< /hint >}} diff --git a/docs/content/contributing/bicep/bicep-contribution-flow/owner-contribution-flow.md b/docs/content/contributing/bicep/bicep-contribution-flow/owner-contribution-flow.md deleted file mode 100644 index 95a9f9a..0000000 --- a/docs/content/contributing/bicep/bicep-contribution-flow/owner-contribution-flow.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Owner Contribution Flow -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -This section describes the contribution flow for module owners who are responsible for creating and maintaining Bicep Modules. - -{{< toc >}} - -{{< hint type=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](/Azure-Verified-Modules/contributing/process/), [Shared Specifications](/Azure-Verified-Modules/specs/shared/) (including [Interfaces](/Azure-Verified-Modules/specs/shared/interfaces/)) and [Bicep-specific](/Azure-Verified-Modules/specs/bicep/) specifications 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. - -{{< /hint >}} - ---- - -## 1. Owner Activities and Responsibilities - -Familiarise yourself with the responsibilities as **Module Owner** outlined in [Team Definitions & RACI](/Azure-Verified-Modules/specs/shared/team-definitions/#module-owners) and [Module Owner Responsibilities](/Azure-Verified-Modules/help-support/issue-triage/brm-issue-triage/#module-owner-responsibilities) in the [BRM Issue Triage](/Azure-Verified-Modules/help-support/issue-triage/brm-issue-triage/). - -1. Create GitHub teams as outlined in [SNFR20](/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only) and add respective parent teams: - -Segments: - -- `avm-res---module-owners-bicep` -- `avm-res---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---module-owners-bicep` team. - -Only fulltime Microsoft employees can be added at this time. - -{{< hint type=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. -{{< /hint >}} - -2. Add teams to `CODEOWNERS` file as outlined in [SNFR20](/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only). -3. 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. -4. Ensure that the module(s) you own are compliant with the AVM specifications and are working as expected. While all specifications are to be followed, pay special attention to the following ones as in these, the `Owner` is mentioned explicitly: -| ID | Specification -|---------------|-----------------------| -| [SFR1](/Azure-Verified-Modules/specs/shared/#id-sfr1---category-composition---preview-services) | Composition - Preview Services | -| [SNFR2](/Azure-Verified-Modules/specs/shared/#id-snfr2---category-testing---e2e-testing) | Testing - E2E Testing | -| [SNFR3](/Azure-Verified-Modules/specs/shared/#id-snfr3---category-testing---avm-compliance-tests) | Testing - AVM Compliance Tests | -| [SNFR8](/Azure-Verified-Modules/specs/shared/#id-snfr8---category-contributionsupport---module-owners-github) | Contribution/Support - Module Owner(s) GitHub | -| [SNFR11](/Azure-Verified-Modules/specs/shared/#id-snfr11---category-contributionsupport---issues-response-times) | Contribution/Support - Issues Response Times | -| [SNFR12](/Azure-Verified-Modules/specs/shared/#id-snfr12---category-contributionsupport---versions-supported) | Contribution/Support - Versions Supported | -| [SNFR17](/Azure-Verified-Modules/specs/shared/#id-snfr17---category-release---semantic-versioning) | Release - Semantic Versioning | -| [SNFR20](/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only) | Contribution/Support - GitHub Teams Only | -| [SNFR21](/Azure-Verified-Modules/specs/shared/#id-snfr21---category-publishing---cross-language-collaboration) | Publishing - Cross Language Collaboration | -| [SNFR24](/Azure-Verified-Modules/specs/shared/#id-snfr24---category-testing---testing-child-extension--interface-resources) | Testing - Testing Child, Extension & Interface Resources | -| [SNFR25](/Azure-Verified-Modules/specs/shared/#id-snfr25---category-composition---resource-naming) | Composition - Resource Naming | -| [RMNFR3](/Azure-Verified-Modules/specs/shared/#id-rmnfr3---category-composition---rp-collaboration) | Composition - RP Collaboration | -| [RMFR4](/Azure-Verified-Modules/specs/shared/#id-rmfr4---category-composition---avm-consistent-feature--extension-resources-value-add) | Composition - AVM Consistent Feature & Extension Resources Value Add | -| [RMFR7](/Azure-Verified-Modules/specs/shared/#id-rmfr7---category-outputs---minimum-required-outputs) | Outputs - Minimum Required Outputs | - -5. Watch Pull Request (PR) activity for your module(s) in the [BRM](https://github.com/Azure/bicep-registry-modules) 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](/Azure-Verified-Modules/specs/shared/#id-snfr11---category-contributionsupport---issues-response-times). -6Γ₯. Watch AVM module issue and AVM question/feedback activity for your module(s) in the [BRM](https://github.com/Azure/bicep-registry-modules) 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](/Azure-Verified-Modules/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-orphaned). - ---- - -## 3. Adopting an Orphaned Module - -When adopting an orphaned module the [when-a-new-owner-is-identified](/Azure-Verified-Modules/help-support/issue-triage/avm-issue-triage/#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](https://github.com/settings/notifications) while logged in with your GitHub account. - -GitHub Notifications Settings Page. - -1. Ensure your **Default Notifications Email** address is set to the email address you intend to use. -2. (Optional) If you would like to automatically watch repositories that you are active in, ensure **Automatically watch repositories** is set to "On." -3. (**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." -4. (**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. -5. (**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](https://github.com/Azure/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.** - -{{< hint type=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). - -{{< /hint >}} - -GitHub Notifications Page. - -### 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. - -{{< hint type=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. - -{{< /hint >}} - -| 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](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#filtering-email-notifications). - ---- - -## 5. Contribution Checklist - -This checklist can be used in the development of AVM Bicep Modules. - -1. Before beginning any work a new module a valid [Issue: New AVM Module Proposal](https://github.com/Azure/Azure-Verified-Modules/issues/new?assignees=&labels=Type%3A+New+Module+Proposal+%3Abulb%3A%2CNeeds%3A+Triage+%3Amag%3A&projects=Azure%2F529&template=module_proposal.yml&title=%5BModule+Proposal%5D%3A+%60MODULE_NAME_BETWEEN_BACKTICKS%60) 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. -2. Fork the bicep-registry-modules [BRM](https://github.com/Azure/bicep-registry-modules) repository. If you use an existing fork, ensure it's up to date with origin/BRM. - - - Ensure all workflows are [disabled by default](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows/) once you forked the BRM repo, to prevent any accidental deployments into your Azure test environment resulted by an automated deployment. - -3. Create a new branch from your forked repository to develop your module. -4. If you're working on a new module you have to create its corresponding workflow file (see [here](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#4-implement-your-contribution)). - - - 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](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows/) to run your e2e tests. - -5. [Implement your contribution](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#4-implement-your-contribution). -6. [Create, update, and run tests](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#5-createupdate-and-run-tests). - - - In addition to testing your module via GitHub pipeline, you can also [test-locally](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/validate-bicep-module-locally/). The following helper script facilitates local testing. - - {{< expand "βž• Local Test Helper Script" "expand/collapse" >}} - - {{< include file="/static/scripts/sample-localtest-helper.ps1" language="powershell" options="linenos=false" >}} - - {{< /expand >}} - -7. Create a PR and reference the status badge of your pipeline run - [see here](/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#6-create-a-pull-request-to-the-public-bicep-registry). -8. After a pull request has been created, it is important to update the [AVM module proposal](https://aka.ms/AVM/ModuleProposals) 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. -9. Once your BRM pull request has been approved and merged into main update the [AVM module proposal](https://aka.ms/AVM/ModuleProposals) 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. diff --git a/docs/content/contributing/bicep/bicep-contribution-flow/validate-bicep-module-locally.md b/docs/content/contributing/bicep/bicep-contribution-flow/validate-bicep-module-locally.md deleted file mode 100644 index cf2e336..0000000 --- a/docs/content/contributing/bicep/bicep-contribution-flow/validate-bicep-module-locally.md +++ /dev/null @@ -1,43 +0,0 @@ -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. - ---- - -### _Navigation_ - -- [Location](#location) -- [How it works](#how-it-works) -- [How to use it](#how-to-use-it) - ---- -# Location - -You can find the script under [`avm/utilities/tools/Test-ModuleLocally.ps1`](https://github.com/Azure/bicep-registry-modules/blob/main/avm/utilities/tools/Test-ModuleLocally.ps1) - -# How it works - -If the switch for Pester tests (`-PesterTest`) is provided the script will -1. 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 -1. 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. -1. 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'. -1. If the `-ValidationTest` parameter was set, it runs a deployment validation using the `Test-TemplateDeployment` script. -1. If the `-DeploymentTest` parameter was set, it runs a deployment using the `New-TemplateDeployment` script (with no retries). -1. 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. - -{{< hint type=note >}} - -The script must be loaded ('*dot-sourced*') before the function can be invoked. -```PowerShell -. 'C:/dev/Test-ModuleLocally.ps1' -Test-ModuleLocally (...) -``` - -{{< /hint >}} diff --git a/docs/content/contributing/bicep/composition.md b/docs/content/contributing/bicep/composition.md deleted file mode 100644 index 12d9e72..0000000 --- a/docs/content/contributing/bicep/composition.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Composition -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -{{< toc >}} - - - -{{< hint type=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 [Shared Specification](/Azure-Verified-Modules/specs/shared/) and the [Bicep specific](/Azure-Verified-Modules/specs/bicep/) specifications. **ALL AVM modules** (Resource and Pattern modules) **MUST meet the respective requirements described in these specifications**! -{{< /hint >}} - -## Composition - -{{< hint type=important >}} - -Before jumping on implementing your contribution, please review the AVM Module specifications, in particular the [Shared](/Azure-Verified-Modules/specs/shared/) and the [Bicep specific](/Azure-Verified-Modules/specs/bicep/) pages, to make sure your contribution complies with the AVM module's design and principles. - -{{< /hint >}} - -
- -### Directory and File Structure - -Each Bicep AVM module that lives within the [`Azure/bicep-registry-modules`](https://github.com/Azure/bicep-registry-modules) 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) - -#### Example Directory and File Structure within `Azure/bicep-registry-modules` Repository - -```txt -/ 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... -``` - -
- -### Code Styling - -This section points to conventions to be followed when developing a Bicep template. - -
- -#### Casing - -Use `camelCasing` as per [BCPNFR8](/Azure-Verified-Modules/specs/bicep/#id-bcpnfr8---category-composition---code-styling---lower-camelcasing). - ---- - -#### Input Parameters and Variables - -Make sure to review all specifications of `Category: Inputs` within both the [Shared](/Azure-Verified-Modules/specs/shared/) and the [Bicep specific](/Azure-Verified-Modules/specs/bicep/) pages. - -{{< hint type=tip >}} -See examples in specifications [SNFR14](/Azure-Verified-Modules/specs/shared/#id-snfr14---category-inputs---data-types) and [BCPNFR1](/Azure-Verified-Modules/specs/bicep/#id-bcpnfr1---category-inputs---data-types). -{{< /hint >}} - ---- - -#### 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. - -{{< hint type=tip >}} -See examples in specifications [SFR1](/Azure-Verified-Modules/specs/shared/#id-sfr1---category-composition---preview-services) and [RMFR1](/Azure-Verified-Modules/specs/shared/#id-rmfr1---category-composition---single-resource-only). -{{< /hint >}} - ---- - -#### 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. - -{{< hint type=tip >}} -See examples in specifications [BCPFR1](/Azure-Verified-Modules/specs/bicep/#id-bcpfr1---category-composition---cross-referencing-modules) for resource modules and [PMNFR2](//Azure-Verified-Modules/specs/shared/#id-pmnfr2---category-composition---use-resource-modules-to-build-a-pattern-module) for pattern modules. -{{< /hint >}} - ---- - -#### Outputs - -Make sure to review all specifications of `Category: Outputs` within both the [Shared](/Azure-Verified-Modules/specs/shared/) and the [Bicep specific](/Azure-Verified-Modules/specs/bicep/) pages. - -{{< hint type=tip >}} -See examples in specification [RMFR7](/Azure-Verified-Modules/specs/shared/#id-rmfr7---category-outputs---minimum-required-outputs). -{{< /hint >}} - ---- - -
- -### Interfaces - -{{< hint type=note >}} - -This section is only relevant for contributions to resource modules. - -{{< /hint >}} - -To meet [RMFR4](/Azure-Verified-Modules/specs/shared/#id-rmfr4---category-composition---avm-consistent-feature--extension-resources-value-add) and [RMFR5](/Azure-Verified-Modules/specs/shared/#id-rmfr5---category-composition---avm-consistent-feature--extension-resources-value-add-interfacesschemas) 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 [Shared Interfaces](/Azure-Verified-Modules/specs/shared/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. - -
diff --git a/docs/content/contributing/bicep/prerequisites.md b/docs/content/contributing/bicep/prerequisites.md deleted file mode 100644 index e96a7ff..0000000 --- a/docs/content/contributing/bicep/prerequisites.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Prerequisites -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -{{< toc >}} - -## GitHub Account Link and Access - -You need to have a personal GitHub account which is [linked](https://aka.ms/LinkYourGitHubAccount) to your Microsoft corporate identity. Once the link step is complete you must join the [Azure](https://repos.opensource.microsoft.com/orgs/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 - -- [Deploy and manage resources in Azure by using Bicep](https://learn.microsoft.com/learn/paths/bicep-deploy/) -- [Structure your Bicep code for collaboration](https://learn.microsoft.com/learn/modules/structure-bicep-code-collaboration/) -- [Manage changes to your Bicep code by using Git](https://learn.microsoft.com/learn/modules/manage-changes-bicep-code-git/) - -### Git - -- [Introduction to version control with Git](https://learn.microsoft.com/learn/paths/intro-to-vc-git/) - -
- -## Tooling - -### Required Tooling - -To contribute to this project the following tooling is required: - -- [Git](https://git-scm.com/downloads) - - If just installed, don't forget to set both your git username & password - - ```PowerShell - git config --global user.name "John Doe" - git config --global user.email "johndoe@example.com" - ``` - -- [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#install-manually) - - {{< hint type=note >}} - - Must be manually kept up-to-date. - - {{< /hint >}} - -- [Pester](https://pester.dev/docs/introduction/installation) -- [Visual Studio Code](https://code.visualstudio.com/download) - - [Bicep extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep) - -### 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](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) -- [ARM Tools extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=msazurermtools.azurerm-vscode-tools) -- [ARM Template Viewer extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=bencoleman.armview) -- [PSRule extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode) -- [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) -- 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](https://desktop.github.com/) - - 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. - -
diff --git a/docs/content/contributing/process.md b/docs/content/contributing/process.md deleted file mode 100644 index 8a5dfc0..0000000 --- a/docs/content/contributing/process.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Process Overview -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -{{< toc >}} - -This page provides an overview of the contribution process for AVM modules. - -## New Module Proposal & Creation - -{{< hint type=important >}} - -Each AVM module **MUST** have a [Module Proposal](https://aka.ms/AVM/ModuleProposal) issue created and approved by the AVM core team before it can be created/migrated! - -{{< /hint >}} - - -{{< mermaid class="text-center" >}} -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{Does the module already
exist in an active/orphaned
state in respective index?} - IndexExistenceCheck -->|No|A - IndexExistenceCheck -->|Yes|EndExistenceCheck(Review existing/proposed AVM module) - EndExistenceCheck -->OrphanedCheck{> Is the module orphaned? <} - click OrphanedCheck "/Azure-Verified-Modules/specs/shared/module-lifecycle/#orphaned-avm-modules" - OrphanedCheck -->|No|ContactOwner[Contact module owner,
via GitHub issues on the related
repo, to discuss enhancements/
bugs/opportunities to contribute etc.] - OrphanedCheck -->|Yes|OrphanOwnerYes(Locate the related issue
and comment on:
- A feature/enhancement suggestion
- 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 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
> 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 "https://aka.ms/avm/snfr3" - G -->|Tests Fail|I(Modules/Tests Fixed
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 to be resolved
before 1.0.0 release?

> ! Read the AVM preview notice ! <} - 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/" -{{< /mermaid >}} - -## AVM Preview Notice - -{{< hint type=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. - -{{< /hint >}} - -## 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: - -{{< hint type=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.) - -{{< /hint >}} - -1. Create a [GitHub Issue](https://github.com/Azure/Azure-Verified-Modules/issues/new/choose) -2. Discuss the issue/blocker with the AVM core team -3. Agree upon action/resolution/closure -4. Implement agreed upon action/resolution/closure - -{{< hint type=note >}} - -Please note for module specific issues, these should be logged in the module's source repository, not the AVM repository. - -{{< /hint >}} diff --git a/docs/content/contributing/q-and-a.md b/docs/content/contributing/q-and-a.md deleted file mode 100644 index 6fea3c4..0000000 --- a/docs/content/contributing/q-and-a.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: Contribution Q&A -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true - -geekdocToC: 1 ---- - -{{< toc >}} - -{{< hint type=tip >}} - -Check out the [FAQ](/Azure-Verified-Modules/faq/) for more answers to common questions about the AVM initiative in general. - -{{< /hint >}} - -## 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][ModuleProposal]. - ---- - -### 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][ModuleSpecifications] 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][ModuleSpecifications] and your modules **SHOULD** be [WAF aligned][WAFAligned]. - - 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][DiagnosticSettings] 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][AzureArchitectureCenter], 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][WAFAligned]. - - 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][ALZ]. 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][AVMCoreTeam] maintains the list of [Bicep][BicepModules] and [Terraform][TFModules] 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][ModuleIndexes] 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][ModuleOwners] and **MAY** have additional [module contributors][ModuleContributors]. - -Essentially, you have 3 options: - -1. You sign up to be a module owner (and optionally, you can find additional contributors to help you). -2. You find / request someone else to be the module owner (and optionally, you can be a contributor). -3. 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][ModuleProposal]. - ---- - -### 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][ModuleSupport] 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][AVMCoreTeam] 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][ModuleOwners]. - ---- - -### 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][ModuleProposal] 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][ModuleProposal], you can reach out to the AVM core team directly via [Teams][AVMChannel] 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][ModuleOwners]. - - - -
- -## 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][ModuleSpecifications] and [contribution guides][ModuleContributors]: - -- [Bicep contribution guide][BicepContributios] -- [Terraform contribution guide][TerrafromContribution] - -Feel free to reach out to the [AVM Core team][AVMCoreTeam] 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][ProcessOverview], 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][GitHubLicensing]. 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)][MandatoryLabels]. - -You **SHOULD NOT** use any additional labels. - -There is also a [PowerShell script][MandatoryLabels] that the [AVM core team][AVMCoreTeam] 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][ModuleSpecifications] covers all naming conventions. As example: - [Module naming specification][ModuleNaming] - - - ---- - -### 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][BicepDir]. - -#### 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.][TerraformDir] - ---- - -### 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](https://repos.opensource.microsoft.com/orgs/Azure/repos?q=), 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 router to module owner that **MUST** respond to logged issues within 3 business days. In case that module currently don't have owner, [AVM Core Team][AVMCoreTeam] will handle request. - ---- - -### I am using module without owner. What will happened if I need update? - -[AVM core team][AVMCoreTeam] 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][ModuleSupport] chapter . - -[AVMCoreTeam]: /Azure-Verified-Modules/specs/shared/team-definitions/#avm-core-team -[BicepModules]: /Azure-Verified-Modules/indexes/bicep/ -[TFModules]: /Azure-Verified-Modules/indexes/terraform/ -[ModuleOwners]: /Azure-Verified-Modules/specs/shared/team-definitions/#module-owners -[ModuleContributors]: /Azure-Verified-Modules/specs/shared/team-definitions/#module-contributors -[WAFAligned]: /Azure-Verified-Modules/faq/#what-does-avm-mean-by-waf-aligned -[ModuleProposal]: https://aka.ms/AVM/ModuleProposal -[ModuleSupport]: /Azure-Verified-Modules/help-support/module-support/ -[AVMChannel]: https://aka.ms/AVM/channel -[ModuleSpecifications]: /Azure-Verified-Modules/specs/ -[DiagnosticSettings]: /Azure-Verified-Modules/specs/shared/interfaces/#diagnostic-settings -[AzureArchitectureCenter]: https://learn.microsoft.com/en-us/azure/architecture/browse/ -[ALZ]: https://aka.ms/alz -[ModuleIndexes]: /Azure-Verified-Modules/indexes/ -[MandatoryLabels]: /Azure-Verified-Modules/specs/shared/#id-snfr23---category-contributionsupport---github-repo-labels -[BicepDir]: /Azure-Verified-Modules/contributing/bicep/#directory-and-file-structure -[TerraformDir]: /Azure-Verified-Modules/contributing/terraform/#repositories -[BicepContributios]: /Azure-Verified-Modules/contributing/bicep/ -[TerrafromContribution]: /Azure-Verified-Modules/contributing/terraform/ -[ModuleNaming]: /Azure-Verified-Modules/specs/shared/#id-rmnfr1---category-naming---module-naming -[ProcessOverview]: /Azure-Verified-Modules/contributing/process/ -[GitHubLicensing]: https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository diff --git a/docs/content/contributing/terraform/_index.md b/docs/content/contributing/terraform/_index.md deleted file mode 100644 index 11ba227..0000000 --- a/docs/content/contributing/terraform/_index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Terraform Contribution Guide -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocToC: 2 -geekdocCollapseSection: true ---- - -{{< toc >}} - -{{< hint type=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 [Shared Specification](/Azure-Verified-Modules/specs/shared/) and the [Terraform specific](/Azure-Verified-Modules/specs/terraform/) specifications. **ALL AVM modules** (Resource and Pattern modules) **MUST meet the respective requirements described in these specifications**! -{{< /hint >}} - -This section lists AVM's Terraform-specific contribution guidance. - -- [Prerequisites](/Azure-Verified-Modules/contributing/terraform/prerequisites/) -- [Composition](/Azure-Verified-Modules/contributing/terraform/composition/) -- [Terraform contribution flow](/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/) diff --git a/docs/content/contributing/terraform/composition.md b/docs/content/contributing/terraform/composition.md deleted file mode 100644 index 26ca752..0000000 --- a/docs/content/contributing/terraform/composition.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -title: Composition -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -{{< toc >}} - -{{< hint type=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 [Shared Specification](/Azure-Verified-Modules/specs/shared/) and the [Terraform specific](/Azure-Verified-Modules/specs/terraform/) specifications. **ALL AVM modules** (Resource and Pattern modules) **MUST meet the respective requirements described in these specifications**! -{{< /hint >}} - -{{< hint type=important >}} - -Before jumping on implementing your contribution, please review the AVM Module specifications, in particular the [Shared](/Azure-Verified-Modules/specs/shared/) and the [Terraform specific](/Azure-Verified-Modules/specs/terraform/) pages, to make sure your contribution complies with the AVM module's design and principles. - -{{< /hint >}} - -
- ---- - -
- -## Repositories - -Each Terraform AVM module will have its own GitHub Repository in the [`Azure` GitHub Organization](https://github.com/Azure) as per [SNFR19](/Azure-Verified-Modules/specs/shared/#id-snfr19---category-publishing---registries-targeted). - -This repo will be created by the Module Owners and the AVM Core team collaboratively, including the configuration of permissions as per [SNFR9](/Azure-Verified-Modules/specs/shared/#id-snfr9---category-contributionsupport---avm--pg-teams-github-repo-permissions) - -
- ---- - -
- -## Directory and File Structure - -Below is the directory and file structure expected for each AVM Terraform repository/module. -See template repo [here](https://github.com/Azure/terraform-azurerm-avm-template). - -- `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) - - `defaults` - (minimum/required parameters/variables only, heavy reliance on the default values for other parameters/variables) - - `` -- `/...` - (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` - - `locals.version.tf.json` - (required for telemetry, should match the upcoming release tag) - - `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 - -```txt -/ 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/ -β”‚ β”œβ”€β”€β”€default/ -β”‚ β”‚ β”œβ”€β”€β”€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.telemetry.tf -β”œβ”€β”€β”€locals.tf -β”œβ”€β”€β”€locals.version.tf.json -β”œβ”€β”€β”€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](/Azure-Verified-Modules/specs/terraform/#id-tfnfr4---category-composition---code-styling---lower-snake_casing). - -
- ---- - -
- -### Input Parameters and Variables - -Make sure to review all specifications of `Category: Inputs` within both the [Shared](/Azure-Verified-Modules/specs/shared/) and the [Terraform specific](/Azure-Verified-Modules/specs/terraform/) pages. - -{{< hint type=tip >}} -See examples in specifications [SNFR14](/Azure-Verified-Modules/specs/shared/#id-snfr14---category-inputs---data-types) and [TFFR14](/Azure-Verified-Modules/specs/terraform/#id-tffr14---category-inputs---no-enabled-or-module_depends_on-variable). -{{< /hint >}} - -
- ---- - -
- -### 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. - -{{< hint type=tip >}} -See examples in specifications [SFR1](/Azure-Verified-Modules/specs/shared/#id-sfr1---category-composition---preview-services) and [RMFR1](/Azure-Verified-Modules/specs/shared/#id-rmfr1---category-composition---single-resource-only). -{{< /hint >}} - -
- ---- - -
- -### Outputs - -Make sure to review all specifications of `Category: Outputs` within both the [Shared](/Azure-Verified-Modules/specs/shared/) and the [Terraform specific](/Azure-Verified-Modules/specs/terraform/) pages. - -{{< hint type=tip >}} -See examples in specification [RMFR7](/Azure-Verified-Modules/specs/shared/#id-rmfr7---category-outputs---minimum-required-outputs) and [TFFR2](/Azure-Verified-Modules/specs/terraform/#id-tffr2---category-outputs---additional-terraform-outputs). -{{< /hint >}} - -
- ---- - -
- -## Interfaces - -{{< hint type=note >}} - -This section is only relevant for contributions to resource modules. - -{{< /hint >}} - -To meet [RMFR4](/Azure-Verified-Modules/specs/shared/#id-rmfr4---category-composition---avm-consistent-feature--extension-resources-value-add) and [RMFR5](/Azure-Verified-Modules/specs/shared/#id-rmfr5---category-composition---avm-consistent-feature--extension-resources-value-add-interfacesschemas) 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 [Shared Interfaces](/Azure-Verified-Modules/specs/shared/interfaces/) page. - -
- ---- - -
- -## Telemetry - -To meet [SFR3](/Azure-Verified-Modules/specs/shared/#id-sfr3---category-telemetry---deploymentusage-telemetry) & [SFR4](/Azure-Verified-Modules/specs/shared/#id-sfr4---category-telemetry---telemetry-enablement-flexibility). -We have provided the sample code below, however it is already included in the [template repository](https://github.com/Azure/terraform-azurerm-avm-template). - -{{< include file="/static/includes/sample.telem.tf" language="terraform" options="linenos=false" >}} - -In addition, you should use a `locals.version.tf.json` file to store the module version in a machine readable format: - -{{< hint type=important >}} - -Do not include the `v` prefix in the `module_version` value. - -{{< /hint >}} - -```json -{ - "locals": { - "module_version": "1.0.0" - } -} -``` - -
- ---- - -
- -## 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. - -```hcl -# In variables.tf... -variable "wait_for_rbac_before_foo_operations" { - type = object({ - create = optional(string, "30s") - destroy = optional(string, "0s") - }) - default = {} - description = < 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 - ] - # ... -} -``` - -
- ---- - -
diff --git a/docs/content/contributing/terraform/prerequisites.md b/docs/content/contributing/terraform/prerequisites.md deleted file mode 100644 index ccaf1d9..0000000 --- a/docs/content/contributing/terraform/prerequisites.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Prerequisites -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -{{< toc >}} - -## GitHub Account Link and Access - -To contribute to this project, you need to have a GitHub account which is [linked](https://repos.opensource.microsoft.com/link) to your Microsoft corporate identity account and be a member of the [Azure](https://repos.opensource.microsoft.com/orgs/Azure) organisation. - -## Tooling - -### Required Tooling - -{{< hint type=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. - -{{< /hint >}} - -To contribute to this project the following tooling is required: - -- [Git](https://git-scm.com/downloads) - - If just installed, don't forget to set both your git username & password - - ```PowerShell - git config --global user.name "John Doe" - git config --global user.email "johndoe@example.com" - ``` - -- [Terraform](https://developer.hashicorp.com/terraform/downloads?product_intent=terraform) -- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) -- [Visual Studio Code](https://code.visualstudio.com/download) - - [Terraform extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=hashicorp.terraform) - - [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) -- [Docker](https://www.docker.com/pricing/#/download) - - [Azure Verified Terraform Scaffold](https://github.com/Azure/tfmod-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)](https://go.dev/doc/install) -- [tfenv](https://github.com/tfutils/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](https://marketplace.visualstudio.com/items?itemName=golang.go) -- For visibility of Bracket Pairs: - - Inside Visual Studio Code, add `editor.bracketPairColorization.enabled`: true to your `settings.json`, to enable bracket pair colorization. - -
- ---- - -
diff --git a/docs/content/contributing/terraform/terraform-contribution-flow/_index.md b/docs/content/contributing/terraform/terraform-contribution-flow/_index.md deleted file mode 100644 index 6c7dc04..0000000 --- a/docs/content/contributing/terraform/terraform-contribution-flow/_index.md +++ /dev/null @@ -1,283 +0,0 @@ ---- -title: Terraform Contribution Flow -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -{{< toc >}} - -## High-level contribution flow - -{{< mermaid class="text-center" >}} -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 Checks
succesful?} - 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 -{{< /mermaid >}} - -
- ---- - -
- -## 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. - -{{< mermaid class="text-center" >}} -%%{init: { '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 -{{< /mermaid >}} - -{{< hint type=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. - -Upstream to fork and source repository. - -{{< /hint >}} - -
- ---- - -
- - - -{{< hint type=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. - -{{< /hint >}} - -## Prepare your developer environment - -### 1. Fork the module source repository - -{{< hint type=important >}} - -Each Terraform AVM module will have its own GitHub repository in the [`Azure`](https://github.com/Azure) GitHub Organization as per [SNFR19](/Azure-Verified-Modules/specs/shared/#id-snfr19---category-publishing---registries-targeted). - -This repository will be created by the Module owners and the AVM Core team collaboratively, including the configuration of permissions as per [SNFR9](/Azure-Verified-Modules/specs/shared/#id-snfr9---category-contributionsupport---avm--pg-teams-github-repo-permissions) - -{{< /hint >}} - -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'. - -{{< hint type=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](/Azure-Verified-Modules/indexes/terraform/tf-resource-modules/) 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. - -{{< /hint >}} - -
- ---- - -
- -### 2. Prepare your Azure test environment - -AVM performs end-to-end (e2e) test dpeloyments 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. - -1. 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)](https://learn.microsoft.com/en-us/cli/azure/azure-cli-sp-tutorial-1) - _**Recommended**_ - - [Create a service principal (Azure Portal)](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) - - [Create a service principal (PowerShell)](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-authenticate-service-principal-powershell) - - [Find Service Principal object ID](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/assign-roles-azure-service-principals#find-your-spn-and-tenant-id) - - [Find managed Identity Service Principal](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-view-managed-identity-service-principal-portal) - - Note down the following pieces of information - - Application (Client) ID - - Service Principal Secret (password) - - **Optional:** Tenant ID - - **Optional:** Subscription ID - - ```bash - # Linux/MacOs - export ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) # or set - export ARM_TENANT_ID=$(az account show --query tenantId --output tsv) # or set - export ARM_CLIENT_ID= - export ARM_CLIENT_SECRET= - - # Windows/Powershell - $env:ARM_SUBSCRIPTION_ID = $(az account show --query id --output tsv) # or set - $env:ARM_TENANT_ID = $(az account show --query tenantId --output tsv) # or set - $env:ARM_CLIENT_ID = "" - $env:ARM_CLIENT_SECRET = "" - ``` - -2. 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. - - Pull latest azterraform container image. - -
- ---- - -
- -### 3. Implement your contribution - -To implement your contribution, we kindly ask you to first review the [shared](/Azure-Verified-Modules/specs/shared/) & [Terraform-specific](/Azure-Verified-Modules/specs/terraform/) specifications and [composition guidelines](/Azure-Verified-Modules/contributing/bicep/terraform/) in particular to make sure your contribution complies with the repository's design and principles. - -
- ---- - -
- -### 4. Run Pre-commit Checks - -{{< hint type=important >}} - -Make sure you have **Docker** installed and running on your machine. - -{{< /hint >}} - -{{< hint type=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](https://github.com/Azure/terraform-azurerm-avm-template/blob/main/avm) script available distributed to all repositories via [`terraform-azurerm-avm-template`](https://github.com/Azure/terraform-azurerm-avm-template) which combines all scripts from the [avm_scripts](https://github.com/Azure/tfmod-scaffold/tree/main/avm_scripts) folder in the [tfmod-scaffold](https://github.com/Azure/tfmod-scaffold/) repository using [avmmakefile](https://github.com/Azure/tfmod-scaffold/blob/main/avmmakefile). - -The avm script also makes sure to pull the latest `mcr.microsoft.com/azterraform:latest` container image before executing any command. - -{{< /hint >}} - -#### 4.1. Run pre-commit and pr-check - -The following commands will run all pre-commit checks and the pr-check. - -```bash -# 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: - -{{< hint type=note >}} - -With the help of the [avm](https://github.com/Azure/terraform-azurerm-avm-template/blob/main/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. - -{{< /hint >}} - -1. Run e2e tests with the help of the azterraform docker container image. - - ```bash - # 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= -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= -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 `` and `` with the values of your service principal as well as `` (e.g. `default`) with the name of the example folder you want to run e2e tests for. - -2. 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, open a PR from your forked repository to the original Terraform Module repository. Make sure you: - -1. Include/Add [`@Azure/avm-core-team-technical-terraform`](https://github.com/orgs/Azure/teams/avm-core-team-technical-terraform) as a reviewer. -2. Make sure all Pull Requst Checks (e2e tests with all examples, linting and version-check) are passing. -3. Watch comments from the PR checks and reviewers (Module owner or AVM core team) and address them accordingly. -4. Once your PR is approved, merge it into the upstream repository and the Module owner will publish the module to the HashiCorp Terraform Registry. - -
- ---- - -
- -### 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](https://github.com/Azure/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 -- Consider updating version to `0.1.0` as the first version that would be published into the terraform registry per spec [SNFR17](/Azure-Verified-Modules/specs/shared/#id-snfr17---category-release---semantic-versioning) -- Set `prevent_deletion_if_contains_resources` to `false` in provider block in example code per spec [TFNFR36](/Azure-Verified-Modules/specs/terraform/#id-tfnfr36---category-code-style---example-code-must-set-prevent_deletion_if_contains_resources-to-false-in-provider-block) -- The `Contributor` and `Owner` teams are not added to the repository per spec [SNFR20](/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only) -- `\_header.md` needs to be updated -- `readme.md` needs to be generated as per spec [SNFR15](/Azure-Verified-Modules/specs/shared/#id-snfr15---category-documentation---automatic-documentation-generation) & [TFNFR2](/Azure-Verified-Modules/specs/terraform/#id-tfnfr2---category-documentation---module-documentation-generation) -- `support.md` needs to be updated -- `locals.telemetry.tf` needs to be updated -- Define outputs like Resource Name, ID and Object in `outputs.tf` per specs [RMFR7](/Azure-Verified-Modules/specs/shared/#id-rmfr7---category-outputs---minimum-required-outputs) & [TFFR2](/Azure-Verified-Modules/specs/terraform/#id-tffr2---category-outputs---additional-terraform-outputs) -- Consider setting a constraint on maximum major version of Provider per spec [TFNFR26](/Azure-Verified-Modules/specs/terraform/#id-tfnfr26---category-code-style---provider-version-constraint-must-have-a-constraint-on-maximum-major-version) in `terraform.tf` flle -- Exclude `terraform.tfvars` file from the repository -- Make sure to have all interfaces defined as per spec [RMFR5](/Azure-Verified-Modules/specs/shared/#id-rmfr5---category-composition---avm-consistent-feature--extension-resources-value-add-interfacesschemas) -- Declaration of provider in module should be as per spec [TFNFR27](/Azure-Verified-Modules/specs/terraform/#id-tfnfr27---category-code-style---declaration-of-a-provider-in-the-module) in `main.tf` -- `CODEOWNERS` file needs to be updated as per spec [SNFR9](/Azure-Verified-Modules/specs/shared/#id-snfr9---category-contributionsupport---avm--pg-teams-github-repo-permissions) & [SNFR20](/Azure-Verified-Modules/specs/shared/#codeowners-file) -- The module is WAF Aligned as per spec [SFR2](/Azure-Verified-Modules/specs/shared/#id-sfr2---category-composition---waf-aligned) -- Availability Zones are used (zonal or zone-redundant where applicable) as per spec [SFR5](/Azure-Verified-Modules/specs/shared/#id-sfr5---category-composition---availability-zones) -- Cross-reagion replication (data redundancy) used where applicable as per spec [SFR6](/Azure-Verified-Modules/specs/shared/#id-sfr6---category-composition---data-redundancy) -- Cross-language collaboration as per spec [SNFR21](/Azure-Verified-Modules/specs/shared/#id-snfr21---category-publishing---cross-language-collaboration) -- RP/PG collaboration as per [RMNFR3](/Azure-Verified-Modules/specs/shared/#id-rmnfr3---category-composition---rp-collaboration) diff --git a/docs/content/contributing/terraform/terraform-contribution-flow/owner-contribution-flow.md b/docs/content/contributing/terraform/terraform-contribution-flow/owner-contribution-flow.md deleted file mode 100644 index 55cb778..0000000 --- a/docs/content/contributing/terraform/terraform-contribution-flow/owner-contribution-flow.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Terraform Owner Contribution Flow -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -This section describes the contribution flow for module owners who are responsible for creating and maintaining Terraform Module repositories. - -{{< toc >}} - -
- ---- - -
- -{{< hint type=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](/Azure-Verified-Modules/contributing/process/,) [shared specifications](/Azure-Verified-Modules/specs/shared/) (including [Interfaces](/Azure-Verified-Modules/specs/shared/interfaces/)) and [Terraform-specific](/Azure-Verified-Modules/specs/terraform/) specifications as as these need to be considered during pull request reviews for the modules you own. - -{{< /hint >}} - -{{< hint type=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 susbcription. Also if more than two subscriptions are required for testin, that's currently not supported. - -{{< /hint >}} - -
- ---- - -
- -### 1. Owner Activities and Responsibilities - - -Familiarise yourself with the responsibilities as **Module Owner** outlined in [Team Definitions & RACI](/Azure-Verified-Modules/specs/shared/team-definitions/#module-owners) and in the [TF Issue Triage](/Azure-Verified-Modules/help-support/issue-triage/). - -1. 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](/Azure-Verified-Modules/specs/shared/#id-snfr11---category-contributionsupport---issues-response-times). - -{{< hint type=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. - -{{< /hint >}} - -2. Ensure that the module(s) you own are compliant with the AVM specifications and are working as expected. Following specifications are to be considered and where `Owner` is mentioned explicitly: - -| ID | Specification | -|---------------|-----------------------| -| [SFR1](/Azure-Verified-Modules/specs/shared/#id-sfr1---category-composition---preview-services) | Category: Composition - Preview Services | -| [SNFR2](/Azure-Verified-Modules/specs/shared/#id-snfr2---category-testing---e2e-testing) | Category: Testing - E2E Testing | -| [SNFR3](/Azure-Verified-Modules/specs/shared/#id-snfr3---category-testing---avm-compliance-tests) | Category: Testing - AVM Compliance Tests | -| [SNFR8](/Azure-Verified-Modules/specs/shared/#id-snfr8---category-contributionsupport---module-owners-github) | Category: Contribution/Support - Module Owner(s) GitHub | -| [SNFR11](/Azure-Verified-Modules/specs/shared/#id-snfr11---category-contributionsupport---issues-response-times) | Category: Contribution/Support - Issues Reponse Times | -| [SNFR12](/Azure-Verified-Modules/specs/shared/#id-snfr12---category-contributionsupport---versions-supported) | Category: Contribution/Support - Versions Supported | -| [SNFR17](/Azure-Verified-Modules/specs/shared/#id-snfr17---category-release---semantic-versioning) | Category: Release - Semantic Versioning | -| [SNFR20](/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only) | Category: Contribution/Support - GitHub Teams Only | -| [SNFR21](/Azure-Verified-Modules/specs/shared/#id-snfr21---category-publishing---cross-language-collaboration) | Category: Publishing - Cross Language Collaboration | -| [SNFR24](/Azure-Verified-Modules/specs/shared/#id-snfr24---category-testing---testing-child-extension--interface-resources) | Category: Testing - Testing Child, Extension & Interface Resources | -| [SNFR25](/Azure-Verified-Modules/specs/shared/#id-snfr25---category-composition---resource-naming) | Category: Composition - Resource Naming | -| [RMNFR3](/Azure-Verified-Modules/specs/shared/#id-rmnfr3---category-composition---rp-collaboration) | Category: Composition - RP Collaboration | -| [RMFR4](/Azure-Verified-Modules/specs/shared/#id-rmfr4---category-composition---avm-consistent-feature--extension-resources-value-add) | Category: Composition - AVM Consistent Feature & Extension Resources Value Add | -| [RMFR7](/Azure-Verified-Modules/specs/shared/#id-rmfr7---category-outputs---minimum-required-outputs) | Category: Outputs - Minimum Required Outputs | - -
- ---- - -
- -### 2. GitHub Teams and repository creation and configuration - -Familiarise yourself with the AVM Resource Module Naming in the [module index csv's](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes). - -- Example: `terraform--avm-res--` - -{{< hint type=important >}} - -Make sure you have access to the Azure organisation see [GitHub Account Link and Access](/Azure-Verified-Modules/contributing/terraform/prerequisites/#github-account-link-and-access). - -{{< /hint >}} - -1. Create the module repostory using [terraform-azuremrm-avm-template](https://github.com/Azure/terraform-azurerm-avm-template) in the `Azure` organisation with the following [details (internal only)](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/333/-TF-Create-repository-in-Github-Azure-org-and-conduct-business-review). You will then have to complete the configuration of your repository and start an [internal business review](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/333/-TF-Create-repository-in-Github-Azure-org-and-conduct-business-review?anchor=conduct-initial-repo-configuration-and-trigger-business-review). - -2. Create GitHub teams as outlined in [SNFR20](/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only) and add respective parent teams: - -Segments: - -- `avm-res---module-owners-tf` -- `avm-res---module-contributors-tf` - -Examples: - -- `avm-res-compute-virtualmachine-module-owners-tf` -- `avm-res-compute-virtualmachine-module-contributors-tf` - - -If a secondary owner is required, add the secondary owner to the `avm-res---module-owners-tf` team. - -1. Add these teams with the following permissions to the repository: - -- Admin: `avm-core-team-technical-terraform` = AVM Core Team (Terraform Technical) -- Admin: `terraform-avm` = Terraform PG -- Admin: `avm-res---module-owners-tf` = AVM Terraform Module Owners -- Write: `avm-res---module-contributors-tf` = AVM Terraform Module Contributors - -1. Make sure the branch protection rules for the `main` branch are inherited from the `Azure/terraform-azurerm-avm-template` repository: - -- Require a pull request before merging -- Dismiss stale pull request approvals when new commits are pushed -- Require review from Code Owners -- Require linear history -- Do not allow bypassing the above settings - -5. Set up a GitHub repository Environment called `test`. - -6. Create deployment protection rules for the `test` environment to avoid spinning up e2e tests with every pull request raised by third-parties. Add the following teams as required reviewers: - -- AVM Resource Module Owners: `avm-res---module-owners-tf` -- AVM Resource Module Contributors: `avm-res---module-contributors-tf` -- AVM Core Team Technical (Terraform): `avm-core-team-technical-terraform` - -Required reviewers. - -

- -Deployment prpotection rules. - -

- -Deployment prpotection rules. - -
- ---- - -
- -### 3. GitHub Repository Labels - -As per [SNFR23](/Azure-Verified-Modules/specs/shared/#id-snfr23---category-contributionsupport---github-repo-labels) the repositories created by module owners **MUST** have and use the pre-defined GitHub labels. To apply these labels to the repository review the PowerShell script `Set-AvmGitHubLabels.ps1` that is provided in [SNFR23](/Azure-Verified-Modules/specs/shared/#id-snfr23---category-contributionsupport---github-repo-labels). - -```pwsh -Set-AvmGitHubLabels.ps1 -RepositoryName "Azure/MyGitHubRepo" -CreateCsvLabelExports $false -NoUserPrompts $true -``` - -
- ---- - -
- -### 4. Module Handover Activities - - -1. Add new owner as maintainer in your `avm-res---module-owners-tf` team and remove any other individual including yourself. -2. In case primary owner leaves, switches roles or abandons the repo and the corresponding team then the parent team (if assigned) doesn't have the permissions to gain back access and a ticket with GitHub support needs to be created (but the team can still be removed from the repo since the team `avm-core-team` has permissions on it). - - - -
- ---- - -
- -### 5. **_Optional_**: Grept - -[Grept](https://github.com/Azure/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](https://github.com/Azure/Azure-Verified-Modules-Grept) repository. - -You can see [here](https://github.com/Azure/Azure-Verified-Modules-Grept/blob/main/terraform/synced_files.grept.hcl) which files are synced from the [`terraform-azurerm-avm-template`](https://github.com/Azure/terraform-azurerm-avm-template) repository. - -{{< hint type=info >}} - -You don't need to run grept manaully because it will be executed with the help of a [cron job](https://github.com/Azure/Azure-Verified-Modules-Grept/actions/workflows/grept-cronjob.yml) on a weekly basis to ensure consistency across all AVM Terraform Module repositories. In case your repository is in an inconsistent state it will create necessary PRs which needs to be approved and merged by you, the owner. However, you can also run it manually with the help of `./avm` to check if your module is compliant with the grept rules. - -{{< /hint >}} - -1. Set environment variables - -```bash -# Linux/MacOS -export GITHUB_REPOSITORY_OWNER=Azure -export GITHUB_REPOSITORY=Azure/terraform-azurerm-avm-res--" - -# Windows - -$env:GITHUB_REPOSITORY_OWNER="Azure" -$env:GITHUB_REPOSITORY="Azure/terraform-azurerm-avm-res--" -``` - -1. Run grept - -```bash -# Linux/MacOS -./avm grept-apply - -# Windows -avm.bat grept-apply -``` - -### 6. Publish the module - -Once a module was updated and is ready to be published, follow the below steps to publish the module to the HashiCorp Registry. - -Ensure your module is ready for publishing: - -1. All tests are passing. -2. All examples are passing. -3. All documentation is generated. -4. Include/Add [`avm-core-team-technical-terraform`](https://github.com/orgs/Azure/teams/avm-core-team-technical/members) as a reviewer (if not added automatically added already). -5. Create a tag for the module version you want to publish. -- Create tag: `git tag -a 0.1.0 -m "0.1.0"` -- Push tag: `git push` -- [Create a release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) on Github based on the tag you just created. Make sure to generate the release notes using the `Generate release notes` button. -- **_Optional:_** Instead of creating the tag via git cli, you can also create both the tag and release via [Github UI](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). Just go to the releases tab and click on `Draft a new release`. Make sure to create the tag from the `main` branch. - -Deployment prpotection rules. - -6. Elevate your respository access using the Open Source Management Portal (aka.ms/opensource/portal). -7. Sign in to the [HashiCorp Registry](https://registry.terraform.io/) using GitHub. -8. Publish a module by selecting the `Publish` button in the top right corner, then `Module` -9. Select the repository and accept the terms. - -{{< hint type=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. - -{{< /hint >}} - -{{< hint type=important >}} - -When an AVM Module is published to the HashiCorp Registry, it **MUST** follow the below requirements: - -- Resource Module: `terraform--avm-res--` as per [RMNFR1](/Azure-Verified-Modules/specs/shared/#id-rmnfr1---category-naming---module-naming) -- Pattern Module: `terraform--avm-ptn-` as per [PMNFR1](/Azure-Verified-Modules/specs/shared/#id-pmnfr1---category-naming---module-naming) - -{{< /hint >}} - -
- ---- - -
diff --git a/docs/content/glossary/_index.md b/docs/content/glossary/_index.md deleted file mode 100644 index 8164547..0000000 --- a/docs/content/glossary/_index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Glossary -geekdocNav: true -geekdocAlign: center -geekdocAnchor: true ---- - -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`](https://aka.ms/CARML) | -| TFVM | Terraform Verified Modules - [`Azure/terrafrom-azure-mdoules`](https://aka.ms/TFVM) | -| 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](https://aka.ms/alz/aac#application) - e.g., Azure Virtual Desktop (AVD), Azure VMware Solution (AVS), etc. | -| RP/RPs | [Azure Resource Providers](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types) | -| PG/PGs | Microsoft Product Group(s) | -| AAC | [Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/) | -| WAF | [Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/) | -| 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](https://careers.microsoft.com/v2/global/culture) | -| FTE/FTEs | Full Time Employee(s) | -| GA | Generally Available | -| MDFC | [Microsoft Defender for Cloud](https://learn.microsoft.com/en-us/azure/defender-for-cloud/defender-for-cloud-introduction) | -| MCSB | [Microsoft Cloud Security Benchmark](https://learn.microsoft.com/security/benchmark/azure/introduction) | -| MCR | [Microsoft Container Registry](https://github.com/microsoft/containerregistry). Which is what the Bicep Public Registry uses to publish it's modules via. | -| PR | [Pull Request](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) | -| Primary Resource | A primary resource is the main Azure service/product a Resource Module provides / is built around. | diff --git a/docs/content/help-support/GH-links.md b/docs/content/help-support/GH-links.md deleted file mode 100644 index 4f452b7..0000000 --- a/docs/content/help-support/GH-links.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: GitHub Links -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocCollapseSection: true ---- - -- [Propose a New Module](https://aka.ms/AVM/ModuleProposal) -- [Question or Feedback](https://aka.ms/AVM/QuestionFeedback) -- [Module Triage (Project)](https://aka.ms/AVM/ModuleTriage) -- [Module Issues (Project)](https://aka.ms/AVM/ModuleIssues) -- [Issue Triage (Project)](https://aka.ms/AVM/IssueTriage) diff --git a/docs/content/help-support/_index.md b/docs/content/help-support/_index.md deleted file mode 100644 index 31d129e..0000000 --- a/docs/content/help-support/_index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Help & Support -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -This section provides information about AVM's support. - -- [Module Support](/Azure-Verified-Modules/help-support/module-support/) -- [Issue Triage](/Azure-Verified-Modules/help-support/issue-triage/) - - [AVM Issue Triage](/Azure-Verified-Modules/help-support/issue-triage/avm-issue-triage/) - - [BRM Issue Triage](/Azure-Verified-Modules/help-support/issue-triage/brm-issue-triage/) - - [Issue Triage Automation](/Azure-Verified-Modules/help-support/issue-triage/issue-triage-automation/) -- [Telemetry](/Azure-Verified-Modules/help-support/telemetry/) -- {{< icon "gdoc_github" >}} [Create GitHub Issue](https://github.com/Azure/Azure-Verified-Modules/issues) -- {{< icon "gdoc_github" >}} [Propose a New Module](https://aka.ms/AVM/ModuleProposal) -- {{< icon "gdoc_github" >}} [Module Triage (Project)](https://aka.ms/AVM/ModuleTriage) -- {{< icon "gdoc_github" >}} [Module Issues (Project)](https://aka.ms/AVM/ModuleIssues) -- {{< icon "gdoc_github" >}} [Issue Triage (Project)](https://aka.ms/AVM/IssueTriage) diff --git a/docs/content/help-support/issue-triage/_index.md b/docs/content/help-support/issue-triage/_index.md deleted file mode 100644 index 5346476..0000000 --- a/docs/content/help-support/issue-triage/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Issue Triage -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocCollapseSection: true ---- - -This section provides information about the issue triage process and its automation, implemented across various AVM repositories. - -- [AVM Issue Triage](/Azure-Verified-Modules/help-support/issue-triage/avm-issue-triage/) -- [BRM Issue Triage](/Azure-Verified-Modules/help-support/issue-triage/brm-issue-triage/) -- [Issue Triage Automation](/Azure-Verified-Modules/help-support/issue-triage/issue-triage-automation/) diff --git a/docs/content/help-support/issue-triage/avm-issue-triage.md b/docs/content/help-support/issue-triage/avm-issue-triage.md deleted file mode 100644 index e864ad5..0000000 --- a/docs/content/help-support/issue-triage/avm-issue-triage.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: AVM Issue Triage -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocToC: 1 ---- - -{{< toc >}} - -## "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](https://aka.ms/AVM/repo), 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). - -{{< hint type=note >}} -Every module needs a module proposal to be created in the AVM repository. -{{< /hint >}} - -{{< hint type=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**. - -{{< /hint >}} - -
- -## Module Proposal triage - -An issue is considered to be a module proposal if - -- it was opened through the "[New AVM Module Proposal πŸ“](https://aka.ms/avm/moduleproposal)" 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](https://github.com/orgs/Azure/projects/529)" GitHub project. - -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](/Azure-Verified-Modules/indexes/bicep/) or [Terraform](/Azure-Verified-Modules/indexes/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](/Azure-Verified-Modules/specs/shared/#id-rmnfr1---category-naming---module-naming), [classification](/Azure-Verified-Modules/specs/shared/module-classifications/) (resource/pattern) etc. - - Check if the module is added to the "`Proposed`" column on the [AVM - Modules Triage](https://aka.ms/avm/moduletriage) 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](https://docs.opensource.microsoft.com/tools/browser/)". 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 - -{{< hint type=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. -{{< /hint >}} - -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](https://aka.ms/avm/moduletriage) 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). - -### 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](https://docs.opensource.microsoft.com/tools/browser/)". -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: - -{{< expand "βž• Standard AVM Core Team Reply to Proposed Module Owners" "expand/collapse" >}} - -{{< include file="static/includes/msg-std-reply-new-prop-mod-owners.md" language="markdown" options="linenos=false" >}} - -{{< /expand >}} - -3. 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](https://aka.ms/avm/moduletriage) 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. -4. Update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/286/Module-index-file-update-process). -5. Use the following text to approve module development - -{{< expand "βž• Final Confirmation for Proposed Module Owners" "expand/collapse" >}} - -{{< include file="static/includes/msg-final-conf-new-prop-mod-owners.md" language="markdown" options="linenos=false" >}} - -{{< /expand >}} - -{{< hint type=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](/Azure-Verified-Modules/specs/shared/#grant-permissions---bicep). - - Ensure the [`CODEOWNERS`](https://github.com/Azure/bicep-registry-modules/blob/main/.github/CODEOWNERS) file in the [BRM repo](https://aka.ms/BRM) has been updated. - - Ensure the [`AVM Module Issue template`](https://github.com/Azure/bicep-registry-modules/blob/main/.github/ISSUE_TEMPLATE/avm_module_issue.yml) file in the [BRM repo](https://aka.ms/BRM) has been updated. - -{{< /hint >}} - -
- -## 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](https://aka.ms/avm/moduletriage) GitHub Project. -3. Update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/286/Module-index-file-update-process). -4. Close the issue. - -{{< hint type=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**. - -{{< /hint >}} - -
- -## Orphaned modules - -### When a module becomes orphaned - -If a module meets the criteria described in the "[Orphaned AVM Modules](/Azure-Verified-Modules/specs/shared/module-lifecycle/#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 πŸ‘€](https://aka.ms/avm/OrphanedModule)" 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](https://github.com/orgs/Azure/projects/529)" GitHub project. - -{{< hint type=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. -{{< /hint >}} - -1. Create a new issue using the "[Orphaned AVM Module πŸ‘€](https://aka.ms/AVM/OrphanedModule)" 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](https://aka.ms/avm/moduletriage) GitHub Project board. -4. Update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/286/Module-index-file-update-process). -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 [`avm/utilities/tools/Set-AVMModule.ps1`](https://github.com/Azure/bicep-registry-modules/blob/main/avm/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: - -{{< expand "βž• Orphaned module notice for module README file" "expand/collapse" open >}} - -{{< include file="static/includes/orphaned-module-notice.md" language="markdown" options="linenos=false" >}} - -{{< /expand >}} - -5. 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 - -{{< hint type=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](https://aka.ms/avm/moduletriage). -{{< /hint >}} - -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: - -{{< expand "βž• Standard AVM Core Team Reply to New Owners of an Orphaned Module" "expand/collapse" >}} - -{{< include file="static/includes/msg-std-reply-new-orph-mod-owners.md" language="markdown" options="linenos=false" >}} - -{{< /expand >}} - -2. 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](https://aka.ms/avm/moduletriage) GitHub Project board. -3. Update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/286/Module-index-file-update-process). -4. Get the new owner(s) and any new contributor(s) added to the related `-module-owners-` or `-module-contributors-` teams. See [SNFR20](/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only) for more details. -5. 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 [`avm/utilities/tools/Set-AVMModule.ps1`](https://github.com/Azure/bicep-registry-modules/blob/main/avm/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. -6. Use the following text to confirm the new ownership of an orphaned module: - -{{< expand "βž• Final Confirmation for New Owners of an Orphaned Module" "expand/collapse" >}} - -{{< include file="static/includes/msg-final-conf-new-orph-mod-owners.md" language="markdown" options="linenos=false" >}} - -{{< /expand >}} - -7. Close the Orphaned Module issue. - -
- -## General feedback/question and other standard issues - -An issue is a "General Question/Feedback ❔" if it was opened through the ["General Question/Feedback ❔"](https://github.com/Azure/Azure-Verified-Modules/issues/new?assignees=&labels=Type%3A+Question%2FFeedback+%3Araising_hand%3A&projects=&template=question_feedback.yml&title=%5BQuestion%2FFeedback%5D%3A+) issue template, and has the labels of "Type: Question/Feedback πŸ™‹β€β™€οΈ" 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](/Azure-Verified-Modules/specs/shared/#id-snfr23---category-contributionsupport---github-repo-labels) section. - -{{< hint type=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](https://aka.ms/avm/moduleproposal). The mistakenly created "General Question/Feedback ❔" or other standard issue **MUST** be closed. - -{{< /hint >}} diff --git a/docs/content/help-support/issue-triage/brm-issue-triage.md b/docs/content/help-support/issue-triage/brm-issue-triage.md deleted file mode 100644 index 6ef08b3..0000000 --- a/docs/content/help-support/issue-triage/brm-issue-triage.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: BRM Issue Triage -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocToC: 1 ---- - -{{< toc >}} - -## 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](https://aka.ms/BRM) (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](https://aka.ms/BRM/AVMModuleIssue)]**: Issues specifically related to an existing AVM module, such as feature requests, bug and security bug reports. -- **\[[AVM Question/Feedback](https://aka.ms/BRM/AVMQuestionFeedback)]**: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](https://aka.ms/AVM/ModuleProposal)]**: Proposals for new AVM modules. -- **\[[Orphaned Module](https://aka.ms/AVM/OrphanedModule)]**: Indicate that a module is orphaned (has no owner). -- **\[[Question/Feedback](https://aka.ms/AVM/QuestionFeedback)]**: Generic questions/requests related to the AVM site or documentation. - -{{< hint type=note >}} -Every module needs a module proposal to be created in the AVM repository. -{{< /hint >}} - -
- -## 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](/Azure-Verified-Modules/help-support/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. - -{{< hint type=important >}} -The [BRM repository](https://aka.ms/BRM) 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! -{{< /hint >}} - -{{< hint type=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 πŸ‘‹ ⬅️. - -{{< /hint >}} - -
- -## Module Issue - -An issue is considered to be an "AVM module issue" if - -- it was opened through the **\[[AVM Module Issue](https://aka.ms/BRM/AVMModuleIssue)]** template in the [BRM repository](https://aka.ms/BRM), -- it has the labels of "Needs: Triage πŸ”" and "Type: AVM πŸ…°οΈ ✌️ β“œοΈ" applied to it, and -- it is assigned to the "[AVM - Module Issues](https://github.com/orgs/Azure/projects/566)" GitHub project. - -{{< hint type=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. -{{< /hint >}} - -### 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. - -
- -## 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](https://aka.ms/BRM/AVMQuestionFeedback)]** template in the [BRM repository](https://aka.ms/BRM), -- 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](https://github.com/orgs/Azure/projects/538)" 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](/Azure-Verified-Modules/specs/shared/#id-snfr23---category-contributionsupport---github-repo-labels) section. - -2. Add any (additional) labels that apply. -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. Once the question/feedback/topic is fully addressed, close the issue. - -{{< hint type=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](https://aka.ms/AVM/repo) using the "New AVM Module Proposal πŸ“" [issue template](https://aka.ms/avm/moduleproposal). The mistakenly created "AVM Question/Feedback ❔" or other standard issue **MUST** be closed. - -{{< /hint >}} diff --git a/docs/content/help-support/issue-triage/issue-triage-automation.md b/docs/content/help-support/issue-triage/issue-triage-automation.md deleted file mode 100644 index cf22dba..0000000 --- a/docs/content/help-support/issue-triage/issue-triage-automation.md +++ /dev/null @@ -1,645 +0,0 @@ ---- -title: Issue/Triage Automation -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocToC: 1 ---- - -{{< toc >}} - -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. - -{{< hint type=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. -{{< /hint >}} - -### 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. - -{{< hint type=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). -{{< /hint >}} - ---- - -### 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. - -{{< hint type=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). -{{< /hint >}} - ---- - -### 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. - -{{< hint type=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. -{{< /hint >}} - ---- - -### 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. - -{{< hint type=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. -{{< /hint >}} - ---- - -### 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. - -{{< hint type=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. -{{< /hint >}} - ---- - -### 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. -- 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. - -{{< hint type=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. -{{< /hint >}} - ---- - -### ITA05 - -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. - -{{< hint type=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. -{{< /hint >}} - ---- - -### 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. - -{{< hint type=tip >}} -- To silence this notification, provide an update every 3 weeks on the Module Proposal issue, or add the "Status: Long Term ⏳" label. -{{< /hint >}} - ---- - -
- -## 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. -- Add a reply to explain the action(s). - ---- - -### 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". -- Add a reply to explain the action(s). - -**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. -- Add a reply to explain the action(s). - ---- - -### ITA11 - -When a reply from anyone to an issue occurs, 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. - -**Action(s):** - -- Add the "Needs: Attention πŸ‘‹" label. -- Add a reply to explain the action(s). - ---- - -### 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. - -```markdown -### Bicep or Terraform? - -Bicep -``` - -**Action(s):** - -- Add the "Language: Bicep πŸ’ͺ" label. -- Add a reply to explain the action(s). - ---- - -### 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. - -```markdown -### Bicep or Terraform? - -Terraform -``` - -**Action(s):** - -- Add the "Language: Terraform 🌐" label. -- Add a reply to explain the action(s). - ---- - -### 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. -- Add a reply to explain the action(s). - ---- - -### 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. -- Add a reply to explain the action(s). - ---- - -### 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. - - ```markdown - ### 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). - - ```markdown - @${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. - - ```markdown - ### 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). - - ```markdown - @${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... - - ```markdown - ### Do you want to be the owner of this module? - - No - ``` - -- ...AND NOT matching the below pattern. - - ```markdown - ### 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). - - ```markdown - @${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. - - ```markdown - ### Issue Type? - - Feature Request - ``` - -**Action(s):** - -- Add the "Type: Feature Request βž•" label. -- Add a reply to explain the action(s). - ---- - -### 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. - - ```markdown - ### Issue Type? - - Bug - ``` - -**Action(s):** - -- Add the "Type: Bug πŸ›" label. -- Add a reply to explain the action(s). - ---- - -### 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. - - ```markdown - ### Issue Type? - - Security Bug - ``` - -**Action(s):** - -- Add the "Type: Security Bug πŸ”’" label. -- Add a reply to explain the action(s). - ---- - -### 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. -- Add a reply to explain the action(s). - ---- - -## 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](#ita01bcp1-2) | | βœ”οΈ | | -| [ITA01TF1-2](#ita01tf1-2) | | | βœ”οΈ | -| [ITA02BCP1-2](#ita02bcp1-2) | | βœ”οΈ | | -| [ITA02TF1-2](#ita02tf1-2) | | | βœ”οΈ | -| [ITA03BCP](#ita03bcp) | | βœ”οΈ | | -| [ITA03TF](#ita03tf) | | | βœ”οΈ | -| [ITA04](#ita04) | βœ”οΈ | βœ”οΈ | βœ”οΈ | -| [ITA05](#ita05) | βœ”οΈ | βœ”οΈ | βœ”οΈ | -| [ITA24](#ita24) | βœ”οΈ | | | - -### Rules applied for Event based automation - -| ID | AVM Core repository | BRM repository | TF repositories | -|-----------------------------|:-------------------:|:--------------:|:---------------:| -| [ITA06](#ita06) | βœ”οΈ | βœ”οΈ | βœ”οΈ | -| [ITA08BCP](#ita08bcp) | | βœ”οΈ | | -| [ITA09](#ita09) | βœ”οΈ | βœ”οΈ | βœ”οΈ | -| [ITA10](#ita10) | βœ”οΈ | βœ”οΈ | βœ”οΈ | -| [ITA11](#ita11) | βœ”οΈ | βœ”οΈ | βœ”οΈ | -| [ITA12](#ita12) | βœ”οΈ | βœ”οΈ | βœ”οΈ | -| [ITA13](#ita13) | βœ”οΈ | | | -| [ITA14](#ita14) | βœ”οΈ | | | -| [ITA15](#ita15) | βœ”οΈ | βœ”οΈ | βœ”οΈ | -| [ITA16](#ita16) | βœ”οΈ | | | -| [ITA17](#ita17) | βœ”οΈ | | | -| [ITA18](#ita18) | βœ”οΈ | | | -| [ITA19](#ita19) | βœ”οΈ | | | -| [ITA20](#ita20) | | βœ”οΈ | βœ”οΈ | -| [ITA21](#ita21) | | βœ”οΈ | βœ”οΈ | -| [ITA22](#ita22) | | βœ”οΈ | βœ”οΈ | -| [ITA23](#ita23) | βœ”οΈ | | βœ”οΈ | diff --git a/docs/content/help-support/issue-triage/terraform-issue-triage.md b/docs/content/help-support/issue-triage/terraform-issue-triage.md deleted file mode 100644 index 1d597ab..0000000 --- a/docs/content/help-support/issue-triage/terraform-issue-triage.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Terraform Issue Triage -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocToC: 1 ---- - -{{< toc >}} - -## 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](https://aka.ms/AVM/ModuleProposal)]**: Proposals for new AVM modules. -- **\[[Orphaned Module](https://aka.ms/AVM/OrphanedModule)]**: Indicate that a module is orphaned (has no owner). -- **\[[Question/Feedback](https://aka.ms/AVM/QuestionFeedback)]**: Generic questions/requests related to the AVM site or documentation. - -{{< hint type=note >}} -Every module needs a module proposal to be created in the AVM repository. -{{< /hint >}} - -
- -## 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](/Azure-Verified-Modules/help-support/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. - -{{< hint type=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 πŸ‘‹ ⬅️. - -{{< /hint >}} - -
- -## 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](https://github.com/orgs/Azure/projects/566)" GitHub project. - -{{< hint type=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. -{{< /hint >}} - -### 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](https://github.com/orgs/Azure/projects/538)" 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](/Azure-Verified-Modules/specs/shared/#id-snfr23---category-contributionsupport---github-repo-labels) section. - -2. Add any (additional) labels that apply. -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. Once the question/feedback/topic is fully addressed, close the issue. - -{{< hint type=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](https://aka.ms/AVM/repo) using the "New AVM Module Proposal πŸ“" [issue template](https://aka.ms/avm/moduleproposal). The mistakenly created "AVM Question/Feedback ❔" or other standard issue **MUST** be closed. - -{{< /hint >}} diff --git a/docs/content/help-support/known-issues.md b/docs/content/help-support/known-issues.md deleted file mode 100644 index c4de985..0000000 --- a/docs/content/help-support/known-issues.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Known Issues -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -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. - -{{< hint type=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`](https://github.com/Azure/Azure-Verified-Modules/issues/new/choose) repo. - -*If you accidentally raise an issue in the wrong place, we will transfer it to its correct home. πŸ‘* - -{{< /hint >}} - -## Bicep - -### Bicep what-if compatibility with modules - -[Bicep/ARM What-If](https://learn.microsoft.com/azure/azure-resource-manager/bicep/deploy-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](https://learn.microsoft.com/azure/azure-resource-manager/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. - -{{< hint type=note icon=gdoc_github title="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](https://github.com/Azure/arm-template-whatif/issues/157) - -{{< /hint >}} - -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](https://github.com/Azure/arm-template-whatif/issues/157#issuecomment-2083179814). - -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. πŸ‘ - -{{< hint type=note icon=gdoc_github title="Other Related GitHub Issues" >}} - -- [`Azure/Azure-Verified-Modules #797` - [AVM Question/Feedback]: Output of what-if (if any) can't be trusted](https://github.com/Azure/Azure-Verified-Modules/issues/797) - -{{< /hint >}} - -## Terraform - -Currently there are no known issues for AVM Terraform modules. πŸ₯³ - - diff --git a/docs/content/help-support/module-support.md b/docs/content/help-support/module-support.md deleted file mode 100644 index 75707c4..0000000 --- a/docs/content/help-support/module-support.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Module Support -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -As mentioned in the [What, Why, How](/Azure-Verified-Modules/concepts/what-why-how) 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. - -{{< hint type=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 πŸ‘* - -{{< /hint >}} - -
- -Azure Verified Modules are supported by the AVM teams, as defined [here](/Azure-Verified-Modules/specs/shared/team-definitions/), 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. - -{{< hint type=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. - -{{< /hint >}} - -
- -All of this will be automated via the use of the Resource Management feature of the [Microsoft GitHub Policy Service](https://github.com/apps/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](/Azure-Verified-Modules/specs/shared/module-lifecycle/) for more info. - -{{< hint type=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). - -{{< /hint >}} diff --git a/docs/content/help-support/telemetry.md b/docs/content/help-support/telemetry.md deleted file mode 100644 index 915704e..0000000 --- a/docs/content/help-support/telemetry.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Telemetry -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true ---- - -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](https://www.microsoft.com/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. - -{{< hint type=note >}} - -While telemetry gathered as described here is only accessible by Microsoft, 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.). - -See [View deployment history with Azure Resource Manager](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deployment-history?tabs=azure-portal) for further information on how. - -{{< /hint >}} - -
- -## Technical Details - -As detailed in [SFR3](/Azure-Verified-Modules/specs/shared/#id-sfr3---category-telemetry---deploymentusage-telemetry) 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](https://learn.microsoft.com/partner-center/marketplace/azure-partner-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. - -{{< hint type=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). - -{{< /hint >}} diff --git a/docs/content/indexes/terraform/_index.md b/docs/content/indexes/terraform/_index.md deleted file mode 100644 index e521087..0000000 --- a/docs/content/indexes/terraform/_index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Terraform Modules -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -geekdocCollapseSection: true ---- - -This section lists all Azure Verified Modules that are available in or planned for the **Terraform language**. - -- [Resource Modules](/Azure-Verified-Modules/indexes/terraform/tf-resource-modules) -- [Pattern Modules](/Azure-Verified-Modules/indexes/terraform/tf-pattern-modules) - ---- - -
- -The following table shows the number of all available, orphaned and planned **Terraform Modules**. - -{{< moduleStats language="Terraform" moduleType="All" showLanguage=true showClassification=true >}} diff --git a/docs/content/indexes/terraform/tf-pattern-modules.md b/docs/content/indexes/terraform/tf-pattern-modules.md deleted file mode 100644 index fda7411..0000000 --- a/docs/content/indexes/terraform/tf-pattern-modules.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Terraform Pattern Modules -geekdocNav: false -geekdocAlign: left -geekdocAnchor: true ---- - - - - - -{{< hint type=note >}} - -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. - -- {{< icon "gdoc_github" >}} To see the **full, unfiltered, unformatted module index** on GitHub, click [here](https://github.com/Azure/Azure-Verified-Modules/blob/main/docs/static/module-indexes/TerraformPatternModules.csv). - -- {{< icon "gdoc_download" >}} To download the source CSV file, click [here](/Azure-Verified-Modules/module-indexes/TerraformPatternModules.csv). - -{{< /hint >}} - -{{< toc >}} - -## Module catalog - -{{< hint type=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](/Azure-Verified-Modules/indexes/terraform/tf-pattern-modules/#proposed-modules---) section below. -{{< /hint >}} - -The following table shows the number of all available, orphaned and proposed **Terraform Pattern Modules**. - -{{< moduleStats language="Terraform" moduleType="Pattern" showLanguage=true showClassification=true >}} - -
- -### Module Publication History - πŸ“… - -{{< expand "βž• Module Publication History - Module names, status and owners" "expand/collapse" "closed" >}} - -{{< moduleHistory header=true csv="/static/module-indexes/TerraformPatternModules.csv" language="Terraform" moduleType="pattern" exclude="New Module :new:" monthsToShow=9999 >}} - -{{< /expand >}} - -
- -### Published modules - 🟒 & πŸ‘€ - -{{< expand "βž• Published Modules - Module names, status and owners" "expand/collapse" "open" >}} - -{{< moduleNameStatusOwners header=true csv="/static/module-indexes/TerraformPatternModules.csv" language="Terraform" moduleType="pattern" exclude="New Module :new:" >}} - -{{< /expand >}} - -
- -### Proposed modules - πŸ†• - -{{< expand "βž• Proposed Modules - Module names, status and owners" "expand/collapse" >}} - -{{< moduleNameStatusOwners header=true csv="/static/module-indexes/TerraformPatternModules.csv" language="Terraform" moduleType="pattern" exclude="Module Available :green_circle:,Module Orphaned :eyes:" >}} - -{{< /expand >}} - -
- -### All modules - πŸ“‡ - -{{< expand "βž• All Modules - Module names, status and owners" "expand/collapse" >}} - -{{< moduleNameStatusOwners header=true csv="/static/module-indexes/TerraformPatternModules.csv" language="Terraform" moduleType="pattern" >}} - -{{< /expand >}} - -
- -## For Module Owners & Contributors - -{{< hint type=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**. - -{{< /hint >}} - -### Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors - -{{< expand "βž• All Modules - Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors" "expand/collapse" >}} - -{{< moduleNameTelemetryGHTeams header=true csv="/static/module-indexes/TerraformPatternModules.csv" language="Terraform" moduleType="pattern">}} - -{{< /expand >}} diff --git a/docs/content/indexes/terraform/tf-resource-modules.md b/docs/content/indexes/terraform/tf-resource-modules.md deleted file mode 100644 index d4a6041..0000000 --- a/docs/content/indexes/terraform/tf-resource-modules.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Terraform Resource Modules -geekdocNav: false -geekdocAlign: left -geekdocAnchor: true ---- - - - - - -{{< hint type=note >}} - -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. - -- {{< icon "gdoc_github" >}} To see the **full, unfiltered, unformatted module index** on GitHub, click [here](https://github.com/Azure/Azure-Verified-Modules/blob/main/docs/static/module-indexes/TerraformResourceModules.csv). - -- {{< icon "gdoc_download" >}} To download the source CSV file, click [here](/Azure-Verified-Modules/module-indexes/TerraformResourceModules.csv). - -{{< /hint >}} - -{{< toc >}} - -## Module catalog - -{{< hint type=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](/Azure-Verified-Modules/indexes/terraform/tf-resource-modules/#proposed-modules---) section below. -{{< /hint >}} - -The following table shows the number of all available, orphaned and proposed **Terraform Resource Modules**. - -{{< moduleStats language="Terraform" moduleType="Resource" showLanguage=true showClassification=true >}} - -
- -### Module Publication History - πŸ“… - -{{< expand "βž• Module Publication History - Module names, status and owners" "expand/collapse" "closed" >}} - -{{< moduleHistory header=true csv="/static/module-indexes/TerraformResourceModules.csv" language="Terraform" moduleType="resource" exclude="New Module :new:" monthsToShow=9999 >}} - -{{< /expand >}} - -
- -### Published modules - 🟒 & πŸ‘€ - -{{< expand "βž• Published Modules - Module names, status and owners" "expand/collapse" "open" >}} - -{{< moduleNameStatusOwners header=true csv="/static/module-indexes/TerraformResourceModules.csv" language="Terraform" moduleType="resource" exclude="New Module :new:" >}} - -{{< /expand >}} - -
- -### Proposed modules - πŸ†• - -{{< expand "βž• Proposed Modules - Module names, status and owners" "expand/collapse" >}} - -{{< moduleNameStatusOwners header=true csv="/static/module-indexes/TerraformResourceModules.csv" language="Terraform" moduleType="resource" exclude="Module Available :green_circle:,Module Orphaned :eyes:" >}} - -{{< /expand >}} - -
- -### All modules - πŸ“‡ - -{{< expand "βž• All Modules - Module names, status and owners" "expand/collapse" >}} - -{{< moduleNameStatusOwners header=true csv="/static/module-indexes/TerraformResourceModules.csv" language="Terraform" moduleType="resource" >}} - -{{< /expand >}} - -
- -## For Module Owners & Contributors - -{{< hint type=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**. - -{{< /hint >}} - -### Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors - -{{< expand "βž• All Modules - Module name, Telemetry ID prefix, GitHub Teams for Owners & Contributors" "expand/collapse" >}} - -{{< moduleNameTelemetryGHTeams header=true csv="/static/module-indexes/TerraformResourceModules.csv" language="Terraform" moduleType="resource" >}} - -{{< /expand >}} diff --git a/docs/content/specs-defs/module-classifications.md b/docs/content/specs-defs/module-classifications.md deleted file mode 100644 index 375779f..0000000 --- a/docs/content/specs-defs/module-classifications.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Module Classifications -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -url: /specs/shared/module-classifications/ ---- - -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 Classification | Definition | Who is it for? | -| --------------------- | ---------- | -------------- | -|**Resource Module** | Deploys a primary resource with WAF high priority/impact best practice configurations set by default, e.g., RBAC, Locks, Private Endpoints etc. (if supported). See [What does AVM mean by β€œWAF Aligned”?](/Azure-Verified-Modules/faq/#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 that want to craft bespoke architectures that default to WAF best practices, where appropriate, for each resource.

People that 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](https://learn.microsoft.com/en-us/azure/architecture/), or other official documentation.

*Note:* It is feasible that pattern modules can contain other pattern modules, however, pattern modules MUST NOT contain references to non-AVM modules. | People that want to easily deploy patterns (architectures) using WAF best practices. | diff --git a/docs/content/specs-defs/module-lifecycle.md b/docs/content/specs-defs/module-lifecycle.md deleted file mode 100644 index 47099b1..0000000 --- a/docs/content/specs-defs/module-lifecycle.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Module Lifecycle -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -url: /specs/shared/module-lifecycle/ ---- -{{< hint type=note >}} - -This page is still a work in progress - -{{< /hint >}} - -## Request/Propose a New AVM Resource or Pattern Module - -Please review the [Process Overview](/Azure-Verified-Modules/contributing/process/#new-module-proposal--creation) for guidance on proposing a new AVM module. - -## Orphaned AVM 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](/Azure-Verified-Modules/help-support/module-support/) , 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](/Azure-Verified-Modules/help-support/module-support/) -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 - -### Notification of a Module Becoming Orphaned - -{{< hint type=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: - -{{< include file="static/includes/orphaned-module-notice.md" language="markdown" options="linenos=false" >}} - -{{< /hint >}} - -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. diff --git a/docs/content/specs-defs/team-definitions.md b/docs/content/specs-defs/team-definitions.md deleted file mode 100644 index 02bd5af..0000000 --- a/docs/content/specs-defs/team-definitions.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Team Definitions & RACI -geekdocNav: true -geekdocAlign: left -geekdocAnchor: true -url: /specs/shared/team-definitions/ ---- -{{< toc >}} - -## 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. - -{{< hint type=important >}} - -Individuals can be members of multiple teams, at once, that are defined below. - -{{< /hint >}} - -
- -### AVM Core Team - -GitHub Team: [`@Azure/avm-core-team`](https://github.com/orgs/Azure/teams/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 - -{{< hint type=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. - -{{< /hint >}} - -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.](https://github.com/orgs/Azure/teams/) - -
- -### Module Contributors - -{{< hint type=important >}} - -Module Contributors can be anyone in any organization. However, they must be an active contributor and supporting the Module Owners. - -{{< /hint >}} - -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](https://github.com/orgs/Azure/teams/), that the Module Owners manage and are maintainers of. - -
- -### Product Groups - -GitHub Teams: - -- [`@Azure/bicep-admins`](https://github.com/orgs/Azure/teams/bicep-admins) = Bicep PG team -- [`@Azure/terraform-avm`](https://github.com/orgs/Azure/teams/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 - -{{< hint type=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. - -{{< /hint >}} - -
- -## RACI - -{{< hint type=note title="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. - -{{< /hint >}} - -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 | Notes | -| ------------------------------------------------------------------------------------------------ | ------------- | ------------------- | ------------- | -------------- | ----- | -| 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 | | diff --git a/docs/data/menu/extra.yaml b/docs/data/menu/extra.yaml index 668c39a..859fd36 100644 --- a/docs/data/menu/extra.yaml +++ b/docs/data/menu/extra.yaml @@ -6,11 +6,11 @@ header: external: false - name: GitHub - ref: https://github.com/Azure/Azure-Verified-Modules + ref: https://github.com/daveRendon/azinsider/ icon: gdoc_github external: true - name: GitHub Issues - ref: https://github.com/Azure/Azure-Verified-Modules/issues + ref: https://github.com/daveRendon/azinsider/issues icon: gdoc_error_outline external: true