Unleash the Power of Terraform Cloud with GitHub Hooks

Image source: Automate Terraform with GitHub Actions

Introduction:

In the growing world of Infrastructure as Code (IaC), Terraform is emerging as the tool of choice for the tool of choice for provisioning and managing services across various cloud platforms like AWS, GCP, Azure, etc.

When combined with GitHub, collaboration possibilities are endless. In this comprehensive blog, we will embark on a journey of seeing a seamless integration of Terraform Cloud with GitHub commit hooks, automating tests and validation on every pull request.

So, buckle up for a deep dive into the intricate steps that will empower your infrastructure workflows.

Prerequisites:

Terraform Cloud Account:

• If you don’t have an account, sign up for Terraform Cloud here -> https://app.terraform.io/public/signup/account

GitHub Repository:

• Create a GitHub repository to host your Terraform code. Follow this guide if you need help creating your first GitHub repository - https://docs.github.com/en/desktop/overview/creating-your-first-repository-using-github-desktop
• Familiarize yourself with basic Git commands for efficient version control. Learn about the version control system, Git, and how it works with GitHub here - https://docs.github.com/en/get-started/using-git/about-git

Access to Terraform CLI:

• Install Terraform CLI on your local machine.
• Refer to Terraform’s official guide for installation of Terraform based on your operating system- https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli

And now, let’s begin the main task…

Step 1: Set Up a Webhook in GitHub

1.1 GitHub Webhook Configuration:

Navigate to your GitHub repository.

In the “Settings” tab, select “Webhooks”

Click “Add webhook” and fill in the details:

• Payload URL: Enter the Terraform Cloud webhook endpoint.
• Content type: Set it to application/json.
• Events: Choose push and pull_request.

Save the webhook.

Example Payload URL:

https://<TFE_HOSTNAME>/api/v2/webhooks/<WORKSPACE_ID>

1.2 GitHub Access Token:

Generate a GitHub access token with repo and workflow scopes by following the below steps:

• On github.com in a browser, in the upper-right corner of any page, click your profile photo, then go to this path ‘Settings -> Developer settings -> Personal access tokens -> Generate new token’

• Enter a descriptive text and select repo and workflow boxes, and click on ‘Generate Token’

Note: For a detailed guide on how to create a token in GitHub, please refer to this guide — https://docs.github.com/en/enterprise-server@3.9/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

Step 2: Configure the Terraform Cloud Workspace

2.1 VCS Connection:

• In your Terraform Cloud workspace, navigate to “Settings”
• Under “Version Control” -> “Providers” select “GitHub.com” as the provider
• Enter your GitHub repository URL
• Paste the GitHub access token generated earlier in Step 1

Step 3: Create a Sentinel Policy

3.1 Sentinel Policy Definition:

• Sentinel policies are crucial for governance and compliance. These policies ensure that your Terraform workspace and code are compliant with necessary standards.
• You can create a simple Sentinel policy to control security groups. One such example is below:

# sentinel.hcl
import "tfplan/v2" as tfplan

main = rule {
  all tfplan.resources.aws_security_group as _, sg {
    all sg.attributes.ingress as _, ingress {
      ingress.cidr_blocks != ["0.0.0.0/0"]
    }
  }
}

• In your Terraform Cloud workspace, go to “Policies”
• Set the enforcement level to “Hard Mandatory”
• Paste the above code and press ‘Create policy’

Step 5: Create a Terraform Script

5.1 Sample Terraform Script:

• Assuming you have created a GitHub repository in prerequisites step, you can create a simple Terraform file and push the same to GitHub by running the following commands.

# Clone your github repository
git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY

# Navigate to your git directory
cd YOUR-REPOSITORY

• Create a simple Terraform script (main.tf) in your current directory:

# main.tf
resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}

# sentinel.hcl
import "tfplan/v2" as tfplan

main = rule {
  all tfplan.resources.aws_instance as _, instance {
    instance.attributes.instance_type == "t2.micro"
  }
}

Step 6: Push Changes to GitHub

After the above step, you can commit and push these changes to GitHub bu running the following commands:

git add .
git commit -m "Update Terraform code"
git push origin main

Step 7: Observe Terraform Cloud Run

• Terraform Cloud will automatically trigger a run and apply the changes.
• Simultaneously, Sentinel policies will be enforced, ensuring compliance.

Step 8: Create a Pull Request

Extend the automation to pull requests:

• Create a branch: git checkout -b feature/test-trigger
• Make changes to main.tf. In this, you can simply a another comment so that GitHub will detect some changes in the pull request.
• Push changes: git push origin feature-branch
• Create a pull request by navigating to GitHub -> Pull Requests -> New Pull requests. In this, set the base branch to main and source branch to feature/test-trigger

Terraform Cloud will once again trigger a run, providing a comprehensive validation of your code during the pull request phase. You can view the same in Terraform Cloud.

Conclusion:

The integration of Terraform Cloud with GitHub commit hooks elevates your infrastructure development workflows. By automating tests, validations, and compliance checks on each pull request, you not only enhance collaboration but also fortify the reliability of your infrastructure deployments.

This in-depth guide is designed to equip you with the knowledge to seamlessly integrate these powerful tools. Remember, while this guide offers a solid foundation, your specific requirements may demand further customization. Consult the official Terraform and Sentinel documentation for advanced configurations and optimizations.

References:

• Terraform Editions
• GitHub Webhooks
• Sentinel policies and Terraform

NOTE:

This article was originally posted on WeAreCommunity of EPAM Systems: Unleash the Power of Terraform Cloud with GitHub Hooks