Terraform Contribution Flow

flowchart TD
A(1. Fork the module source repository)
  click A "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#1-fork-the-module-source-repository"
B(2. Setup your Azure test environment)
  click B "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#2-prepare-your-azure-test-environment"
C(3. Implement your contribution)
  click C "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#3-implement-your-contribution"
D{4. Pre-commit Checks 
 succesful?}
  click D "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#4-run-pre-commit-checks"
E(5. Create a pull request to the upstream repository)
  click E "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#5-create-a-pull-request-to-the-upstream-repository"
A --> B
B --> C
C --> D
D -->|yes|E
D -->|no|C

The GitFlow process outlined here depicts and suggests a way of working with Git and GitHub. It serves to synchronize the forked repository with the original upstream repository. It is not a strict requirement to follow this process, but it is highly recommended to do so.

%%{init: { 'logLevel': 'debug', 'gitGraph': {'rotateCommitLabel': false}} }%%
gitGraph LR:
commit id:"fork"
branch fork/main
checkout fork/main
commit id:"checkout feature" type: HIGHLIGHT
branch feature
checkout feature
commit id:"checkout fix"
branch fix
checkout main
merge feature id: "Pull Request 'Feature'" type: HIGHLIGHT
checkout fix
commit id:"Patch 1"
commit id:"Patch 2"
checkout main
merge fix id: "Pull Request 'Fix'" type: HIGHLIGHT

When implementing the GitFlow process as described, it is advisable to configure the local clone of your forked repository with an additional remote for the upstream repository. This will allow you to easily synchronize your locally forked repository with the upstream repository. Remember, there is a difference between the forked repository on GitHub and the clone of the forked repository on your local machine.

Each time in the following sections we refer to ‘your xyz’, it is an indicator that you have to change something in your own environment.

Each Terraform AVM module will have its own GitHub repository in the Azure GitHub Organization as per SNFR19.

This repository will be created by the Module owners and the AVM Core team collaboratively, including the configuration of permissions as per SNFR9

Module contributors are expected to fork the corresponding repository and work on a branch from within their fork, before then creating a Pull Request (PR) back into the source repository’s main branch.

To do so, simply navigate to your desired repository, select the 'Fork' button to the top right of the UI, select where the fork should be created (i.e., the owning organization) and finally click ‘Create fork’.

If the module repository you want to contribute to is not yet available, please get in touch with the respective module owner which can be tracked in the Terraform Resource Modules index see PrimaryModuleOwnerGHHandle column.

Optional: The usage of local source branches

For consistent contributors but also Azure-org members in general it is possible to get invited as collaborator of the module repository which enables you to work on branches instead of forks. To get invited get in touch with the module owner since it’s the module owner’s decision who gets invited as collaborator.

AVM performs end-to-end (e2e) test dpeloyments of all modules in Azure for validation. We recommend you to perform a local e2e test deployment of your module before you create a PR to the upstream repository. Especially because the e2e test deployment will be triggered automatically once you create a PR to the upstream repository.

1. Have/create an Azure Active Directory Service Principal with at least Contributor & User Access Administrator permissions on the Management-Group/Subscription you want to test the modules in. You might find the following links useful:

   • Create a service principal (Azure CLI) - Recommended
   • Create a service principal (Azure Portal)
   • Create a service principal (PowerShell)
   • Find Service Principal object ID
   • Find managed Identity Service Principal
   • Note down the following pieces of information
   • Application (Client) ID
   • Service Principal Secret (password)
   • Optional: Tenant ID
   • Optional: Subscription ID

   # Linux/MacOs
   export ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) # or set <subscription_id>
   export ARM_TENANT_ID=$(az account show --query tenantId --output tsv) # or set <tenant_id>
   export ARM_CLIENT_ID=<client_id>
   export ARM_CLIENT_SECRET=<service_principal_password>
   
   # Windows/Powershell
   $env:ARM_SUBSCRIPTION_ID = $(az account show --query id --output tsv) # or set <subscription_id>
   $env:ARM_TENANT_ID = $(az account show --query tenantId --output tsv) # or set <tenant_id>
   $env:ARM_CLIENT_ID = "<client_id>"
   $env:ARM_CLIENT_SECRET = "<service_principal_password>"
   

2. Change to the root of your module repository and run ./avm docscheck (Linux/MacOs) / avm.bat docscheck (Windows) to verify the container image is working as expected or needs to be pulled first. You will need this later.

   

To implement your contribution, we kindly ask you to first review the shared & Terraform-specific specifications and composition guidelines in particular to make sure your contribution complies with the repository’s design and principles.

Make sure you have Docker installed and running on your machine.

