DOCSEARCHbyAlgolia
Submit Docs

Terragrunt Documentation

repository·main·Indexed 27 days ago

https://github.com/gruntwork-io/terragrunt

Terragrunt is an orchestration tool for OpenTofu and Terraform designed to scale Infrastructure as Code. It provides advanced configuration and management capabilities, including the ability to manage module inputs via inputs blocks, define dependencies between units using dependency blocks, and execute commands across stacks using a Directed Acyclic Graph (DAG). Key features include remote state backend configuration, file injection via generate blocks, and an Auto-init feature for streamlined project initialization.

Tokens
175.1K
Snippets
489
Records
1.1K
Agent score
95%

What's inside Terragrunt

  1. Overview of vendored Starlight components

    main

    This directory contains components vendored from @astrojs/starlight version 0.35.2. They are used to provide custom file tree icons for Terragrunt and OpenTofu without patching the main dependency.

    File Tree Components:

    • FileTree.astro: Main component for rendering trees.
    • rehype-file-tree.ts: Rehype plugin for processing markup.
    • file-tree-icons.ts: Icon definitions and mappings.

    Card Components:

    • Card.astro: Content display with optional icons.
    • Icon.astro: Renders SVG icons.

    Icon Registry:

    • Icons.ts: Registry and SVG path definitions.

  2. Overview of the Terragrunt Catalog ecosystem

    main

    The Terragrunt catalog ecosystem provides two tools for managing OpenTofu/Terraform modules:

    • Catalog TUI: A terminal user interface for browsing and searching your module catalog. You can launch the scaffolding process directly from the TUI by pressing S on a selected module.
    • Scaffold: A command used to generate terragrunt.hcl files from module templates.

    Security Warning: Do not use catalog/scaffold to scaffold untrusted templates. IaC configurations can run arbitrary code on your system; only use templates that have been reviewed and approved.

  3. Overview of Terragrunt

    main
    Terragrunt is a flexible orchestration tool designed to help Infrastructure as Code (IaC) written in OpenTofu or Terraform scale. It provides a way to manage complex infrastructure deployments more efficiently by providing orchestration capabilities on top of these tools.

  4. Overview of Terragrunt Scale

    main

    Terragrunt Scale is a GitOps platform designed to extend Terragrunt with production-grade infrastructure automation. It operates entirely within your existing CI/CD environment (GitHub Actions or GitLab CI), ensuring you maintain full control without 'black box' processes. It never has direct access to your cloud accounts or state files; instead, it uses OIDC handshakes to acquire temporary, least-privilege credentials for each environment.

    Core Products:

    • Pipelines: CI/CD for Terragrunt featuring plan on PR/MR, apply on merge, blast radius minimization, and OIDC authentication.
    • Drift Detection: Scheduled scans that compare deployed infrastructure against Terragrunt code and automatically open pull requests to remediate drift.
    • Patcher: Automated dependency updates that open PR/MRs when new versions of OpenTofu/Terraform modules or Terragrunt units/stacks are available, including handling of breaking changes.

  5. Overview of Terragrunt Scale Patcher

    main
    Patcher is a dependency management component of Terragrunt Scale designed to automate infrastructure module updates. It scans repositories for Terragrunt module, unit, or stack references and manages version pins. When new versions are released, Patcher opens Pull Requests (PRs) with updated versions. For breaking changes, it can automatically apply code transformations (patches) or generate documentation for required manual interventions.

  6. Overview of Terragrunt Pipelines

    main

    Pipelines is the CI/CD component of Terragrunt Scale designed to automate terragrunt plan and terragrunt apply within pull request workflows. It leverages Terragrunt's dependency graph (DAG) to minimize blast radius by only executing operations on affected units.

    Execution occurs within your own CI/CD runners (such as GitHub Actions or GitLab CI), ensuring that Pipelines does not require direct access to your cloud accounts.

  7. How Git sources are resolved and cached in CAS

    main

    Terragrunt identifies Git sources using a remote URL and a ref (branch, tag, or commit).

    1. Resolution: Terragrunt uses git ls-remote to resolve the ref to a specific commit hash. This hash serves as the cache key.
    2. Deduplication: Because the commit hash is content-addressed, identical objects (blobs and trees) are shared across different repositories and refs. Both SHA-1 and SHA-256 are supported.
    3. Offline Mode: If you pin to a specific commit SHA that is already in the local store, Terragrunt skips the ls-remote network call entirely, allowing for offline resolution.
    4. Cache Hits: On a hit, Terragrunt hard links the blobs from the store into your target directory without fetching from the remote.

  8. Evaluate Trade-offs of Modular IaC Refactoring

    main

    Refactoring from a flat configuration to a modular structure (using catalog and live directories) involves specific trade-offs:

    Pros

    • Abstraction by encapsulation: Modules encapsulate subsets of infrastructure with explicit interfaces via variables and outputs.
    • More code reusability: Modules can be reused across different environments in live or within other catalog modules.

    Cons

    • Increased complexity: Introduces a layer of indirection. Consumers must trust or vet the module implementation.
    • State Adjustment: Requires state manipulation or the use of moved blocks to migrate existing resources to the new pattern without recreation.

  9. Understand the trade-offs of granular state segmentation

    main

    Moving from a 'one state file per environment' model to a 'one state file per component, per environment' model introduces several architectural trade-offs:

    Pros

    • Safety and Granular Blast Radius: Changes to stateless resources (e.g., Lambda) cannot impact stateful resources (e.g., DynamoDB or S3).
    • Reduced Lock Contention: State locks are per-component, allowing concurrent apply operations on different components.
    • Faster Feedback Loops: terragrunt plan runs faster because OpenTofu only refreshes the state for the specific component directory.

    Cons

    • Increased Configuration Complexity: Requires managing more directories and terragrunt.hcl files.
    • Explicit Dependency Management: Requires using dependency blocks to define relationships between components.
    • Mocking Outputs: When planning components that depend on unapplied infrastructure, you must use mock_outputs to prevent plan failures.

  10. Understand Terragrunt Scale Drift Detection

    main

    Drift Detection is an infrastructure reconciliation component of Terragrunt Scale. It identifies discrepancies between your deployed infrastructure and your Terragrunt code by running terragrunt plan on a configurable schedule.

    When drift is detected (i.e., the plan shows non-zero changes), the system automatically opens a pull request (PR/MR) on a drift-detection branch. This PR contains details about the drift and proposes remediation. Merging the PR triggers a terragrunt apply to bring the infrastructure back in line with the code.

  11. Verify Terragrunt project layout

    main

    A successful migration from Terralith to Terragrunt should result in a directory structure where environment-specific directories (like dev or prod) contain a terragrunt.hcl file and a moved.tf file (if refactoring state), all referencing a central root.hcl at the root of the live directory.

    Example layout:

    - live
  - dev
    - moved.tf
    - terragrunt.hcl
  - prod
    - moved.tf
    - terragrunt.hcl
  - root.hcl

  12. Understand Terragrunt terminology

    main
    Terragrunt uses specific terminology to describe Infrastructure as Code (IaC) concepts. While it attempts to align with industry standards, some terms may have specialized meanings within Terragrunt or Gruntwork products. Use the terminology guide to ensure clear communication when configuring modules, managing state, or defining infrastructure components.