terraform-cli-setup

Terraform CLI 安装与初始化技能。当用户本地未安装 Terraform 时自动完成安装，确保 terraform 命令可用并能执行 init/validate。不负责 Provider 凭证配置，凭证在实际使用时由 terraform-skill 引导。

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Medium

Suggest reviewing before use

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 会执行：

初始化 Backend — 配置状态存储（默认为本地）
安装 Provider 插件 — 下载 .tf 中声明的 Provider
下载模块 — 获取引用的远程模块
创建锁文件 — 生成 .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

该脚本会：

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

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 配置凭证

执行原则

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

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

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

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

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

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

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

参考

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

Repository: agentscope-ai/QwenPaw
Path: plugins/bundle/cloudpaw/skills/terraform-cli-setup/SKILL.md
Commit: 734c8b9

Last updated: 3 days ago
First committed: 3 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.