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 步：检测安装状态 ```bash which terraform 2>/dev/null || echo "NOT_INSTALLED" ``` 如果未安装，进入安装流程。如果已安装，跳到第 3 步。 ### 第 2 步：安装 Terraform #### macOS (Homebrew — 推荐) ```bash brew tap hashicorp/tap brew install hashicorp/tap/terraform ``` #### macOS (手动下载) ```bash 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 (手动下载) ```bash 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) ```bash 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) ```bash 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 ``` 安装后验证： ```bash terraform version ``` ### 第 3 步：初始化 Terraform 工作区 在有 `.tf` 文件的目录中执行： ```bash terraform init ``` `terraform init` 会执行： 1. **初始化 Backend** — 配置状态存储（默认为本地） 2. **安装 Provider 插件** — 下载 `.tf` 中声明的 Provider 3. **下载模块** — 获取引用的远程模块 4. **创建锁文件** — 生成 `.terraform.lock.hcl` 锁定版本 常见 init 选项： ```bash # 升级 Provider 和模块到约束范围内的最新版本 terraform init -upgrade # 重新配置 Backend terraform init -reconfigure # 迁移 State 到新 Backend terraform init -migrate-state ``` ### 第 4 步：验证安装与初始化 ```bash # 检查版本 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`，用于一键检测+安装（从本技能目录执行）： ```bash 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 下载失败时，**自动配置阿里云镜像**并重试： ```bash 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`： ```hcl # 阿里云镜像 provider_installation { network_mirror { url = "https://mirrors.aliyun.com/terraform/" } } ``` 或腾讯云镜像： ```hcl 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