Terragrunt 官方 Docker 镜像文档

一、镜像概述和主要用途

概述

Terragrunt 官方 Docker 镜像是由 Terragrunt 官方维护的容器化分发形式，封装了 Terragrunt 工具及其运行依赖，提供开箱即用的 Terragrunt 执行环境。Terragrunt 是 Terraform 的封装工具，旨在简化多环境、多模块 Terraform 配置的管理，通过自动化后端配置、版本控制、依赖管理等功能，提升基础设施即代码（IaC）的维护效率。

主要用途

• 提供标准化的 Terragrunt 运行环境，避免本地环境配置差异；
• 支持在 CI/CD 流水线、容器化部署平台中集成 Terragrunt 命令；
• 快速启动临时环境执行 Terragrunt 任务（如 plan、apply、destroy）；
• 集中管理 Terraform 版本，确保多团队、多环境使用一致的工具链。

二、核心功能和特性

工具核心功能

1. Terraform 版本管理：自动下载、缓存并切换指定版本的 Terraform，无需手动安装；
2. 集中化配置：通过 terragrunt.hcl 集中定义通用配置（如后端、提供商），避免重复代码；
3. 依赖管理：支持模块间依赖声明，确保按依赖顺序执行 Terraform 命令；
4. 后端配置自动化：自动生成 Terraform 后端配置（如 S3、GCS），简化远程状态管理。

镜像特性

• 官方维护：由 Terragrunt 团队官方构建，确保与工具版本同步更新；
• 轻量级：基于 Alpine 或 Debian slim 基础镜像，体积小，启动快；
• 跨平台：支持 Linux/amd64、Linux/arm64 等主流架构；
• 零配置启动：无需预安装 Terraform 或 Terragrunt，拉取镜像即可运行。

三、使用场景和适用范围

典型使用场景

1. CI/CD 流水线集成：在 Jenkins、GitLab CI、GitHub Actions 等平台中执行 terragrunt plan/apply，实现基础设施自动化部署；
2. 开发环境快速初始化：开发人员无需本地安装 Terragrunt/Terraform，通过容器快速启动配置环境；
3. 多环境一致性管理：在开发、测试、生产环境中使用相同镜像，确保工具链版本一致；
4. 临时任务执行：如一次性基础设施检查、版本迁移、状态同步等临时操作。

适用范围

• DevOps 工程师、云基础设施管理员；
• 使用 Terragrunt 管理 Terraform 配置的团队；
• 需要自动化基础设施部署流程的组织；
• 追求环境一致性和标准化的技术团队。

四、使用方法和配置说明

4.1 基础使用步骤

1. 拉取镜像

从 Docker Hub 拉取官方镜像（默认使用最新版本，可指定标签如 v0.55.16 锁定版本）：

docker pull gruntwork/terragrunt:latest

2. 验证安装

运行以下命令检查 Terragrunt 版本，确认镜像正常工作：

docker run --rm gruntwork/terragrunt:latest terragrunt --version

3. 执行 Terragrunt 命令

通过挂载本地 Terragrunt 配置目录，执行具体命令（如 plan、apply）：

# 假设当前目录包含 terragrunt.hcl 及 Terraform 模块
docker run --rm -v $(pwd):/workspace -w /workspace gruntwork/terragrunt:latest terragrunt plan

4.2 高级配置

挂载配置文件

将本地 Terragrunt 配置（terragrunt.hcl）、Terraform 模块、变量文件（如 terraform.tfvars）挂载到容器内 /workspace 目录（或自定义工作目录）：

docker run --rm \
  -v $(pwd)/config:/workspace \  # 挂载配置目录
  -v $(pwd)/secrets:/secrets \    # 挂载敏感文件（如 AWS 凭证）
  -w /workspace \                 # 设置工作目录
  gruntwork/terragrunt:latest \
  terragrunt apply

传递环境变量

通过 -e 参数传递环境变量（如云服务凭证、自定义配置）：

