Supporting Files accountregionenvcommonhcl

Supporting files make Terragrunt repositories more maintainable by centralizing account-, region-, environment-, and global-level configuration. In a Terragrunt-driven workflow these files typically expose locals that multiple terragrunt.hcl modules can read with read_terragrunt_config and find_in_parent_folders, avoiding duplication and making updates predictable across many modules. A quick summary of each file’s role:

account.hcl: account-specific values (for example account name or account ID).
region.hcl: region-specific values (for example region name or geolocation).
env.hcl: environment-specific values (project name, environment tags, etc.).
common.hcl: global, cross-cutting configuration (global tags, company name, resource prefixes).

A slide showing four supporting .hcl configuration files — account.hcl, region.hcl, env.hcl, and common.hcl — each depicted as a colored circular icon within a card. Below each card are short descriptions of their contents (name/account ID, region/geolocation, project tags, and global tags/resource prefixes).

Why HCL (and when to use YAML)

HCL is native to Terraform/Terragrunt and works directly with read_terragrunt_config. If your toolchain prefers YAML you can store configuration in YAML, but Terragrunt does not parse YAML automatically — you must read the file with file() and convert it with yamldecode() in your terragrunt.hcl. When possible prefer HCL to reduce boilerplate and keep configs consistent with Terraform usage.

Where to place these supporting files

Place each supporting file at a level in your repo where child terragrunt.hcl files can discover them using find_in_parent_folders (commonly in the repository root or an environments/ directory).
Use consistent filenames and key names so find_in_parent_folders("account.hcl") works reliably from modules and environments.
Keep secrets out of these files. Use a secrets manager (e.g., Vault, AWS Secrets Manager) and reference secrets at runtime.

Use supporting files to centralize and reuse non-secret configuration. Store secrets in a secure secrets manager and reference them at runtime rather than putting them in these files.

Example supporting files (concise HCL patterns)

Store each of the following examples as account.hcl, region.hcl, env.hcl, and common.hcl so terragrunt.hcl can read them.

account.hcl

locals {
  account = {
    name = "production"
    id   = "123456789012"
  }
}

region.hcl

locals {
  region = {
    name = "us-east-1"
    geo  = "us-east"
  }
}

env.hcl

locals {
  env = {
    name    = "prod"
    project = "my-app"
    tags = {
      Environment = "prod"
      Project     = "my-app"
    }
  }
}

common.hcl

locals {
  common = {
    company     = "AcmeCorp"
    global_tags = {
      Company   = "AcmeCorp"
      ManagedBy = "Terragrunt"
    }
    prefix = "acme"
  }
}

How a Terragrunt config consumes supporting files

Read supporting files with read_terragrunt_config(find_in_parent_folders(...)) and merge the values into inputs for Terraform modules. The example below shows a typical terragrunt.hcl that collects all four supporting files and merges tags and core inputs.

terragrunt.hcl

locals {
  account = read_terragrunt_config(find_in_parent_folders("account.hcl")).locals.account
  region  = read_terragrunt_config(find_in_parent_folders("region.hcl")).locals.region
  env     = read_terragrunt_config(find_in_parent_folders("env.hcl")).locals.env
  common  = read_terragrunt_config(find_in_parent_folders("common.hcl")).locals.common
}

inputs = merge(
  local.common.global_tags,
  {
    account_id = local.account.id
    region     = local.region.name
    project    = local.env.project
  }
)

Quick reference table

File	Use case	Example snippet
`account.hcl`	Account-specific identifiers and metadata	`locals { account = { name = "production", id = "123456789012" } }`
`region.hcl`	Region and geolocation details	`locals { region = { name = "us-east-1", geo = "us-east" } }`
`env.hcl`	Environment/project-specific tags and names	`locals { env = { name = "prod", project = "my-app", tags = { Environment = "prod" } } }`
`common.hcl`	Cross-cutting/global settings and tags	`locals { common = { company = "AcmeCorp", prefix = "acme" } }`

Best practices and tips

Keep supporting files small and focused: one responsibility per file (account, region, env, common).
Use predictable keys (e.g., local.account, local.region, local.env, local.common) so consumption is straightforward.
Avoid hardcoding credentials or secrets — use a secrets manager. Reference secrets at runtime using Terragrunt’s built-in integrations or external data sources.
Document each supporting file at the repository root so teams know what to edit and where.
If you need YAML for other tools, store it alongside the HCL files but ensure your terragrunt.hcl explicitly parses YAML with file() + yamldecode().

Never commit plaintext secrets or credentials into supporting files. Use a dedicated secrets manager (Vault, AWS Secrets Manager, etc.) and read secrets securely at deployment time.

Links and references

By organizing account-, region-, env-, and common-level configuration into dedicated supporting files you reduce duplicate configuration, simplify updates across modules, and improve the maintainability and consistency of your Terragrunt/Terraform repo.

Introduction

Terragrunt - Good to Know Concepts & Ideas

Terragrunt Configuration

Terragrunt Commands

Terragrunt Functions

Terragrunt Blocks

Terragrunt Attributes

Managing Remote State with Terragrunt

Terragrunt Modules

Building our first AWS Demo with Terragrunt

Conclusion

Terragrunt - Basic Concepts

Supporting Files accountregionenvcommonhcl

Watch Video