Concepts

To effectively use Terrateam, it’s important to understand its key concepts and terminology. In the following section, we’ll explore the core components of Terrateam and how they work together to simplify your infrastructure management workflow.

Dirspace

In Terrateam, a Dirspace is a fundamental concept that defines the scope of Terraform operations. It uniquely combines a repository, a directory within that repository, and a Terraform workspace, represented as a tuple (repository, directory, workspace).

Dirspaces are discovered automatically by Terrateam whenever it detects Terraform configurations in your repository. Each directory containing Terraform files is associated with a Dirspace, using either the explicitly defined Terraform workspace or the default workspace (if no workspace is specified).

Engine

Every Dirspace in Terrateam is executed using a specific engine, the tool responsible for running the init, plan, apply, and related steps. By default, this engine is the Terraform CLI, but Terrateam also supports OpenTofu, Terragrunt, Pulumi, CDKTF, and even fully custom engines.

The engine can be defined globally for the entire repository or overridden per workflow to suit different environments or teams.

For example, you might want to use OpenTofu in development and Terraform in production:

workflows:
  - tag_query: "development"
    engine:
      name: tofu
  - tag_query: "production"
    engine:
      name: terraform

Terrateam uses this configuration to decide how to execute each Dirspace when a change is detected. If you define a custom engine, you can provide commands for each lifecycle step, giving you full control over the execution logic.

Learn more about configuring an Engine here.

Changes and File Patterns

When a pull request is opened or updated, Terrateam detects changes based on patterns defined in your .terrateam/config.yml file under the when_modified configuration. The default configuration looks like:

when_modified:
  file_patterns:
    - '**/*.tf'
    - '**/*.tfvars'

This configuration instructs Terrateam to monitor changes to any files with .tf or .tfvars extensions. Adjust these patterns in your configuration file to align with your project’s structure.

Terrateam maps detected changes to their appropriate Dirspaces. These mapped Dirspaces are referred to as Changes. When executing operations, Terrateam only considers Dirspaces with modified files in the pull request.

Auto-Plan and Auto-Apply

Terrateam provides automated Terraform execution workflows to simplify infrastructure changes:

Auto-Plan: Runs terraform plan automatically when a pull request is created or updated. Enable with:
```
when_modified:
  autoplan: true  # Set to false to disable
```
Auto-Apply: Runs terraform apply post-merge. It is disabled by default. Enable with:
```
when_modified:
  autoapply: true
```

Tags and Tag Sets

Terrateam uses Tags to organize Terraform resources through flexible labeling. Tags provide a powerful way to categorize, filter, and manage your infrastructure resources, making it easier to apply specific operations to targeted sets of resources.

Tags in Terrateam can be both user-defined and automatically assigned. They are optional but provide significant benefits for organizing and managing infrastructure resources.

There are two types of Tags:

Tag Set: An unordered and deduplicated list of labels assigned to Terraform resources.
Tag Query: A Tag Set used for matching. Every Tag in a Tag Query must exist in a Tag Set for a match to occur. Check the Tag Queries page to lean more.

Lock policy

Terrateam’s locking system prevents concurrent modifications by ensuring only one change can be applied to a resource at a time. This prevents:

State file conflicts.
Resource modification races.
Concurrent apply operations.

Key behaviors:

Enabled by default (no config needed).
Automatically released after apply + merge.
Force unlock via comment: terrateam unlock.

Customizing lock policies:

# .terrateam/config.yml (default shown)
workflows:
  lock_policy: strict  # strict|apply|merge|none

For advanced configurations see our Locks & Concurrency guide.