Terraform Owner Contribution Flow

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

This contribution flow is for Module owners only.

As a Terraform Module Owner you need to be aware of the AVM contribution process overview & shared specifications (including Interfaces) and Terraform-specific specifications as as these need to be considered during pull request reviews for the modules you own.

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 subscription. Also if more than two subscriptions are required for testing, that’s currently not supported.

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.

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.

Familiarise yourself with the AVM Resource Module Naming in the module index csv’s.

• Example: terraform-<provider>-avm-res-<rp>-<ARM resource type>

Make sure you have access to the Azure organisation see GitHub Account Link and Access.

1. Create the module repostory using terraform-azuremrm-avm-template in the Azure organisation with the following details (internal only). You will then have to complete the configuration of your repository and start an internal business review.

2. Create GitHub teams as outlined in SNFR20 and add respective parent teams:

   Segments:

   • avm-res-<RP>-<modulename>-module-owners-tf
   • avm-res-<RP>-<modulename>-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-<RP>-<modulename>-module-owners-tf team.

3. Add these teams with the following permissions directly to the repository:

   • Admin: avm-core-team-technical-terraform = AVM Core Team (Terraform Technical)
   • Admin: terraform-avm = Terraform PG
   • Admin: avm-res-<RP>-<modulename>-module-owners-tf = AVM Terraform Module Owners
   • Write: avm-res-<RP>-<modulename>-module-contributors-tf = AVM Terraform Module Contributors

4. 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. The respoitory environment test will be automatically created within 4 hours, it will have approvals and secrets applied to it ready to run end to end tests. You should not create this environment manually.

   • If you wish 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.

As per SNFR23 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.

Set-AvmGitHubLabels.ps1 -RepositoryName "Azure/MyGitHubRepo" -CreateCsvLabelExports $false -NoUserPrompts $true

1. Add new owner as maintainer in your avm-res-<RP>-<modulename>-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).

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.

1. Set environment variables

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

# Windows

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

1. Run grept

# Linux/MacOS
./avm grept-apply

# Windows
avm.bat grept-apply

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.

Once a module has been reviewed 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. 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 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. Just go to the releases tab and click on Draft a new release. Make sure to create the tag from the main branch.

2. Elevate your respository access using the Open Source Management Portal (aka.ms/opensource/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.

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.

When an AVM Module is published to the HashiCorp Registry, it MUST follow the below requirements:

• Resource Module: terraform-<provider>-avm-res-<rp>-<ARM resource type> as per RMNFR1
• Pattern Module: terraform-<provider>-avm-ptn-<patternmodulename> as per PMNFR1