How Terrateam works

Terrateam is a powerful GitHub application that seamlessly integrates with your Terraform workflow, enabling you to manage your infrastructure as code directly from your pull requests. Let’s dive into how Terrateam works under the hood.

Architecture overview

Terrateam consists of two main components:

Terrateam Backend

The backend receives GitHub events and makes decisions based on the event payload. It orchestrates the execution of Terraform operations and manages the state of your infrastructure.

Terrateam Runner

The runner is responsible for executing the Terraform jobs created by the backend. It interacts with your GitHub repository, performs the necessary Terraform commands, and reports the results back to the backend.

Workflow

Here’s a high-level overview of how Terrateam works:

1. Event Trigger

   A user performs an action on GitHub, such as opening a pull request, updating it, or commenting on it. This action triggers an event that is sent to the Terrateam backend.

2. Event Evaluation

   The Terrateam backend evaluates the received event to determine if a Terraform operation needs to be executed. It analyzes the changes in the pull request and decides whether to trigger a plan or apply operation.

3. Workflow Dispatch

   If the backend determines that a Terraform operation is required, it dispatches a GitHub Actions workflow to the Terrateam runner. The workflow contains the necessary information and instructions for executing the Terraform commands.

4. Terraform Execution

   The Terrateam runner receives the workflow dispatch and starts executing the Terraform operations. It clones your GitHub repository, sets up the necessary environment, and runs the Terraform commands (e.g., terraform plan or terraform apply) for each modified directory.

5. Result Reporting

   Once the Terraform execution is complete, the Terrateam runner collects the results and sends them back to the Terrateam backend. The results include the output of the Terraform commands, any changes made to the infrastructure, and the overall status of the operation.

6. Feedback and Notifications

   The Terrateam backend processes the received results and provides feedback to the user. It adds comments to the pull request with the Terraform plan output, updates the status checks, and notifies the relevant stakeholders about the outcome of the operation.

Key features

Terrateam offers several key features that enhance your Terraform workflow:

Plan and Apply Operations

Terrateam allows you to manually trigger Terraform plan and apply operations directly from your pull requests. You can review the proposed changes, collaborate with your team, and apply the changes when ready.

Automatic Plan and Apply

Terrateam can automatically trigger plan operations when a pull request is opened or updated, and apply the changes when the pull request is merged. This streamlines your workflow and ensures that your infrastructure stays in sync with your code.

Locking and Concurrency

Terrateam implements intelligent locking mechanisms to prevent concurrent modifications to the same resources. It ensures that only one apply operation can be executed at a time for a given directory and workspace, maintaining the integrity of your infrastructure state.

Customizable Workflows

Terrateam allows you to customize your Terraform workflows using a configuration file. You can define custom plan and apply steps, set up notifications, and integrate with other tools and services to tailor Terrateam to your specific needs.

Architecture diagram

Here’s a visual representation of Terrateam’s architecture:

In this diagram:

1. The GitHub pull request triggers an event (e.g., open, close, comment) that is sent to the Terrateam backend.

2. The Terrateam backend evaluates the event and dispatches a workflow to GitHub Actions if a Terraform operation is required.

3. GitHub Actions (the Terrateam runner) executes the Terraform commands and sends the results back to the Terrateam backend.

4. The Terrateam backend processes the results and provides feedback and notifications to the GitHub pull request.

Hierarchy of repositories

Terrateam organizes your Terraform code using the following hierarchy:

• Repository: The top-level entity that represents your GitHub repository.
• Directory: A repository can contain zero or more directories, each representing a logical grouping of Terraform resources.
• Workspace: Each directory can have one or more workspaces, allowing you to use the same Terraform code in different contexts. If no workspace is specified, each directory has a default workspace.

This hierarchy enables you to structure your Terraform code in a modular and reusable way, making it easier to manage and maintain your infrastructure.