Terraform Owner Contribution Flow

This section describes the contribution flow for module owners who are responsible for creating and maintaining Terraform Module repositories.

1. Owner Activities and Responsibilities

Familiarise yourself with the responsibilities as Module Owner outlined in Team Definitions & RACI and in the TF 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.

2. GitHub repository creation and configuration

Once your module has been approved and you are ready to start development, you need to request that a new repository be created for your module.

You do that by adding a comment to the issue with the #RFRC tag. The  Status: Ready For Repository Creation 📝  label will then be applied. This will trigger the creation of the repository and the configuration of the repository with the required settings.

Once your module is ready for development, the  Status: Repository Created 📄  label will be added to the issue and you’ll be notified it is ready.

3. Module Development Activities

You can now start developing your module, following standard guidance for Terraform module development.

Some useful things to know:

Pull Request

You can raise a pull request anytime, don’t wait until the end of the development cycle. Raise the PR after you first push your branch.

You can then use the PR to run end to end tests, check linting, etc.

Once readdy for review, you can request a review per step 4.

Grept

Grept is a linting tool for repositories, ensures predefined standards, maintains codebase consistency, and quality.
It’s using the grept configuration files from the Azure-Verified-Modules-Grept repository.

You can see here which files are synced from the terraform-azurerm-avm-template repository.

Set environment variables and run Grept:

export GITHUB_REPOSITORY_OWNER=Azure
export GITHUB_REPOSITORY=Azure/terraform-azurerm-avm-res-<RP>-<modulename>"

./avm grept-apply

$env:GITHUB_REPOSITORY_OWNER="Azure"
$env:GITHUB_REPOSITORY="Azure/terraform-azurerm-avm-res-<RP>-<modulename>"

./avm grept-apply

Custom Variables and Secrets for end to end tests

The respoitory has an environment called test, it has have approvals and secrets applied to it ready to run end to end tests.

• In the unusual cicumstance that you need to use your own tenant and subscription for end to end tests, you can override the secrets by setting ARM_TENANT_ID_OVERRIDE, ARM_SUBSCRIPTION_ID_OVERRIDE, and ARM_CLIENT_ID_OVERRIDE secrets.
• If you need to supply additional secrets or variables for your end to end tests, you can add them to the test environment. They must be prefixed with TF_VAR_, otherwise they will be ignored.

4. Review the module

Once the development of the module has been completed, get the module reviewed from the AVM Core team by following the AVM Review of Terraform Modules process here which is a pre-requisite for the next step.

5. Publish the module

Once a module has been reviewed and the PR is merged to main. Follow the below steps to publish the module to the HashiCorp Registry.

Ensure your module is ready for publishing:

1. Create a release with a new tag (e.g. 0.1.0) via Github UI.

   • Go to the releases tab and click on Draft a new release.
   • Ensure that the Target is set to the main branch.
   • Select Choose a tag and type in a new tag, such as 0.1.0 Make sure to create the tag from the main branch.
   • Generate the release notes using the Generate release notes button.

   

2. Elevate your respository access using the Open Source Management Portal.

3. Sign in to the HashiCorp Registry using GitHub.

4. Publish a module by selecting the Publish button in the top right corner, then Module

5. Select the repository and accept the terms.

Terraform Core Team Repository Creation Process

This section describes the process for AVM core team members who are responsible for creating Terraform Module repositories.

1. Find Issues Ready for Repository Creation

1. When a module owner is ready to start development, they will add the  Status: Ready For Repository Creation 📝  label to the proposal via a comment issue.
2. To find issues that are ready for repository creation, click this link
3. Open one of the issues to find the details you need.
   1. Module name: This will be in the format avm-<type>-<name>. e.g. avm-res-network-virtualnetwork
   2. Module owner GitHub handle: This will be in the content of the issue
   3. Module description: If this does not exist, then create one. The description will automtically be prefixed with Terraform Azure Verified <module-type> Module for ..., where <module-type> is either Resource, Pattern, or Utility

2. Create the repository

1. Open a PowerShell terminal

2. Clone the https://github.com/Azure/terraform-azure-modules repository and navigate to the repository_creation_helper folder

   git clone "https://github.com/Azure/terraform-azure-modules"
   cd ./terraform-azure-modules/repository_creation_helper

3. Install the GitHub CLI if you don’t already have it installed: https://cli.github.com

4. Login to GitHub CLI

   gh auth login -h "github.com" -w -p "https" -s "delete_repo" -s "workflow" -s "read:user" -s "user:email"

   Follow the prompts to login to your GitHub account.

5. Run the following command, replacing the values with the details you collected in step 1

   $moduleProvider = "azurerm" # Only change this if you know why you need to change it :)
   $moduleName = "<module name>" # Replace with the module name (do not include the "terraform-azurerm" prefix)
   $moduleDescription = "<module description>" # Replace with a short description of the module
   $moduleOwner = "<github user handle>" # Replace with the GitHub handle of the module owner
   
   ./New-Repository.ps1 `
       -moduleProvider $moduleProvider `
       -moduleName $moduleName `
       -moduleDescription $moduleDescription `
       -moduleOwner $moduleOwner

   For example:

   $moduleProvider = "azurerm" # Only change this if you know why you need to change it :)
   $moduleName = "avm-res-network-virtualnetwork" # Replace with the module name (do not include the "terraform-azurerm" prefix)
   $moduleDescription = "Virtual Networks" # Replace with a short description of the module
   $moduleOwner = "jaredfholgate" # Replace with the GitHub handle of the module owner
   
   ./New-Repository.ps1 `
       -moduleProvider $moduleProvider `
       -moduleName $moduleName `
       -moduleDescription $moduleDescription `
       -moduleOwner $moduleOwner

