通过 Terragrunt 管理 Terraform S3 后端的最佳实践

Terragrunt 简介

Terragrunt 是一个对 Terraform 的轻量级封装器，旨在实现配置的 DRY（Don't Repeat Yourself） 原则。它提供了对多个 Terraform 模块的统一管理能力，并简化了远程状态存储的配置与维护。

🚀 安装 Terragrunt

  1. 安装 Terraform

  2. 安装 Terragrunt

  3. 建议在 ~/.bashrc 添加以下内容，用 tg 简化 terragrunt 命令：

    # terragrunt bash 补全支持
alias tg=terragrunt
complete -C /usr/bin/terraform tg

    注：Bash 合并 Terraform 与 Terragrunt 补全较困难，Zsh 更容易实现。详见 Issue #689

  4. 使用示例（等价于 Terraform 命令）：

    terragrunt fmt
terragrunt init
terragrunt plan
terragrunt apply

👉 快速开始文档

🗂️ 使用 Terragrunt 构建 Terraform 项目结构

  1. 每个 Terraform 项目都需要一个最底层的 terragrunt.hcl 文件，供 Terragrunt 读取配置。
  2. 该文件可以通过 include 引用上层目录的配置，从而实现结构化管理和配置复用。
  3. 推荐的项目结构如下： 
    ./environments/
├── prod/
│   └── terraform/
│       ├── beijing/
│       │   ├── 1.vpc/
│       │   │   ├── main.tf
│       │   │   └── terragrunt.hcl      # 底层配置
│       └── terragrunt.hcl              # 区域/环境级别配置
├── qa/
│   └── terraform/
│       ├── global/
│       │   └── route53-acm/
│       │       ├── main.tf
│       │       └── terragrunt.hcl
│       └── terragrunt.hcl
  4. 示例底层 terragrunt.hcl 文件内容： 
    include "root" {
  path = find_in_parent_folders()
}
  5. 使用 terragrunt hclfmt 格式化 .hcl 文件（类似 terraform fmt）

📖 更多信息

☁️ 使用 Terragrunt 配置 S3 后端存储（Remote State）

  1. 在上层 terragrunt.hcl 中添加 remote_state 配置块：

    remote_state {
  backend = "s3"

  generate = {
    path      = "terraform-backend.tf"
    if_exists = "overwrite"
  }

  config = {
    profile              = "pad"
    allowed_account_ids  = ["464542629384"]
    region               = "ap-southeast-1"
    bucket               = "pad-terraform-state"
    encrypt              = true
    bucket_sse_algorithm = "AES256"
    dynamodb_table       = "terraform-state-locks"
    key                  = "pad-deploy/${get_path_from_repo_root()}/terraform.tfstate"
  }
}
    • key 的含义：
      1. coinbridge-deploy：Git 仓库名
      2. ${get_path_from_repo_root()}：当前模块相对于仓库根目录的路径
      3. terraform.tfstate：状态文件名

    更多内置函数参考：Terragrunt Built-in Functions

  2. 在模块目录中执行：

    terragrunt init

    Terragrunt 会根据配置生成 terraform-backend.tf，并将状态文件保存至 S3。

    • 若 S3 bucket 或 DynamoDB 表不存在，Terragrunt 会提示是否创建
    • 若已有本地状态文件，Terraform 会提示迁移至远程 S3

  3. .terraform/terraform.tfstate 文件仍存在本地，用于记录后端配置，判断是否需要迁移。

📖