From daf1d796a2cef8dc625bfe8bb00b51cf7df8ad7e Mon Sep 17 00:00:00 2001 From: x0rgus Date: Mon, 3 Mar 2025 17:40:43 -0300 Subject: [PATCH 1/6] :memo: Updated Getting Started / Concepts --- .../content/docs/getting-started/concepts.mdx | 75 ++++++++++++++----- 1 file changed, 57 insertions(+), 18 deletions(-) diff --git a/docs/src/content/docs/getting-started/concepts.mdx b/docs/src/content/docs/getting-started/concepts.mdx index ed5438761..ee5298c57 100644 --- a/docs/src/content/docs/getting-started/concepts.mdx +++ b/docs/src/content/docs/getting-started/concepts.mdx @@ -13,13 +13,14 @@ To effectively use Terrateam, it's important to understand its key concepts and 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. -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)` +For example, consider a repository named `repo` with two directories, `dir1` and `dir2`, and no extra workspace configuration. This repository would have two Dirspaces: -Terrateam executes its operations, such as plan and apply, within the context of a Dirspace. +1. (`repo`, `dir1`, `default`) or (`dir1`, `default`) +2. (`repo`, `dir2`, `default`) or (`dir2`, `default`) +Terrateam executes operations like plan and apply within the context of a Dirspace. ``` Repository | @@ -29,34 +30,72 @@ Repository |-- Directory 2 |-- Workspace: default ``` - ## 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' +``` -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. +This configuration tells Terrateam to monitor changes to any files with `.tf` or `.tfvars` extensions. Modify these patterns in your configuration file to match your project's structure. + +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 offers two configurable automated operations: -- **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**: (Enabled by default) Runs `terraform plan` on new or updated pull requests. Configure in `.terrateam/config.yml`: + ```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 your workflow and reduce the manual effort required to manage your infrastructure. +These automated operations streamline workflows while maintaining control through configurable thresholds. ## 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: + +- State file conflicts +- Resource modification races +- Concurrent apply operations -* **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. +**Key behaviors**: +- Enabled by default (no config needed) +- Automatically released after apply + merge +- Force unlock via comment: `terrateam unlock` +```yaml +# .terrateam/config.yml (default shown) +workflows: + lock_policy: strict # strict|apply|merge|none +``` + +For advanced configurations see our [Locks & Concurrency guide](/advanced-workflows/locks-and-concurrency). + +:::note + Default settings work for most teams. Customize only if you need specific lock timing or policies. +::: ## Tags and Tag Sets -Terrateam uses Tags to group Terraform resources in a repository and match against those labels. There are two types of Tags: +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 -* **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. +**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 provide a flexible way to organize and manage your Terraform resources within Terrateam. +Tags enable precise resource management across complex infrastructures. \ No newline at end of file From 9e5ba9aa6dc44504655a375e829a3074fb3bccc1 Mon Sep 17 00:00:00 2001 From: x0rgus Date: Tue, 4 Mar 2025 21:21:58 -0300 Subject: [PATCH 2/6] :memo: updated dirspaces explanation and added a better example --- .../content/docs/getting-started/concepts.mdx | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/src/content/docs/getting-started/concepts.mdx b/docs/src/content/docs/getting-started/concepts.mdx index ee5298c57..092f526e4 100644 --- a/docs/src/content/docs/getting-started/concepts.mdx +++ b/docs/src/content/docs/getting-started/concepts.mdx @@ -15,12 +15,16 @@ At the heart of Terrateam is the concept of a Dirspace. A Dirspace represents a 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). -For example, consider a repository named `repo` with two directories, `dir1` and `dir2`, and no extra workspace configuration. This repository would have two Dirspaces: +#### **Example:** +Consider a repository named `repo` with two directories, `dir1` and `dir2`, and no explicitly configured workspaces. This repository would have two Dirspaces: -1. (`repo`, `dir1`, `default`) or (`dir1`, `default`) -2. (`repo`, `dir2`, `default`) or (`dir2`, `default`) +| Repository | Directory | Workspace | +|------------|----------|-----------| +| repo | dir1 | default | +| repo | dir2 | default | + +A **workspace** allows you to manage multiple states for the same directory. This helps isolate environments such as `dev`, `staging`, and `prod` within the same repository, making infrastructure management more organized. -Terrateam executes operations like plan and apply within the context of a Dirspace. ``` Repository | @@ -30,6 +34,9 @@ Repository |-- Directory 2 |-- 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 based on patterns defined in your `.terrateam/config.yml` file under the `when_modified` configuration. The default configuration looks like: @@ -47,10 +54,7 @@ Terrateam maps detected changes to their appropriate [Dirspaces](/getting-starte ## Auto-Plan and Auto-Apply -Terrateam offers two configurable automated operations: - -- **Auto-Plan**: (Enabled by default) Runs `terraform plan` on new or updated pull requests. Configure in `.terrateam/config.yml`: - ```yaml +Terrateam offers two configurable automated operations:New chat auto_plan: true # Set to false to disable ``` - **Auto-Apply**: (Disabled by default) Runs `terraform apply` post-merge. Enable with: From 00f1fe12bafaca2fec5bea49d02ad5c64af7ea20 Mon Sep 17 00:00:00 2001 From: lucaspr2 Date: Mon, 10 Mar 2025 14:48:40 -0300 Subject: [PATCH 3/6] Update docs/src/content/docs/getting-started/concepts.mdx Co-authored-by: Damian Furfuro <85168963+Arcapas@users.noreply.github.com> --- docs/src/content/docs/getting-started/concepts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/getting-started/concepts.mdx b/docs/src/content/docs/getting-started/concepts.mdx index 092f526e4..1ced44fca 100644 --- a/docs/src/content/docs/getting-started/concepts.mdx +++ b/docs/src/content/docs/getting-started/concepts.mdx @@ -11,7 +11,7 @@ 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. 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). From f3bd40e2170fea6981dc5cd5e0e466264c0fb11b Mon Sep 17 00:00:00 2001 From: lucaspr2 Date: Mon, 10 Mar 2025 14:48:49 -0300 Subject: [PATCH 4/6] Update docs/src/content/docs/getting-started/concepts.mdx Co-authored-by: Damian Furfuro <85168963+Arcapas@users.noreply.github.com> --- docs/src/content/docs/getting-started/concepts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/getting-started/concepts.mdx b/docs/src/content/docs/getting-started/concepts.mdx index 1ced44fca..f03b2b99f 100644 --- a/docs/src/content/docs/getting-started/concepts.mdx +++ b/docs/src/content/docs/getting-started/concepts.mdx @@ -23,7 +23,7 @@ Consider a repository named `repo` with two directories, `dir1` and `dir2`, and | repo | dir1 | default | | repo | dir2 | default | -A **workspace** allows you to manage multiple states for the same directory. This helps isolate environments such as `dev`, `staging`, and `prod` within the same repository, making infrastructure management more organized. +A **workspace** enables you to manage multiple states for the same directory. This helps to isolate environments such as `dev`, `staging`, and `prod` within the same repository, making infrastructure management more organized. ``` Repository From 05977ff38dce54edb6e077260f5497581f3775c8 Mon Sep 17 00:00:00 2001 From: lucaspr2 Date: Mon, 10 Mar 2025 14:48:56 -0300 Subject: [PATCH 5/6] Update docs/src/content/docs/getting-started/concepts.mdx Co-authored-by: Damian Furfuro <85168963+Arcapas@users.noreply.github.com> --- docs/src/content/docs/getting-started/concepts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/getting-started/concepts.mdx b/docs/src/content/docs/getting-started/concepts.mdx index f03b2b99f..add120efe 100644 --- a/docs/src/content/docs/getting-started/concepts.mdx +++ b/docs/src/content/docs/getting-started/concepts.mdx @@ -48,7 +48,7 @@ when_modified: - '**/*.tfvars' ``` -This configuration tells Terrateam to monitor changes to any files with `.tf` or `.tfvars` extensions. Modify these patterns in your configuration file to match your project's structure. +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](/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. From 0be5f9b1bd2bd8a425bd569303ec64f7d1479c27 Mon Sep 17 00:00:00 2001 From: x0rgus Date: Mon, 10 Mar 2025 15:00:10 -0300 Subject: [PATCH 6/6] :wrench: added less abstract example on dirspaces, moved sections, added intro to auto plan --- .../content/docs/getting-started/concepts.mdx | 63 ++++++++++--------- 1 file changed, 35 insertions(+), 28 deletions(-) diff --git a/docs/src/content/docs/getting-started/concepts.mdx b/docs/src/content/docs/getting-started/concepts.mdx index add120efe..5ea8e6e43 100644 --- a/docs/src/content/docs/getting-started/concepts.mdx +++ b/docs/src/content/docs/getting-started/concepts.mdx @@ -16,23 +16,28 @@ At the core of Terrateam is the concept of a Dirspace. It represents a unique bl 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). #### **Example:** -Consider a repository named `repo` with two directories, `dir1` and `dir2`, and no explicitly configured workspaces. This repository would have two Dirspaces: -| Repository | Directory | Workspace | -|------------|----------|-----------| -| repo | dir1 | default | -| repo | dir2 | default | +Imagine you have a repository called `infra-repo` managing multiple environments: -A **workspace** enables you to manage multiple states for the same directory. This helps to isolate environments such as `dev`, `staging`, and `prod` within the same repository, making infrastructure management more organized. +| 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 + | + |-- dev/ + | |-- Workspace: default | - |-- Directory 1 - | |-- Workspace: default + |-- staging/ + | |-- Workspace: default | - |-- Directory 2 - |-- Workspace: default + |-- prod/ + |-- Workspace: default ``` :::note Terrateam executes operations like plan and apply within the context of a Dirspace. @@ -54,16 +59,33 @@ Terrateam maps detected changes to their appropriate [Dirspaces](/getting-starte ## Auto-Plan and Auto-Apply -Terrateam offers two configurable automated operations:New chat +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: + ```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. +## 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's locking system prevents concurrent modifications by ensuring only one change can be applied to a resource at a time. This prevents: @@ -88,18 +110,3 @@ For advanced configurations see our [Locks & Concurrency guide](/advanced-workfl :::note Default settings work for most teams. Customize only if you need specific lock timing or policies. ::: -## 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. \ No newline at end of file