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

Familiarize 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 create your new repository.

Follow the Repository Creation Process to create your new repository.

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 ready 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 respository has an environment called test, it has have approvals and secrets applied to it ready to run end to end tests.

• In the unusual circumstance 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.
   • If this is a community contribution be sure to update the ‘Release Notes` to provide appropriate credit to the contributors.

   

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 owners who are responsible for creating their Terraform Module repositories.

1. Add yourself to the Module Owners Team and Open Source orgs

If you have already done this, then you don’t need to do it again and can skip this section.

1. Open the Open Source Portal and ensure you GitHub account is linked to your Microsoft account
2. Open the Open Source Portal and ensure you are a member of the Azure and Microsoft organizations (you need to be a member of both for this process to work)
3. Navigate to Core Identity and request access to the Azure Verified Module Owners Terraform entitlement

2. Get the information you need for Repository Creation

You’ll need to gather the following information from the module request issue and other sources:

1. Module name: This will be in the format avm-<type>-<name>. e.g. avm-res-network-virtualnetwork
2. Module owner GitHub handle: This is your own GitHub handle
3. Module owner display name: This is your name in the format Firstname Lastname. This is used to display the module owner in the module index CSV file
4. Module description: The description will automatically be prefixed with Terraform Azure Verified <module-type> Module for ..., where <module-type> is either Resource, Pattern, or Utility
5. Resource provider namespace: This is only required for resource modules. You may need to look this up in the Azure Documentation if not included in the issue. For example, Microsoft.Network for a Virtual Network module
6. Resource type: This is only required for resource modules. You may need to look this up in the Azure Documentation if not included in the issue. For example, virtualNetworks for a Virtual Network module
7. Module alternative names: Consider if it would be useful to search for this module using other names. If so, add them here. This is a comma separated list of names
8. Owner secondary GitHub handle: This is optional. If the module has a secondary owner GitHub handle
9. Owner secondary display name: This is optional. If the module has a secondary owner, get their display name in the format Firstname Lastname. This is used to display the module owner in the module index CSV file

3. Create the repository

1. Check you have the latest version of the Terraform CLI installed. You can do this by running terraform -version in a terminal. If you don’t have it installed, you can download it from the Terraform website.

2. Check you have the latest version of the Azure CLI installed. You can do this by running az --version in a terminal. If you don’t have it installed, you can download it from the Azure CLI website.

3. Check you have the latest version of the PowerShell Core installed. You can do this by running pwsh -version in a terminal. If you don’t have it installed, you can download it from the PowerShell website.

4. Open a PowerShell core terminal

5. Clone the https://github.com/Azure/avm-terraform-governance repository and navigate to the tf-repo-mgmt folder

   cd ~
   git clone "https://github.com/Azure/avm-terraform-governance"
   cd ./avm-terraform-governance/tf-repo-mgmt

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

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

8. If you are not already logged in to the Azure CLI, you’ll need to be to avoid an error. You don’t need to be connected to any specific subscription or tenant, just a valid session. If you are not logged in, you can run the following command to login to a non specific session:

   az login --scope https://graph.microsoft.com/.default --allow-no-subscriptions

9. Run the following command, replacing the values with the details you collected in step 2

   if(!(Test-Path -Path "./scripts/New-Repository.ps1")) {
       Write-Error "This script must be run from the tf-repo-mgmt directoy. Please switch to the tf-repo-mgmt directory and try again."
       exit 1
   }
   
   # Required Inputs
   $moduleProvider = "azurerm" # Only change this if you know why you need to change it (Allowed values: azurerm, azapi, azure)
   $moduleName = "<module name>" # Replace with the module name (do not include the "terraform-azurerm" prefix)
   $moduleDisplayName = "<module description>" # Replace with a short description of the module
   $resourceProviderNamespace = "" # Replace with the resource provider namespace of the module (NOTE: Leave empty for Pattern or Utility Modules)
   $resourceType = "" # Replace with the resource type of the module (NOTE: Leave empty for Pattern or Utility Modules)
   $ownerPrimaryGitHubHandle = "<github user handle>" # Replace with the GitHub handle of the module owner
   $ownerPrimaryDisplayName = "<user display name>" # Replace with the display name of the module owner
   
   # Optional Metadata Inputs
   $moduleAlternativeNames = "" # Replace with a comma separated list of alternative names for the module
   $ownerSecondaryGitHubHandle = "" # Replace with the GitHub handle of the module owner
   $ownerSecondaryDisplayName = "" # Replace with the display name of the module owner
   
   ./scripts/New-Repository.ps1 `
       -moduleProvider $moduleProvider `
       -moduleName $moduleName `
       -moduleDisplayName $moduleDisplayName `
       -resourceProviderNamespace $resourceProviderNamespace `
       -resourceType $resourceType `
       -ownerPrimaryGitHubHandle $ownerPrimaryGitHubHandle `
       -ownerPrimaryDisplayName $ownerPrimaryDisplayName `
       -moduleAlternativeNames $moduleAlternativeNames `
       -ownerSecondaryGitHubHandle $ownerSecondaryGitHubHandle `
       -ownerSecondaryDisplayName $ownerSecondaryDisplayName

   For example:

   if(!(Test-Path -Path "./scripts/New-Repository.ps1")) {
       Write-Error "This script must be run from the tf-repo-mgmt directoy. Please switch to the tf-repo-mgmt directory and try again."
       exit 1
   }
   
   # Required Inputs
   $moduleProvider = "azurerm" # Only change this if you know why you need to change it (Allowed values: azurerm, azapi, azure)
   $moduleName = "avm-res-network-virtualnetwork" # Replace with the module name (do not include the "terraform-azurerm" prefix)
   $moduleDisplayName = "Virtual Networks" # Replace with a short description of the module
   $resourceProviderNamespace = "Microsoft.Network" # Replace with the resource provider namespace of the module (NOTE: Leave empty for Pattern or Utility Modules)
   $resourceType = "virtualNetworks" # Replace with the resource type of the module (NOTE: Leave empty for Pattern or Utility Modules)
   $ownerPrimaryGitHubHandle = "jaredfholgate" # Replace with the GitHub handle of the module owner
   $ownerPrimaryDisplayName = "Jared Holgate" # Replace with the display name of the module owner
   
   # Optional Metadata Inputs
   $moduleAlternativeNames = "VNet" # Replace with a comma separated list of alternative names for the module
   $ownerSecondaryGitHubHandle = "" # Replace with the GitHub handle of the module owner
   $ownerSecondaryDisplayName = "" # Replace with the display name of the module owner
   
   ./scripts/New-Repository.ps1 `
       -moduleProvider $moduleProvider `
       -moduleName $moduleName `
       -moduleDisplayName $moduleDisplayName `
       -resourceProviderNamespace $resourceProviderNamespace `
       -resourceType $resourceType `
       -ownerPrimaryGitHubHandle $ownerPrimaryGitHubHandle `
       -ownerPrimaryDisplayName $ownerPrimaryDisplayName `
       -moduleAlternativeNames $moduleAlternativeNames `
       -ownerSecondaryGitHubHandle $ownerSecondaryGitHubHandle `
       -ownerSecondaryDisplayName $ownerSecondaryDisplayName

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

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

12. If you see the Complete Setup link, then follow the steps below in 3.1. If you don’t see the Complete Setup link, then follow the steps in 3.2.

3.1 Complete Setup Link is Present

1. 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 yourself and jaredholgate or mawhi as the direct owners. Add the avm-team-module-owners as the fallback 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

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

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

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

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

3.2 Complete Setup Link is Not Present

1. Click on the Compliance tab

2. Fill out the 3 sections as follows, saving each:

   Question	Answer
   Direct owners	Add yourself and jaredholgate or mawhi as the direct owners. Add the avm-team-module-owners as the fallback security group.
   Classify the repository	Production
   Assign a Service tree	Azure Verified Modules / AVM

3. Head back to the Overview tab

4. If you don’t see the Elevate your access button, this is likely because you already have temporary admin rights from creating the repository. In that case you’ll see You currently have native Administrator permission to this repository on GitHub. and you can skip the next step

5. If you do see the Elevate your access button, click it and follow the prompts to elevate your access

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

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

8. The script will automatically create a pull request to add the module metadata to the avm-terraform-governance repository. This will be approved and merged by the core team. You can find it here if you lost the link.

9. The script will automatically create an issue to install the Azure Verified Modules GitHub App in the repository. This will be actioned by the open source team. You can find it here if you lost the link.

4. Update the Issue Status

1. Add the  Status: Repository Created 📄  label to the issue
2. Remove the  Status: Ready For Repository Creation 📝  label from the issue if it was added

5. Wait for the GitHub App to be installed

Once the GitHub App has been installed via the issue raised by the script, the sync to create the environment and credentials will be triggered automatically at 15:30 UTC on week days. This will complete the repository creation process.

The open source team will usually complete this within 24 hours, but it can take longer in some cases.