Terragrunt的官方Docker镜像,提供运行环境以简化Terraform配置管理,支持远程状态处理和模块重用等功能。
Terragrunt 官方 Docker 镜像文档
一、镜像概述和主要用途
概述
Terragrunt 官方 Docker 镜像是由 Terragrunt 官方维护的容器化分发形式,封装了 Terragrunt 工具及其运行依赖,提供开箱即用的 Terragrunt 执行环境。Terragrunt 是 Terraform 的封装工具,旨在简化多环境、多模块 Terraform 配置的管理,通过自动化后端配置、版本控制、依赖管理等功能,提升基础设施即代码(IaC)的维护效率。
主要用途
- 提供标准化的 Terragrunt 运行环境,避免本地环境配置差异;
- 支持在 CI/CD 流水线、容器化部署平台中集成 Terragrunt 命令;
- 快速启动临时环境执行 Terragrunt 任务(如
plan、apply、destroy); - 集中管理 Terraform 版本,确保多团队、多环境使用一致的工具链。
二、核心功能和特性
工具核心功能
- Terraform 版本管理:自动下载、缓存并切换指定版本的 Terraform,无需手动安装;
- 集中化配置:通过
terragrunt.hcl集中定义通用配置(如后端、提供商),避免重复代码; - 依赖管理:支持模块间依赖声明,确保按依赖顺序执行 Terraform 命令;
- 后端配置自动化:自动生成 Terraform 后端配置(如 S3、GCS),简化远程状态管理。
镜像特性
- 官方维护:由 Terragrunt 团队官方构建,确保与工具版本同步更新;
- 轻量级:基于 Alpine 或 Debian slim 基础镜像,体积小,启动快;
- 跨平台:支持 Linux/amd64、Linux/arm64 等主流架构;
- 零配置启动:无需预安装 Terraform 或 Terragrunt,拉取镜像即可运行。
三、使用场景和适用范围
典型使用场景
- CI/CD 流水线集成:在 Jenkins、GitLab CI、GitHub Actions 等平台中执行
terragrunt plan/apply,实现基础设施自动化部署; - 开发环境快速初始化:开发人员无需本地安装 Terragrunt/Terraform,通过容器快速启动配置环境;
- 多环境一致性管理:在开发、测试、生产环境中使用相同镜像,确保工具链版本一致;
- 临时任务执行:如一次性基础设施检查、版本迁移、状态同步等临时操作。
适用范围
- DevOps 工程师、云基础设施管理员;
- 使用 Terragrunt 管理 Terraform 配置的团队;
- 需要自动化基础设施部署流程的组织;
- 追求环境一致性和标准化的技术团队。
四、使用方法和配置说明
4.1 基础使用步骤
1. 拉取镜像
从 Docker Hub 拉取官方镜像(默认使用最新版本,可指定标签如 v0.55.16 锁定版本):
bashdocker pull docker.xuanyuan.run/gruntwork/terragrunt:latest
2. 验证安装
运行以下命令检查 Terragrunt 版本,确认镜像正常工作:
bashdocker run --rm docker.xuanyuan.run/gruntwork/terragrunt:latest terragrunt --version
3. 执行 Terragrunt 命令
通过挂载本地 Terragrunt 配置目录,执行具体命令(如 plan、apply):
bash# 假设当前目录包含 terragrunt.hcl 及 Terraform 模块 docker run --rm -v $(pwd):/workspace -w /workspace docker.xuanyuan.run/gruntwork/terragrunt:latest terragrunt plan
4.2 高级配置
挂载配置文件
将本地 Terragrunt 配置(terragrunt.hcl)、Terraform 模块、变量文件(如 terraform.tfvars)挂载到容器内 /workspace 目录(或自定义工作目录):
bashdocker run --rm \ -v $(pwd)/config:/workspace \ # 挂载配置目录 -v $(pwd)/secrets:/secrets \ # 挂载敏感文件(如 AWS 凭证) -w /workspace \ # 设置工作目录 gruntwork/terragrunt:latest \ terragrunt apply
传递环境变量
通过 -e 参数传递环境变量(如云服务凭证、自定义配置):
bashdocker 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 版本,镜像会自动下载对应版本(需确保网络通畅):
bashdocker 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 二进制、模块缓存)挂载到本地,避免重复下载:
bashdocker run --rm \ -v $(pwd):/workspace \ -v ~/.terragrunt-cache:/root/.terragrunt-cache \ # 持久化缓存 gruntwork/terragrunt:latest \ terragrunt apply
4.3 配置参数与环境变量
常用环境变量
| 变量名 | 说明 | 默认值 |
|---|---|---|
TERRAGRUNT_TFPATH | 指定 Terraform 可执行文件路径(用于自定义版本或路径) | /usr/local/bin/terraform |
TERRAGRUNT_DOWNLOAD | 是否自动下载 Terraform(true/false) | true |
TERRAGRUNT_CACHE_DIR | Terragrunt 缓存目录(存放下载的 Terraform、模块缓存等) | /root/.terragrunt-cache |
TERRAGRUNT_DEBUG | 启用调试模式(输出详细日志) | false |
TERRAFORM_VERSION | 构建镜像时指定默认 Terraform 版本(仅用于镜像构建,运行时可覆盖) | 最新稳定版 |
构建参数(用于自定义镜像)
如需构建包含特定 Terraform 版本的镜像,可通过 --build-arg 指定:
bashdocker build \ --build-arg TERRAFORM_VERSION=1.6.0 \ -t my-custom-terragrunt:1.6.0 \ https://github.com/gruntwork-io/terragrunt.git#:docker
五、Docker 部署方案示例
5.1 docker-compose 配置示例
创建 docker-compose.yml,定义 Terragrunt 服务,适用于本地开发或固定环境:
yamlversion: '3.8' services: terragrunt: image: docker.xuanyuan.run/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: # 命名卷,持久化缓存数据
启动服务:
bashdocker-compose up
5.2 CI/CD 流水线示例(GitLab CI)
在 .gitlab-ci.yml 中集成 Terragrunt 镜像执行部署任务:
yamlstages: - deploy deploy-infra: stage: deploy image: docker.xuanyuan.run/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 # 仅主分支触发
六、注意事项
- 权限问题:挂载本地目录时,容器内用户(默认
root)可能对挂载文件有读写权限,生产环境建议通过--user参数指定非 root 用户,避免权限泄露。 - 网络配置:执行涉及云服务的命令(如
apply)时,需确保容器网络可访问云厂商 API(如 AWS、Azure 等),无需特殊代理时可使用默认网络模式。 - 版本锁定:生产环境强烈建议使用具体版本标签(如
v0.55.16)而非latest,避免工具版本变更导致兼容性问题。 - 敏感数据:避免将密钥、凭证直接写入镜像或命令行,优先通过环境变量(如 CI/CD 密钥管理)或挂载只读文件传递。
七、镜像维护与更新
- 官方镜像通过 https://github.com/gruntwork-io/terragrunt 自动构建,与 Terragrunt 版本同步更新;
- 镜像标签规则:
v<terragrunt-version>(如v0.55.16),latest指向最新稳定版; - 安全更新和漏洞修复通过新版本镜像发布,建议定期更新镜像以获取最新特性和安全补丁。
镜像拉取方式
您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本,请访问 标签列表页面。
轩辕镜像加速拉取命令点我查看更多 terragrunt 镜像标签
DockerHub 原生拉取命令
用户好评
来自真实用户的反馈,见证轩辕镜像的优质服务