terraform-cli-setup

Category: setup

Terraform CLI 安装与初始化

目标

• 检测本地是否已安装 terraform，未安装则自动安装
• 确保 terraform version 正常输出
• 引导完成 terraform init 初始化工作区
• 处理 Provider 下载、镜像配置等基础环境问题

> 关于 Provider 凭证配置：各云厂商的凭证配置（AWS/Azure/GCP/阿里云等）不在本技能范围内。Provider 凭证在实际使用 Terraform 时按需配置，请参考 terraform-skill 中的 Provider 凭证配置引导。

何时触发此技能

• 用户首次使用 Terraform 相关功能
• 执行 terraform 命令报错 command not found
• terraform init 报 Provider 下载失败（网络/镜像问题）
• 用户主动要求安装或重新安装 Terraform
• 其他 Terraform 技能（terraform-skill）的前置依赖检查

完整流程

第 1 步：检测安装状态

which terraform 2>/dev/null || echo "NOT_INSTALLED"

如果未安装，进入安装流程。如果已安装，跳到第 3 步。

第 2 步：安装 Terraform

macOS (Homebrew — 推荐)

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

macOS (手动下载)

ARCH=$(uname -m)
case "$ARCH" in
    x86_64|amd64) ARCH="amd64" ;;
    arm64|aarch64) ARCH="arm64" ;;
esac
curl -fsSL "https://releases.hashicorp.com/terraform/1.14.6/terraform_1.14.6_darwin_${ARCH}.zip" -o /tmp/terraform.zip
mkdir -p ~/.local/bin
unzip -o /tmp/terraform.zip -d ~/.local/bin/
chmod +x ~/.local/bin/terraform
export PATH="$HOME/.local/bin:$PATH"

Linux (手动下载)

ARCH=$(uname -m)
case "$ARCH" in
    x86_64|amd64) ARCH="amd64" ;;
    arm64|aarch64) ARCH="arm64" ;;
esac
curl -fsSL "https://releases.hashicorp.com/terraform/1.14.6/terraform_1.14.6_linux_${ARCH}.zip" -o /tmp/terraform.zip
mkdir -p ~/.local/bin
unzip -o /tmp/terraform.zip -d ~/.local/bin/
chmod +x ~/.local/bin/terraform
export PATH="$HOME/.local/bin:$PATH"

Linux (APT — Debian/Ubuntu)

sudo apt-get update && sudo apt-get install -y gnupg software-properties-common
wget -O- https://apt.releases.hashicorp.com/gpg | \
  gpg --dearmor | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \
  https://apt.releases.hashicorp.com $(lsb_release -cs) main" | \
  sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt-get update && sudo apt-get install terraform

Linux (YUM — RHEL/CentOS/Fedora)

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo yum -y install terraform

安装后验证：

terraform version

第 3 步：初始化 Terraform 工作区

在有 .tf 文件的目录中执行：

terraform init

terraform init 会执行：

1. 初始化 Backend — 配置状态存储（默认为本地）
2. 安装 Provider 插件 — 下载 .tf 中声明的 Provider
3. 下载模块 — 获取引用的远程模块
4. 创建锁文件 — 生成 .terraform.lock.hcl 锁定版本

常见 init 选项：

# 升级 Provider 和模块到约束范围内的最新版本
terraform init -upgrade

# 重新配置 Backend
terraform init -reconfigure

# 迁移 State 到新 Backend
terraform init -migrate-state

第 4 步：验证安装与初始化

# 检查版本
terraform version

# 检查配置文件语法（需要先 init）
terraform validate

# 格式化代码
terraform fmt -check

验证结果判断：

| 输出 | 含义 | 处理方式 |

|------|------|----------|

| Terraform vX.Y.Z | 版本正常 | 安装成功 |

| Success! The configuration is valid. | validate 通过 | 初始化完成 |

| Error: Failed to query available provider packages | Provider 下载失败 | 检查网络或配置镜像 |

| Error: Inconsistent dependency lock file | 锁文件不一致 | 执行 terraform init -upgrade |

| Error: Module not installed | 模块未下载 | 执行 terraform init |

| Error: No valid credential sources found | Provider 凭证缺失 | 参考 terraform-skill 配置凭证 |

自动化脚本

本技能提供 scripts/setup_terraform.py，用于一键检测+安装（从本技能目录执行）：

python scripts/setup_terraform.py

该脚本会：

1. 检测 terraform 是否已安装
2. 未安装则根据 OS/Arch 自动下载安装（macOS 优先用 Homebrew）
3. 输出版本信息确认安装成功

Agent 决策指南

当你（AI Agent）执行此技能时，按以下决策树操作：

开始
 │
 ├── which terraform → 未找到?
 │     └── 根据操作系统自动选择最佳安装方式（无需询问用户）
 │           ├── macOS → 优先 brew install，brew 不可用则手动下载
 │           └── Linux → 优先手动下载 zip，检测到 apt/yum 则用包管理器
 │
 ├── terraform version → 正常输出?
 │     └── 是 → ✅ Terraform 已就绪
 │
 ├── 当前目录有 .tf 文件?
 │     ├── 是 → terraform init
 │     │      ├── 成功 → terraform validate
 │     │      │      ├── 成功 → ✅ 初始化完成
 │     │      │      └── 失败 → 根据错误信息自动判断修复方案并执行
 │     │      └── Provider 下载失败 → 自动配置阿里云镜像源并重试
 │     └── 否 → ✅ 安装完成，等用户创建 .tf 文件后再 init
 │
 └── 遇到 Provider 凭证错误?
       └── 引导用户参考 terraform-skill 进行凭证配置

