diff --git a/docs/src/content/docs/getting-started/concepts.mdx b/docs/src/content/docs/getting-started/concepts.mdx index ed5438761..5ea8e6e43 100644 --- a/docs/src/content/docs/getting-started/concepts.mdx +++ b/docs/src/content/docs/getting-started/concepts.mdx @@ -11,52 +11,102 @@ To effectively use Terrateam, it's important to understand its key concepts and ## Dirspace -At the heart of Terrateam is the concept of a Dirspace. A Dirspace represents a unique combination of a repository, a directory, and a workspace. It is denoted as a tuple `(repository, directory, workspace)` or simply `(directory, workspace)` when the repository is implied. +At the core of Terrateam is the concept of a Dirspace. It represents a unique blend of a repository, directory, and workspace. It is referred to as a tuple `(repository, directory, workspace)` or simply `(directory, workspace)` when the repository is implied. -For example, consider a repository named `repo` with two directories, `dir1` and `dir2`, and no extra configuration for workspaces. This repository would have two Dirspaces: +Dirspaces are automatically created when Terrateam detects Terraform configurations in your repository. Each directory containing Terraform files forms a Dirspace with either its explicitly configured workspace or the **default workspace** (created automatically when no specific workspace is defined). -1. `(repo, dir1, default)` or `(dir1, default)` -2. `(repo, dir2, default)` or `(dir2, default)` +#### **Example:** -Terrateam executes its operations, such as plan and apply, within the context of a Dirspace. +Imagine you have a repository called `infra-repo` managing multiple environments: + +| Repository | Directory | Workspace | +| ---------- | --------- | --------- | +| infra-repo | dev | default | +| infra-repo | staging | default | +| infra-repo | prod | default | + +A **workspace** enables you to manage multiple states for the same directory, isolating environments like `dev`, `staging`, and `prod` within the same repository. ``` -Repository +Repository: infra-repo | - |-- Directory 1 - | |-- Workspace: default + |-- dev/ + | |-- Workspace: default | - |-- Directory 2 - |-- Workspace: default + |-- staging/ + | |-- Workspace: default + | + |-- prod/ + |-- Workspace: default ``` - +:::note +Terrateam executes operations like plan and apply within the context of a Dirspace. +::: ## Changes and File Patterns -When a pull request is opened or updated, Terrateam detects changes in the repository based on the `file_patterns` specified in the [`when_modified`](/configuration-reference/when-modified) configuration. By default, the `file_patterns` are set to `['**/*.tf', '**/*.tfvars']`, which means Terrateam will consider changes to any files with `.tf` or `.tfvars` extensions. +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: + +```yaml +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 the detected changes to their appropriate [Dirspaces](/getting-started/concepts#dirspace). These mapped Dirspaces are referred to as Changes. When Terrateam executes a Plan or Apply operation on the changes in a pull request, it only considers the Dirspaces that have files modified in the pull request. +Terrateam maps detected changes to their appropriate [Dirspaces](/getting-started/concepts#dirspace). 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 offers two automated operations: +Terrateam provides automated Terraform execution workflows to simplify infrastructure changes: -- **Auto-Plan**: Automatically runs a Plan on a new pull request or an update to an existing one. This allows you to see the proposed changes to your infrastructure before merging the pull request. -- **Auto-Apply**: Automatically runs an Apply after merging a pull request. This ensures that the approved changes are applied to your infrastructure immediately after the merge. +- **Auto-Plan**: Runs `terraform plan` automatically when a pull request is created or updated. Enable with: + ```yaml + auto_plan: true # Set to false to disable + ``` +- **Auto-Apply**: (Disabled by default) Runs `terraform apply` post-merge. Enable with: + ```yaml + auto_apply: true + ``` +These automated operations streamline workflows while maintaining control through configurable thresholds. -These automated operations streamline your workflow and reduce the manual effort required to manage your infrastructure. +## Tags and Tag Sets + +Terrateam uses Tags to organize Terraform resources through flexible labeling: + +* **Tag Set**: Unordered, unique labels assigned to resources + Example: `env:prod, component:network` +* **Tag Query**: Filter to match specific Tag Sets + Example: `env:prod` matches all production resources +**Example workflow:** +1. Tag EC2 instances with `resource-type:compute` +2. Create Auto-Scaling Groups with `resource-type:compute, environment:production` +3. Query with `resource-type:compute` to manage all compute resources + +Tags enable precise resource management across complex infrastructures. ## Locks and Unlocks -Terrateam Locks make sure that only a single change to a resource can be applied in a pull request at any given time. This prevents conflicts and maintains consistency in your infrastructure. +Terrateam's locking system prevents concurrent modifications by ensuring only one change can be applied to a resource at a time. This prevents: -* **Lock**: A guarantee that only a single change to a resource can be applied in a pull request at any given time. -* **Unlock**: The process of releasing a lock, allowing other changes to be applied. +- State file conflicts +- Resource modification races +- Concurrent apply operations -## Tags and Tag Sets +**Key behaviors**: +- Enabled by default (no config needed) +- Automatically released after apply + merge +- Force unlock via comment: `terrateam unlock` -Terrateam uses Tags to group Terraform resources in a repository and match against those labels. There are two types of Tags: +```yaml +# .terrateam/config.yml (default shown) +workflows: + lock_policy: strict # strict|apply|merge|none +``` -* **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. +For advanced configurations see our [Locks & Concurrency guide](/advanced-workflows/locks-and-concurrency). -Tags provide a flexible way to organize and manage your Terraform resources within Terrateam. +:::note + Default settings work for most teams. Customize only if you need specific lock timing or policies. +:::