To simplify and help with the execution of commands like pre-commit, pr-check, docscheck, fmt, test-example, etc. there is now a simplified avm script available distributed to all repositories via terraform-azurerm-avm-template which combines all scripts from the avm_scripts folder in the tfmod-scaffold repository using avmmakefile.

The avm script also makes sure to pull the latest mcr.microsoft.com/azterraform:latest container image before executing any command.

The following commands will run all pre-commit checks and the pr-check.

# Running all pre-commit checks
# `pre-commit` runs depsensure fmt fumpt autofix docs
# `pr-check` runs fmtcheck tfvalidatecheck lint unit-test

## Linux/MacOs
./avm pre-commit
./avm pr-check

## Windows
avm.bat pre-commit
avm.bat pr-check

Currently you have two options to run e2e tests:

With the help of the avm script and the commands ./avm test-example (Linux/MacOs) / avm.bat test-example (Windows) you will be able to run it in a more simplified way. Currently the test-example command is not completely ready yet and will be released soon. Therefore please use the below docker command for now.

1. Run e2e tests with the help of the azterraform docker container image.

   # Linux/MacOs
   
   docker run --rm -v $(pwd):/src -w /src -v $HOME/.azure:/root/.azure -e TF_IN_AUTOMATION -e AVM_MOD_PATH=/src -e AVM_EXAMPLE=<example_folder> -e ARM_SUBSCRIPTION_ID -e ARM_TENANT_ID -e ARM_CLIENT_ID -e ARM_CLIENT_SECRET mcr.microsoft.com/azterraform:latest make test-example
   
   # Powershell
   
   docker run --rm -v ${pwd}:/src -w /src -v $HOME/.azure:/root/.azure -e TF_IN_AUTOMATION -e AVM_MOD_PATH=/src -e AVM_EXAMPLE=<example_folder> -e ARM_SUBSCRIPTION_ID -e ARM_TENANT_ID -e ARM_CLIENT_ID -e ARM_CLIENT_SECRET mcr.microsoft.com/azterraform:latest make test-example
   

   Make sure to replace <client_id> and <service_principal_password> with the values of your service principal as well as <example_folder> (e.g. default) with the name of the example folder you want to run e2e tests for.

2. Run e2e tests with the help of terraform init/plan/apply.

   Simply run terraform init and terraform apply in the example folder you want to run e2e tests for. Make sure to set the environment variables ARM_SUBSCRIPTION_ID, ARM_TENANT_ID, ARM_CLIENT_ID and ARM_CLIENT_SECRET before you run terraform init and terraform apply or make sure you have a valid Azure CLI session and are logged in with az login.

Once you are satisfied with your contribution and validated it, open a PR from your forked repository to the original Terraform Module repository. Make sure you:

1. Include/Add @Azure/avm-core-team-technical-terraform as a reviewer.
2. Make sure all Pull Requst Checks (e2e tests with all examples, linting and version-check) are passing.
3. Watch comments from the PR checks and reviewers (Module owner or AVM core team) and address them accordingly.
4. Once your PR is approved, merge it into the upstream repository and the Module owner will publish the module to the HashiCorp Terraform Registry.

• If you contribute to a new module then search and update TODOs (which are coming with the terraform-azurerm-avm-template) within the code and remove the TODO comments once complete
• terraform.lock.hcl shouldn’t be in the repository as per the .gitignore file
• Update the support.md file
• Consider updating version to 0.1.0 as the first version that would be published into the terraform registry per spec SNFR17
• Set prevent_deletion_if_contains_resources to false in provider block in example code per spec TFNFR36
• The Contributor and Owner teams are not added to the repository per spec SNFR20
• \_header.md needs to be updated
• readme.md needs to be generated as per spec SNFR15 & TFNFR2
• support.md needs to be updated
• locals.telemetry.tf needs to be updated
• Define outputs like Resource Name, ID and Object in outputs.tf per specs RMFR7 & TFFR2
• Consider setting a constraint on maximum major version of Provider per spec TFNFR26 in terraform.tf flle
• Exclude terraform.tfvars file from the repository
• Make sure to have all interfaces defined as per spec RMFR5
• Declaration of provider in module should be as per spec TFNFR27 in main.tf
• CODEOWNERS file needs to be updated as per spec SNFR9 & SNFR20
• The module is WAF Aligned as per spec SFR2
• Availability Zones are used (zonal or zone-redundant where applicable) as per spec SFR5
• Cross-reagion replication (data redundancy) used where applicable as per spec SFR6
• Cross-language collaboration as per spec SNFR21
• RP/PG collaboration as per RMNFR3