自动决策原则

重要：在执行本技能时，Agent 应当自动判断并选择最合适的方案和配置，无需询问用户，直接执行。

安装方式自动选择逻辑

| 操作系统 | 判断条件 | 自动选择 |

|----------|----------|----------|

| macOS | which brew 存在 | brew install hashicorp/tap/terraform |

| macOS | brew 不可用 | 手动下载对应架构的 zip 安装到 ~/.local/bin |

| Linux (Debian/Ubuntu) | which apt-get 存在 | APT 安装 |

| Linux (RHEL/CentOS) | which yum 存在 | YUM 安装 |

| Linux (其他) | 无包管理器 | 手动下载 zip 安装 |

Provider 下载失败自动处理

当 terraform init 因 Provider 下载失败时，自动配置阿里云镜像并重试：

cat > ~/.terraformrc << 'EOF'
provider_installation {
  network_mirror {
    url = "https://mirrors.aliyun.com/terraform/"
  }
}
EOF
terraform init

init 错误自动修复

| 错误类型 | 自动修复操作 |

|----------|-------------|

| Inconsistent dependency lock file | 自动执行 terraform init -upgrade |

| Module not installed | 自动执行 terraform init |

| Plugin reinitialization required | 自动执行 terraform init -upgrade |

| Backend initialization required | 自动执行 terraform init |

| Provider 凭证错误 | 引导参考 terraform-skill 配置凭证 |

执行原则

1. 所有可自动判断的场景直接由 Agent 根据环境检测结果自动选择最优方案并执行，不向用户提问
2. 安装方式根据操作系统和可用工具链自动决定
3. 错误修复根据错误类型自动匹配最佳修复策略
4. 镜像配置默认选择阿里云镜像
5. 仅在遇到需要用户提供敏感信息（如凭证）或无法自动决策的极端情况时，才以纯文本方式向用户说明

Terraform 中国镜像配置

国内网络环境下载 Provider 可能较慢，可配置镜像。

创建或编辑 ~/.terraformrc：

# 阿里云镜像
provider_installation {
  network_mirror {
    url = "https://mirrors.aliyun.com/terraform/"
  }
}

或腾讯云镜像：

provider_installation {
  network_mirror {
    url = "https://mirrors.tencent.com/terraform/"
  }
}

常见问题快速修复

| 问题 | 快速修复 |

|------|---------|

| command not found: terraform | brew install hashicorp/tap/terraform 或参照安装流程 |

| Error: Failed to query available provider packages | 检查网络连接，或配置 Terraform Registry 镜像 |

| Error: Backend initialization required | 执行 terraform init |

| Error: Plugin reinitialization required | 执行 terraform init -upgrade |

| Error: Inconsistent dependency lock file | 执行 terraform init -upgrade 更新锁文件 |

| Error: state snapshot was created by Terraform vX.Y.Z | 升级 Terraform 版本 |

| Error: Module not installed | 执行 terraform init 或 terraform get |

| Provider 下载超时 | 配置 Terraform Registry 镜像（见上方） |

| Error: No valid credential sources found | 此为 Provider 凭证问题，参考 terraform-skill |

配置文件位置

| 文件 | 位置 | 说明 |

|------|------|------|

| CLI 配置 | ~/.terraformrc（macOS/Linux） | 全局 CLI 配置（镜像等） |

| Provider 缓存 | ~/.terraform.d/plugins/ | 下载的 Provider 插件缓存 |

| 工作区 Provider | .terraform/providers/ | 当前工作区的 Provider 插件 |

| 锁文件 | .terraform.lock.hcl | Provider 版本锁定（应提交到 Git） |

| State 文件 | terraform.tfstate | 本地状态文件（不应提交到 Git） |

与其他技能的关系

| 技能 | 职责 |

|------|------|

| terraform-cli-setup（本技能） | Terraform CLI 的安装、init、镜像配置等基础环境 |

| terraform-skill | Terraform 实际使用：编写配置、Provider 凭证配置、模块开发、测试、CI/CD |

> 关于阿里云 ROS：阿里云资源编排服务（ROS）没有独立 CLI 工具，直接通过 aliyun ros <API> 使用 aliyun-cli 调用。如需使用 ROS，请确保 aliyun-cli 已安装（参考 alicloud_cli 技能）。

Interaction Tips

> 重要提示：在使用本技能时，请遵循以下规则：

>

> 1. 自动决策优先：安装方式、镜像选择、错误处理等场景，Agent 应根据环境检测结果自动选择最优方案并直接执行，不向用户提问

> 2. 执行过程中向用户简要说明正在做什么及原因，保持信息透明

> 3. 仅在需要用户提供无法自动获取的敏感信息（如凭证）时才向用户询问

> 4. 遇到错误时先自动尝试修复，修复失败后再向用户说明情况并提供建议

参考

• Terraform 官方文档：https://developer.hashicorp.com/terraform
• Terraform CLI 教程：https://developer.hashicorp.com/terraform/tutorials/cli
• Terraform 安装指南：https://developer.hashicorp.com/terraform/install
• Provider Registry：https://registry.terraform.io/
• GitHub 仓库：https://github.com/hashicorp/terraform