6. The script will stop and prompt you to fill out the Microsoft Open Source details,

7. Open the Open Source Portal using the link in the script output.

8. Click Complete Setup, then use the following table to provide the settings:

   Question	Answer
   Classify the repository	Production
   Assign a Service tree or Opt-out	Azure Verified Modules / AVM
   Direct owners	Add the module owner and yourself as direct owners. Add the avm-team-module-owners as security group.
   Is this going to ship as a public open source licensed project	Yes, creating an open source licensed project
   What type of open source will this be	Sample code
   What license will you be releasing with	MIT
   Did your team write all the code and create all of the assets you are releasing?	Yes, all created by my team
   Does this project send any data or telemetry back to Microsoft?	Yes, telemetry
   Does this project implement cryptography	No
   Project name	Azure Verified Module (Terraform) for ‘module name’
   Project version	1
   Project description	Azure Verified Module (Terraform) for ‘module name’. Part of AVM project - https://aka.ms/avm
   Business goals	Create IaC module that will accelerate deployment on Azure using Microsoft best practice.
   Will this be used in a Microsoft product or service?	This is open source project and can be leveraged in Microsoft service and product.
   Adopt security best practice?	Yes, use just-in-time elevation
   Maintainer permissions	Leave empty
   Write permissions	Leave empty
   Repository template	Uncheck
   Add .gitignore	Uncheck

9. Click Finish setup + start business review to complete the setup

10. Wait for it to process and then click View repository

11. If you don’t see the Elevate your access button, then refresh the browser window

12. Click Elevate your access and follow the prompts to elevate your access

13. Now head back over to the terminal and type yes and hit enter to complete the repository configuration

14. Open the new repository in GitHub.com and verify it all looks good.

    1. On the home page
       1. The name is correct
       2. The description is correct
       3. The Terraform registry url looks good
       4. The repository has the template files in it
    2. In Setting
       1. The repository is public
       2. The Collaborators and teams are correct

3. Request the GitHub App Install

1. Create a new issue at https://github.com/microsoft/github-operations/issues/new?template=GitHub-App-Installation-Request.md

2. Update the issue with the following details:

   1. Title: [GitHub App] Installation Request - Azure Verified Modules

   2. Body - replace <repository url> with the URL of the repository you created in step 2:

      > __Note:__ If the app is listed on the [Auto-Approved list](https://docs.opensource.microsoft.com/github/apps/approvals/), you do not need to complete this form.
      
      You complete these steps:
      
      - [x] Confirm the app is not in the [Auto-Approved list](https://docs.opensource.microsoft.com/github/apps/approvals/)
      - [x] Fill out and verify the information in this form
      - [x] Update the title to reflect the org/repo and/or app name
      - [x] Submit the native request within the GitHub user interface
      
      Operations will help complete these steps:
      
      - [ ] Approve the app if already requested on GitHub natively
      - [ ] Close this issue
      
      Finally, you'll complete any configuration with the app or your repo that is required once approved.
      
      # My request
      
      - GitHub App name: Azure Verified Modules
      
      - GitHub organization in which the app would be installed: Azure
      
      - Is this an app created by you and/or your team?
      
        - [x] Yes, this is an app created by me and/or my team
        - [ ] No, this is a Microsoft 1st-party app created by another team
        - [ ] No, this is a 3rd-party marketplace app
      
      - If this __is an app created by you and/or your team__, please provide some ownership information in case future questions come up:
      
        - Service Tree ID: our service tree ID is: Unchanged
        - A few specific individuals at Microsoft if we have questions (corporate email list):Unchanged
        - An optional team discussion list: Unchanged
      
      - Is this an app you/your team created to address [reduced PAT lifetimes](https://aka.ms/opensource/tsg/pat)?
        - [x] Yes
        - [ ] No
      
      - Are you looking for this app to be installed on individual repos or all repos in an organization?
      
        - [x] Individual repos: <repository url>
        - [ ] All repos in an organization
      
      - Does this app have any side-effects if it is installed into all repos in an organization? Side effects can include creating labels, issues, pull requests, automatic checks on PRs, etc.
      
        - [ ] Yes, it has side effects and you should be careful if installing to all repos in an org
        - [x] No side effects
      
      - Please provide a description of the app's functionality and what are you trying to accomplish by utilizing this app:
      
        Unchanged
      
      - For any major permissions (org admin, repo admin, etc.), can you explain what they are and why they are needed?
      
        Unchanged
      
      - Any other notes or information can you provide about the app?

3. Submit the issue

4. Notify the Module Owner and Update the Issue Status

1. Add a comment to the issue you found in step 1 to let the module owner know that the repository has been created and is be ready for them to start development.

   @<module owner> The module repository has now been created. You can find it at <repository url>.
   
   The final step of repository configuration is still in progress, but you will be able to start developing your code immediately.
   
   The final step is to create the environment and credentials require to run the end to end tests. If the environment called `test` is not available in 48 hours, please let me know.
   
   Thanks

2. Add the  Status: Repository Created 📄  label to the issue

3. Remove the  Status: Ready For Repository Creation 📝  label from the issue