terragrunt

Terragrunt Docker 镜像

Terragrunt的官方Docker镜像,提供运行环境以简化Terraform配置管理,支持远程状态处理和模块重用等功能。

1 次收藏下载次数: 0状态:社区镜像维护者:gruntwork仓库类型:镜像最近更新:
下载命令
点击查看

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 锁定版本):

bash
docker pull docker.xuanyuan.run/gruntwork/terragrunt:latest

2. 验证安装

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

bash
docker 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 目录(或自定义工作目录):

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

传递环境变量

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

bash
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 版本,镜像会自动下载对应版本(需确保网络通畅):

bash
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 二进制、模块缓存)挂载到本地,避免重复下载:

bash
docker 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_DIRTerragrunt 缓存目录(存放下载的 Terraform、模块缓存等)/root/.terragrunt-cache
TERRAGRUNT_DEBUG启用调试模式(输出详细日志)false
TERRAFORM_VERSION构建镜像时指定默认 Terraform 版本(仅用于镜像构建,运行时可覆盖)最新稳定版

构建参数(用于自定义镜像)

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

bash
docker 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 服务,适用于本地开发或固定环境:

yaml
version: '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:  # 命名卷,持久化缓存数据

启动服务:

bash
docker-compose up

5.2 CI/CD 流水线示例(GitLab CI)

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

yaml
stages:
  - 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  # 仅主分支触发

六、注意事项

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

七、镜像维护与更新

  • 官方镜像通过 https://github.com/gruntwork-io/terragrunt 自动构建,与 Terragrunt 版本同步更新;
  • 镜像标签规则:v<terragrunt-version>(如 v0.55.16),latest 指向最新稳定版;
  • 安全更新和漏洞修复通过新版本镜像发布,建议定期更新镜像以获取最新特性和安全补丁。

镜像拉取方式

您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本,请访问 标签列表页面。

轩辕镜像加速拉取命令点我查看更多 terragrunt 镜像标签

docker pull docker.xuanyuan.run/gruntwork/terragrunt:<标签>

DockerHub 原生拉取命令

docker pull gruntwork/terragrunt:<标签>
专业版 · 高速稳定拉取镜像
50GB 仅 ¥8/年
高速镜像下载在线技术支持专业版保障服务可用付费会员免广告