docker run --rm \
  -v $(pwd):/workspace -w /workspace \
  -e AWS_ACCESS_KEY_ID="AKIAEXAMPLE" \
  -e AWS_SECRET_ACCESS_KEY="secret" \
  -e TERRAGRUNT_TFPATH="/usr/local/bin/terraform" \  # 指定 Terraform 路径
  gruntwork/terragrunt:latest \
  terragrunt plan

自定义 Terraform 版本

通过 TERRAGRUNT_TFPATH 环境变量指定 Terraform 版本，镜像会自动下载对应版本（需确保网络通畅）：

docker run --rm \
  -v $(pwd):/workspace -w /workspace \
  -e TERRAGRUNT_DOWNLOAD="true" \  # 允许自动下载 Terraform
  -e TERRAGRUNT_TFPATH="/usr/local/bin/terraform-1.6.0" \  # 指定版本
  gruntwork/terragrunt:latest \
  terragrunt init

持久化缓存

将 Terragrunt 缓存目录（含下载的 Terraform 二进制、模块缓存）挂载到本地，避免重复下载：

docker run --rm \
  -v $(pwd):/workspace \
  -v ~/.terragrunt-cache:/root/.terragrunt-cache \  # 持久化缓存
  gruntwork/terragrunt:latest \
  terragrunt apply

4.3 配置参数与环境变量

常用环境变量

构建参数（用于自定义镜像）

如需构建包含特定 Terraform 版本的镜像，可通过 --build-arg 指定：

docker build \
  --build-arg TERRAFORM_VERSION=1.6.0 \
  -t my-custom-terragrunt:1.6.0 \
  [***]

五、Docker 部署方案示例

5.1 docker-compose 配置示例

创建 docker-compose.yml，定义 Terragrunt 服务，适用于本地开发或固定环境：

version: '3.8'
services:
  terragrunt:
    image: gruntwork/terragrunt:latest
    volumes:
      - ./config:/workspace:ro  # 挂载只读配置目录
      - ./secrets:/secrets:ro   # 挂载敏感文件（如云凭证）
      - terragrunt-cache:/root/.terragrunt-cache  # 持久化缓存
    environment:
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - TERRAGRUNT_TFPATH=/usr/local/bin/terraform-1.6.0
    working_dir: /workspace
    command: ["terragrunt", "plan"]  # 默认执行的命令

volumes:
  terragrunt-cache:  # 命名卷，持久化缓存数据

启动服务：

docker-compose up

5.2 CI/CD 流水线示例（GitLab CI）

在 .gitlab-ci.yml 中集成 Terragrunt 镜像执行部署任务：

stages:
  - deploy

deploy-infra:
  stage: deploy
  image: gruntwork/terragrunt:latest
  before_script:
    - export AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID
    - export AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
  script:
    - cd /builds/your-project/infrastructure  # 切换到配置目录
    - terragrunt init
    - terragrunt plan
    - terragrunt apply --auto-approve
  only:
    - main  # 仅主分支触发

六、注意事项

1. 权限问题：挂载本地目录时，容器内用户（默认 root）可能对挂载文件有读写权限，生产环境建议通过 --user 参数指定非 root 用户，避免权限泄露。
2. 网络配置：执行涉及云服务的命令（如 apply）时，需确保容器网络可访问云厂商 API（如 AWS、Azure 等），无需特殊代理时可使用默认网络模式。
3. 版本锁定：生产环境强烈建议使用具体版本标签（如 v0.55.16）而非 latest，避免工具版本变更导致兼容性问题。
4. 敏感数据：避免将密钥、凭证直接写入镜像或命令行，优先通过环境变量（如 CI/CD 密钥管理）或挂载只读文件传递。

七、镜像维护与更新

• 官方镜像通过 Terragrunt GitHub 仓库 自动构建，与 Terragrunt 版本同步更新；
• 镜像标签规则：v<terragrunt-version>（如 v0.55.16），latest 指向最新稳定版；
• 安全更新和漏洞修复通过新版本镜像发布，建议定期更新镜像以获取最新特性和安全补丁。