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 susbcription. Also if more than two subscriptions are required for testin, 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.

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:

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.

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-<RP>-<modulename>-module-owners-tf = AVM Terraform Module Owners
• Write: avm-res-<RP>-<modulename>-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-<RP>-<modulename>-module-owners-tf
• AVM Resource Module Contributors: avm-res-<RP>-<modulename>-module-contributors-tf
• AVM Core Team Technical (Terraform): avm-core-team-technical-terraform

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.

You don’t need to run grept manaully because it will be executed with the help of a cron job 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.

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

6. Elevate your respository access using the Open Source Management Portal (aka.ms/opensource/portal).
7. Sign in to the HashiCorp Registry 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.

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