Terraform 核心操作速查

用途：供 AI 助手快速查阅并编写/执行 Terraform 基础设施代码。场景：用代码管理 Hyper-V/云上的虚拟机资源。 更新日期：2026-11-11 版本基线：Terraform 1.17.1（核对日期 2026-11-11，来源：官网）

1. 概念与安装

# 安装（Ubuntu）
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

# 核心概念
# provider：对接的平台（hyperv / libvirt / aws / 阿里云…）
# resource：被管理的资源（一台 VM、一个网络）
# state：terraform.tfstate 记录真实资源与代码的映射（核心文件，勿手改、勿泄露）

# 许可与背景：Terraform 自 1.6 起采用 BSL 1.1（源码可得、非开源），
# HashiCorp 已被 IBM 收购（2025 年完成）；BSL 对普通使用无影响。
# 开源替代为 OpenTofu（MPL 2.0，Linux Foundation，截至 2026-11 最新 1.13.x）。

2. 标准工作流（五步固定流程）

terraform init        # 初始化/下载 provider（换 provider 版本后重跑）
terraform validate    # 语法校验
terraform plan        # 预览变更（+创建 -销毁 ~修改，逐行确认）
terraform apply       # 执行变更（要输 yes；自动化加 -auto-approve 前必须确认 plan）
terraform destroy     # 销毁全部资源（高危）

3. 配置模板

# main.tf
terraform {
  required_providers {
    # 本地 Hyper-V 场景可用社区 provider（telmate/proxmox 类似思路），
    # 云上实验更推荐直接用云 provider
    docker = { source = "kreuzwerker/docker", version = "~> 3.0" }
  }
}

provider "docker" {}

resource "docker_container" "tts" {
  name  = "tts"
  image = docker_image.tts.image_id
  ports { internal = 5000, external = 5000 }
}

resource "docker_image" "tts" {
  name = "myrepo/tts:1.0"
}

output "container_id" { value = docker_container.tts.id }

4. 变量与多环境

# variables.tf
variable "env" {
  type    = string
  default = "dev"
  validation {
    condition     = contains(["dev", "prod"], var.env)
    error_message = "env 只能是 dev 或 prod"
  }
}
variable "replicas" { type = number, default = 2 }

# locals.tf 本地计算值
locals {
  name_prefix = "lab-${var.env}"
}

terraform apply -var="env=prod" -var="replicas=3"
terraform apply -var-file="prod.tfvars"
terraform output                     # 查看输出值

5. 状态与远程存储

terraform state list                        # 查看管理的资源
terraform state show <资源地址>              # 某资源详情
terraform state rm <资源地址>                # 从管理中移除（不销毁资源本身；1.7+ 更推荐代码里写 removed 块）
terraform import <资源类型>.<名> <真实ID>    # 把已存在资源纳入管理（1.5+ 也可用 import 块声明式导入）
terraform refresh / plan -refresh-only      # 刷新真实状态（refresh 已弃用，优先 -refresh-only）

# 远程 state（团队/多机场景）
# terraform { backend "s3" { ... } }  或本地实验直接默认本地文件

6. 常用技巧

terraform fmt -recursive        # 代码格式化（写完必跑）
terraform plan -out=tfplan      # 保存 plan，apply 用同一份：terraform apply tfplan
terraform destroy -target=<资源> # 只销毁某个资源（慎用，target 尽量只用于实验）
terraform init -upgrade         # 更新 provider 与模块（"terraform upgrade" 不是命令）
terraform test                  # 配置测试框架（1.6 起内置稳定，支持 mock_provider）

# 近年重要新特性（速记）：
# - removed 块：代码中声明删除资源而不销毁（1.7+，替代 state rm 的首选写法）
# - ephemeral 资源 / write-only 属性：敏感值不落 state（1.10 / 1.11+）
# - S3 backend 无需 DynamoDB 即可加锁（1.11 GA）
# - 变量/输出可标记 deprecated（1.15）；plan -minimal-refresh 只刷新有变更的资源（1.17）

模块化复用：

module "k8s_nodes" {
  source   = "./modules/vm"
  count    = 3                       # 或在模块内 for_each
  name     = "node-${count.index}"
  memory   = 4096
}

7. 与本环境的关系（Vagrant 对比）

维度	Vagrant	Terraform
定位	本地开发/实验环境生命周期	基础设施即代码（含云）
长寿命、多环境管理	弱	强
Hyper-V 支持	内置 provider	需社区 provider 或转用云/Proxmox
学习价值	入门快	云原生就业市场硬通货

实验建议：本机先用好 Vagrant；Terraform 主要练 Docker provider / 云 provider（阿里云/AWS 免费额度）+ 状态管理 + module 化，以后上云直接复用。

8. AI 助手操作守则

• 固定流程 init → validate → plan → apply；任何 apply 前必须把 plan 的增删改摘要给用户看，destroy 必须二次确认。
• terraform.tfstate 与 .tfvars（含密钥）不入 git，写好 .gitignore。
• 不手改 state 文件；漂移排查用 plan 观察 diff。
• HCL 代码写完先 terraform fmt 再交付。