GitHub Actions Workflows for Terraform

This is a sample repository that shows how to build GitHub Actions workflows to manage infrastructure with Terraform.

Architecture

Dataflow

1. Create a new branch and check in the needed Terraform code modifications.
2. Create a Pull Request (PR) in GitHub once you're ready to merge your changes into your environment.
3. A GitHub Actions workflow will trigger to ensure your code is well formatted. In addition, a Terraform Plan analysis should run to generate a preview of the changes that will happen in your Azure environment.
4. Once appropriately reviewed, the PR can be merged into your main branch.
5. Another GitHub Actions workflow will trigger from the main branch and execute the changes using Terraform.
6. A regularly scheduled GitHub Action workflow should also run to look for any configuration drift in your environment and create a new issue if changes are detected.

Workflows

1. Terraform Unit Test

   This workflow is designed to be run on every commit and is composed of a set of unit tests on the infrastructure code. It runs terraform fmt to ensure the code is properly linted and follows terraform best practices. Next it performs terraform validate to check that the code is syntactically correct and internally consistent.

2. Terraform Plan / Apply

   This workflow runs on every pull request and on each commit to the main branch. The plan stage of the workflow is used to understand the impact of the IaC changes on the Azure environment by running terraform plan. This report is then attached to the PR for easy review. The apply stage runs after the plan when the workflow is triggered by a push to the main branch. This stage will take the plan document and apply the changes after a manual review has signed off if there are any pending changes to the environment.

3. Terraform Drift Detection

   This workflow runs on a periodic basis to scan your environment for any configuration drift (i.e. changes made outside of terraform). If any drift is detected a GitHub Issue is raised to alert the maintainers of the project.

Getting Started

To use these workflows in your environment several prerequiste steps are required:

1. Create GitHub Environments

   The workflows utilizes GitHub Environments to store the azure identity information and setup an appoval process for deployments. Create 2 environments: production-readonly and production-readwrite by following these insturctions. On the production-readwrite environment setup a protection rule and add any required approvers you want that need to sign off on production deployments. You can also limit the environment to your main branch. Detailed instructions can be found here.

2. Setup Azure Identity:

   An Azure Active Directory application is required that has permissions to deploy within your Azure subscription. Create a separate application for the production-readonly and production-readwrite environments and give them the appropriate permissions in your Azure subscription. Next setup the federated credentials to allow the GitHub environments to utilize the identity using OIDC. See the Azure documentation for detailed instructions. Make sure to set the Enitity Type to Environment and use the appropriate environment name for the GitHub name.

3. Add GitHub Secrets

   For each GitHub Environment create the following secrets for the respective Azure Identity:

   • AZURE_CLIENT_ID : The application (client) ID of the app registration in Azure
   • AZURE_TENANT_ID : The tenant ID of Azure Active Directory where the app registration is defined.
   • AZURE_SUBSCRIPTION_ID : The subscription ID where the app registration is defined.

   Instuructions to add the secrets to the environment can be found here.

4. Configure Terraform State Location

   Terraform utilizes a state file to store information about the current state of your managed infrastructure and associated configuration. This file will need to be persisted between different runs of the workflow. The recommended approach is to store this file within an Azure Storage Account or other similiar remote backend. The Terraform backend block TODO: add link will need to be configured to point to an appropriate location where your workflow has permissions. Normally this location would be created manually or via a separate workflow.

5. Activate the Workflows

   In each workflow file uncomment the top trigger section to enable the workflows to run automatically.