DOCSEARCHbyAlgolia
Submit Docs

Terrateam Documentation

repository·main·Indexed 20 days ago

https://github.com/terrateamio/terrateam

An open-source Terraform automation platform for GitOps workflows that integrates with pull requests to automate infrastructure plans and applies. It supports Terraform, OpenTofu, Terragrunt, CDKTF, and Pulumi, featuring tag-based configuration for scaling across monorepos, policy enforcement via OPA/Rego and Checkov, and options for Hosted SaaS or self-hosting via Docker Compose.

Tokens
101.8K
Snippets
313
Records
494
Agent score
78%

What's inside Terrateam

  1. Overview of Terrateam features

    main

    Terrateam is an open-source Terraform automation tool designed for GitOps workflows in pull requests. Key capabilities include:

    • GitOps Automation: Automates Terraform/OpenTofu plans and applies directly in pull requests, including pre and post-merge applies.
    • Scalable Configuration: Uses tag-based configuration to manage workspaces across monorepos or multiple repositories.
    • Flexible Tooling: Supports Terraform, OpenTofu, Terragrunt, CDKTF, Pulumi, and any arbitrary CLI.
    • Policy Enforcement: Integrates with OPA/Rego, Checkov, and built-in policy engines to enforce infrastructure rules.
    • Safety & Visibility: Provides smart locking for parallel execution, cost estimation, drift detection, and a full UI to track runs and view execution logs.
    • Deployment Options: Available as a Hosted SaaS or as a self-hostable solution (server and private runners).

  2. What is Terrateam?

    main
    Terrateam is an open-source GitOps CI/CD platform designed for Terraform and OpenTofu. It integrates with GitHub (via GitHub App and Actions) and GitLab to enable infrastructure management through pull requests and merge requests. It automates deployment processes, manages plan storage, handles resource locking to prevent conflicts, and provides drift detection.

  3. Compare Terrateam Open Source and Enterprise editions

    main

    Terrateam is available in two editions: Open Source (MPL-2.0, free) and Enterprise (Commercial). Both editions include the core GitOps pull request automation engine, IaC tool integrations (Terraform, OpenTofu, Terragrunt, Pulumi, CDKTF), policy enforcement (OPA, Checkov), cost estimation (Infracost), and the full UI for runs and logs.

    Key Differences

    FeatureOpen SourceEnterprise
    Drift detectionSingle schedule per repoMultiple schedules per repo
    Access Control / RBACNot availableFine-grained policies (user, team, or repo role)
    CODEOWNERS enforcementNot availableEnforces require_completed_reviews
    GatekeeperNot availableManual approval gates via tokens
    Centralized ConfigurationNot availableGlobal defaults/overrides across repos
    API Access TokensNot availableProgrammatic access via /api/v1/{vcs}/access-token
    Comment summary headerNot availableControlled via notifications.summary

  4. Key Features of Terrateam

    main

    Terrateam provides several core capabilities for managing infrastructure via GitOps:

    • Plan and Apply Operations: Manually trigger operations via PR/MR comments to review and collaborate on changes.
    • Automatic Plan and Apply: Automatically trigger plan on PR creation/updates and apply when a PR is merged.
    • Locking and Concurrency: Prevents race conditions by ensuring only one apply operation runs at a time for a specific directory and workspace.
    • Customizable Workflows: Use a configuration file to define custom plan/apply steps, notifications, and tool integrations.

  6. What is Gatekeeper and how does it work?

    main

    Gatekeeper is an Enterprise Edition feature that allows you to create manual approval gates in Terrateam workflows. When a gated workflow step (like a security scan or policy check) fails, instead of failing the entire workflow, Gatekeeper pauses execution, creates an approval request, notifies authorized approvers, and waits for manual intervention.

    Approval Mechanisms

    • Token-based gates: Require users to explicitly approve the gate using a specific command in a pull request comment. This is identified by a unique token.
    • Non-token gates: Require all requested approvers to approve the pull request in your VCS provider (e.g., GitHub/GitLab) before changes can be applied.

    Workflow Lifecycle

    1. Gated step fails: A configured step (e.g., checkov, conftest, or run) encounters a failure.
    2. Approval request created: Terrateam posts a PR comment detailing the failure, the gate token (if applicable), and the authorized approvers.
    3. Review: Authorized users review the failure.
    4. Approval granted:
      • For token-based gates: Comment terrateam gate approve <token>.
      • For non-token gates: Approve the pull request in the VCS.
    5. Workflow continues: The workflow proceeds as if the step succeeded.
    terrateam gate approve <token>

  7. Understand Apply Requirements and Deployment Strategies

    main

    Terrateam allows you to enforce specific conditions before an Apply operation can proceed. These are defined in your Terrateam configuration file.

    Apply Requirements

    Common requirements include:

    • Approvals: Requiring a specific number of approvals on the PR/MR.
    • Merge Conflicts: Ensuring the branch has no conflicts.
    • Status Checks: Ensuring all required CI/CD status checks have passed.

    Deployment Strategies

    You can choose between two main approaches:

    1. Pre-merge: Validating and applying changes before the PR/MR is merged. This is often used in conjunction with automerge to apply changes automatically once all checks pass.
    2. Post-merge: Applying changes only after the PR/MR has been merged into the main branch.

  8. How tree_builder works and its execution lifecycle

    main

    Tree builder operates as dedicated GitHub Actions workflows that run independently of the plan/apply phase.

    Workflow Logic

    1. Check Cache: Terrateam checks if a file inventory (tree) already exists for the current commit SHA in its database.
    2. Build Tree: If no tree exists, it queues a build-tree run to execute your custom script and generate the inventory.
    3. Build Config: Once the tree is stored, it queues a build-config run to load your terrateam.yml.
    4. Change Detection: When a PR is evaluated, Terrateam compares the id values for each file path in the feature branch tree against the destination branch tree. A difference in id triggers a change detection.

    PR Run Sequence

    For a new PR where neither the destination nor the feature branch has been processed, you will see multiple parallel and sequential runs:

    Destination Branch (Parallel):

    1. build-tree (runs your script)
    2. build-config (loads terrateam.yml)

    Feature Branch (Parallel):

    1. build-tree (runs your script)
    2. build-config (loads terrateam.yml)
    3. plan/apply (waits for both branch trees to be available, then compares them)

    Subsequent events on the same commit SHA will reuse the stored trees, skipping the build phases.

  9. Use the config_builder to dynamically generate configurations

    main

    The config_builder feature allows you to generate Terrateam configurations at runtime using custom scripts. This is useful when your configuration needs to depend on external data, environment variables, or complex logic that cannot be expressed in a static YAML file.

    How it works

    1. Input: Terrateam feeds the existing configuration into your script as a JSON string via stdin.
    2. Execution: The script is executed at runtime. If the script does not start with a shebang (#!), it is treated as a bash script.
    3. Output: Your script must output a new, valid repository configuration in JSON format to stdout.

    Configuration Keys

    In your .terrateam/config.yml, use the following keys under config_builder:

    • enabled (boolean): Enables or disables the feature. Defaults to false.
    • script (string): The actual script content. This is required if enabled is true.

  10. Understand the Repositories Hierarchy

    main

    Terrateam organizes infrastructure management through a three-tier hierarchy. This allows you to manage multiple environments and logical groupings within a single repository:

    1. Repository: The top-level GitHub or GitLab repository containing your code.
    2. Directory: A logical grouping of Terraform resources within the repository. Each directory is processed independently by Terrateam.
    3. Workspace: A context within a directory (e.g., development, staging, production). Each directory can have multiple workspaces. If no workspace is explicitly specified, Terrateam uses a Default Workspace for that directory.

  11. Understand the Terrateam Architecture

    main

    Terrateam's architecture is split into two primary components that work together to orchestrate infrastructure changes:

    • Terrateam Server: The central orchestrator. It listens for GitHub and GitLab events, evaluates the event payload to determine the required Terraform operation, manages execution logic, and handles state updates.
    • Terrateam Runner: The execution engine. It receives instructions from the server, executes the actual Terraform commands (or other CLI-driven tools) within your repository environment, and reports the results back to the server.

  12. Distinguish between success and failure in webhooks

    main

    Because the hooks configuration runs after an operation without knowledge of its outcome, you must use the workflows section to implement conditional webhook triggers. Use the run_on attribute set to either success or failure to control when the run step executes.

    workflows:
  - tag_query: ""
    apply:
      - type: init
      - type: apply
      - type: run
        run_on: success
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply succeeded for directory: $TERRATEAM_DIR"}', 'https://example.com/webhook']
      - type: run
        run_on: failure
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply failed for directory: $TERRATEAM_DIR"}', 'https://example.com/webhook']