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.
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 deployments 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.
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>"
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 viaterraform-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 thetest-example
command is not completely ready yet and will be released soon. Therefore please use the below docker command for now.
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.Run e2e tests with the help of terraform init/plan/apply.
Simply run
terraform init
andterraform apply
in theexample
folder you want to run e2e tests for. Make sure to set the environment variablesARM_SUBSCRIPTION_ID
,ARM_TENANT_ID
,ARM_CLIENT_ID
andARM_CLIENT_SECRET
before you runterraform init
andterraform apply
or make sure you have a valid Azure CLI session and are logged in withaz login
.
Once you are satisfied with your contribution and validated it, submit a pull request to the upstream repository and work with the module owner to get the module reviewed by the AVM Core team, by following the initial module review process for Terraform Modules, described here. This is a prerequisite for publishing the module. Once the review process is complete and your PR is approved, merge it into the upstream repository and the Module owner will publish the module to the HashiCorp Terraform Registry.
These steps are performed by the contributor:
- Navigate to the upstream repository and click on the
Pull requests
tab. - Click on the
New pull request
button. - Ensure the
base repository
is set to the upstream AVM repo. - Ensure the
base
branch is set tomain
. - Ensure your
head repository
andcompare
branch are set to your fork and the branch you are working on. - Click on the
Create pull request
button.
- IMPORTANT: The module owner must first check for any malicious code or changes to workflow files. If they are found, the owner should close the PR and report the contributor.
- Review the changes made by the contributor and determine whether end to end tests need to be run.
- If end to end tests do not need to be run (e.g. doc changes, small changes, etc) then so long as the static analysis passes, the PR can be merged to main.
- If end to end tests do need to be run, then follow the steps in 5.3.
- IMPORTANT: The module owner must first check for any malicious code or changes to workflow files. If they are found, the owner should close the PR and report the contributor.
- Create a release branch from
main
. Suggested naminmg convention isrelease/<description-of-change>
. - Open the PR created by the contributor and click
Edit
at the top right of the PR. - Change the
base
branch to the release branch you just created. - Wait for the PR checks to run, validate the code looks good and then merge the PR into the release branch.
- Create a new PR from the release branch to the
main
branch of the AVM module. - The end to end tests should trigger and you can approve the run.
- Once the end to end tests have passed, merge the PR into the
main
branch. - If the end to end tests fail, investigate the failure. You have two options:
- Work with the contributor to resolve the issue and ask them to submit a new PR from their fork branch to the release branch.
- Re-run the tests and merge to
main
. Repeat the loop as required.
- Re-run the tests and merge to
- If the issue is a simple fix, resolve it directly in the release branch, re-run the tests and merge to
main
.
- Work with the contributor to resolve the issue and ask them to submit a new PR from their fork branch to the release branch.
- 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 theTODO
comments once complete terraform.lock.hcl
shouldn’t be in the repository as per the.gitignore
file- Update the
support.md
file \_header.md
needs to be updatedsupport.md
needs to be updated- Exclude
terraform.tfvars
file from the repository