minamijoyo/tfupdate

tfupdate

镜像概述与主要用途

tfupdate 是一款专为 Terraform 配置文件设计的版本更新工具，旨在帮助用户批量更新 Terraform 核心、提供者（Provider）及模块（Module）的版本约束。它能够递归解析多个目录下的配置文件，自动从 GitHub、GitLab 或 Terraform Registry 获取最新版本信息，并支持 Terraform v0.12+。通过与 CI 或任务调度工具集成，可实现每日检查最新版本并自动创建 Pull Request，有效解决多目录 Terraform 配置版本管理的复杂性。

核心功能与特性

• 批量版本更新：支持同时更新 Terraform 核心、提供者和模块的版本约束
• 递归目录处理：可递归遍历指定目录下的所有 Terraform 配置文件
• 多源版本获取：从 GitHub、GitLab 或 Terraform Registry 自动获取最新版本
• 版本锁定支持：帮助维持版本锁定最佳实践，减少升级风险
• 兼容性：全面支持 Terraform v0.12+ 配置文件格式
• 灵活忽略机制：支持通过正则表达式忽略特定路径

为什么使用 tfupdate？

最佳实践建议将 Terraform 配置和状态拆分为多个小模块，以最小化意外影响，同时锁定核心、提供者和模块版本以避免意外的破坏性变更。然而，当版本约束分散在多个目录时，手动更新变得繁琐。tfupdate 解决了这一痛点，能够解析 Terraform 配置并一次性更新所有版本约束，确保版本保持最新，降低升级失败风险。

Docker 安装与使用

基本使用

通过 Docker 运行 tfupdate 无需本地安装，直接执行以下命令验证版本：

bash
$ docker run -it --rm minamijoyo/tfupdate --version

挂载配置文件

如需更新本地 Terraform 配置文件，需将本地目录挂载到容器中。例如，更新当前目录下的配置：

bash
$ docker run -it --rm -v $(pwd):/workspace minamijoyo/tfupdate terraform -r /workspace

详细使用方法

命令概览

bash
tfupdate --help
Usage: tfupdate [--version] [--help] <command> [<args>]

可用命令:
    module       更新模块的版本约束
    provider     更新提供者的版本约束
    release      获取版本发布信息
    terraform    更新 Terraform 核心版本约束

terraform 命令

用于更新 Terraform 核心版本约束（required_version）。

bash
$ tfupdate terraform --help
Usage: tfupdate terraform [options] <PATH>

参数:
  PATH               待更新的文件或目录路径

选项:
  -v  --version      新版本约束（默认：latest，自动获取最新版本）
  -r  --recursive    递归检查目录（默认：false）
  -i  --ignore-path  忽略路径的正则表达式（可多次指定以忽略多个目录）

示例：

更新单个文件至指定版本：

bash
$ docker run -it --rm -v $(pwd):/workspace minamijoyo/tfupdate terraform -v 0.12.16 /workspace/main.tf

递归更新目录下所有配置至最新版本：

bash
$ docker run -it --rm -v $(pwd):/workspace minamijoyo/tfupdate terraform -r /workspace

递归更新时忽略 modules/ 目录：

bash
$ docker run -it --rm -v $(pwd):/workspace minamijoyo/tfupdate terraform -r -i "modules/" /workspace

provider 命令

用于更新 Terraform 提供者的版本约束（如 AWS、Google 等）。

bash
$ tfupdate provider --help
Usage: tfupdate provider [options] <PROVIDER_NAME> <PATH>

参数:
  PROVIDER_NAME      提供者名称（如 aws、google、azurerm）
  PATH               待更新的文件或目录路径

选项:
  -v  --version      新版本约束（默认：latest，官方提供者支持自动获取最新版本）
  -r  --recursive    递归检查目录（默认：false）
  -i  --ignore-path  忽略路径的正则表达式（可多次指定）

示例：

更新 AWS 提供者至 2.40.0 版本：

bash
$ docker run -it --rm -v $(pwd):/workspace minamijoyo/tfupdate provider aws -v 2.40.0 /workspace/main.tf

module 命令

用于更新 Terraform 模块的版本约束。

bash
$ tfupdate module --help
Usage: tfupdate module [options] <MODULE_NAME> <PATH>

参数:
  MODULE_NAME        模块名称（如 terraform-aws-modules/vpc/aws 或 git::https://example.com/vpc.git）
  PATH               待更新的文件或目录路径

选项:
  -v  --version      新版本约束（必填，当前不支持自动获取模块最新版本）
  -r  --recursive    递归检查目录（默认：false）
  -i  --ignore-path  忽略路径的正则表达式（可多次指定）

示例：

更新 vpc 模块至 2.21.0 版本：

bash
$ docker run -it --rm -v $(pwd):/workspace minamijoyo/tfupdate module -v 2.21.0 terraform-aws-modules/vpc/aws /workspace/main.tf

release 命令

用于获取版本发布信息，支持 latest（获取最新版本）和 list（获取版本列表）子命令。

release latest

获取指定源的最新版本：

bash
$ tfupdate release latest --help
Usage: tfupdate release latest [options] <SOURCE>

参数:
  SOURCE             版本数据源路径，格式取决于 --source-type：
                     - github/gitlab: owner/repo（如 terraform-providers/terraform-provider-aws）
                     - tfregistryModule: namespace/name/provider（如 terraform-aws-modules/vpc/aws）
                     - tfregistryProvider (实验性): namespace/type（如 hashicorp/aws）

选项:
  -s  --source-type  数据源类型，可选值：github（默认）、gitlab、tfregistryModule、tfregistryProvider（实验性）

示例：

获取 AWS 提供者的最新版本：

bash
$ docker run -it --rm minamijoyo/tfupdate release latest terraform-providers/terraform-provider-aws
2.40.0

访问私有 GitHub/GitLab 仓库时，需设置环境变量：

bash
# GitHub 私有仓库
$ docker run -it --rm -e GITHUB_TOKEN=your_token minamijoyo/tfupdate release latest owner/private-repo

# GitLab 私有仓库
$ docker run -it --rm -e GITLAB_TOKEN=your_token -e GITLAB_BASE_URL=https://your-gitlab.com/api/v4/ minamijoyo/tfupdate release latest owner/private-repo -s gitlab

release list

获取指定源的版本列表：

bash
$ tfupdate release list --help
Usage: tfupdate release list [options] <SOURCE>

参数:
  SOURCE             版本数据源路径（格式同 latest 子命令）

选项:
  -s  --source-type  数据源类型（同 latest 子命令）
  -n  --max-length   版本列表最大长度

示例：

获取 Terraform 核心的最新 5 个版本：

bash
$ docker run -it --rm minamijoyo/tfupdate release list -n 5 hashicorp/terraform
0.12.17
0.12.18
0.12.19
0.12.20
0.12.21

与 CI 集成

将 tfupdate 与 CI 或任务调度工具集成，可实现每日检查最新版本并自动创建 Pull Request。示例配置和 CircleCI Orb 可参考：

• https://github.com/minamijoyo/tfupdate-circleci-example
• https://github.com/masutaka/circleci-tfupdate-orb

许可证

MIT 许可证