Terraform Core Team Repository Creation Process

This section describes the process for AVM owners who are responsible for creating their Terraform Module repositories.

Important

If this process is not followed exactly, it may result in your repository and any in progress code being permanently deleted. Please ensure you follow the steps exactly as described below.

1. Add yourself to the Module Owners Team

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 organization
  3. Navigate to Core Identity and request access to the Azure Verified Module Owners Terraform entitlement
Info

Please note that until your request is approved to join the Azure Verified Module Owners Terraform entitlement, you will only be able to contribute to your new repository if you JIT elevate first.

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

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

    # 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. Click Complete Setup, then use the following table to provide the settings:

    QuestionAnswer
    Classify the repositoryProduction
    Assign a Service tree or Opt-outAzure Verified Modules / AVM
    Direct ownersAdd 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 projectYes, creating an open source licensed project
    What type of open source will this beSample code
    What license will you be releasing withMIT
    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 cryptographyNo
    Project nameAzure Verified Module (Terraform) for ‘module name’
    Project version1
    Project descriptionAzure Verified Module (Terraform) for ‘module name’. Part of AVM project - https://aka.ms/avm
    Business goalsCreate 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 permissionsLeave empty
    Write permissionsLeave empty
    Repository templateUncheck
    Add .gitignoreUncheck

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

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

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

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

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

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

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

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