中文

应用程序

开始使用 Terraform

在 Debian 或 Ubuntu 上了解 Terraform:提供程序、plan、apply、状态管理与机密保护,并附通用示例。

阅读约 6 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

Terraform 在文本文件中描述基础设施,将该描述与现有环境进行比较,然后只应用必要的变更。它依赖提供程序(providers),由提供程序负责与特定服务通信。

本指南通过一个无需任何外部账户即可运行的示例介绍基础知识:Terraform 会生成一个随机密码、一份 Ansible 清单和一个本地配置文件。

术语 含义
提供程序(Provider) 用于访问某个服务或资源的扩展
资源(Resource) 由 Terraform 管理的对象
变量(Variable) 配置的输入值
输出(Output) 应用之后公开的值
计划(Plan) Terraform 提议执行的变更列表
状态(State) 将配置与实际对象关联起来的文件

前提条件

  • 一台运行 Debian 12/13 或 Ubuntu 22.04/24.04 的机器:您的电脑或一台管理服务器
  • 拥有 sudo 权限的用户
  • 可对外访问 apt.releases.hashicorp.com 和 registry.terraform.io 的 HTTPS 连接

Terraform 不监听任何端口,此示例也不需要开放任何入站端口。

安装 Terraform

添加 HashiCorp 的官方软件源,然后安装软件包:

终端
sudo apt update
sudo apt install -y wget gpg lsb-release
wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update
sudo apt install -y terraform
terraform version

创建项目

终端
mkdir -p ~/terraform-demo
cd ~/terraform-demo

声明 Terraform 和提供程序

创建 versions.tf:

hcl
terraform {
  required_version = ">= 1.11"

  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.9"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.9"
    }
  }
}

声明变量

创建 variables.tf:

hcl
variable "ssh_user" {
  description = "服务器的 SSH 用户"
  type        = string
}

variable "servers" {
  description = "要写入清单的服务器(名称 => IP 地址)"
  type        = map(string)

  validation {
    condition     = length(var.servers) > 0
    error_message = "请至少声明一台服务器。"
  }
}

在 terraform.tfvars 中为它们赋值,该文件会被自动加载:

hcl
ssh_user = "您的用户名"

servers = {
  web1 = "您的服务器IP"
}

描述资源

创建清单模板 inventory.tftpl:

文本
[web]
%{ for name, ip in servers ~}
${name} ansible_host=${ip} ansible_user=${ssh_user}
%{ endfor ~}

然后创建 main.tf:

hcl
resource "random_password" "app_token" {
  length  = 32
  special = false
}

resource "local_file" "inventory" {
  filename        = "${path.module}/generated/inventory.ini"
  file_permission = "0644"

  content = templatefile("${path.module}/inventory.tftpl", {
    servers  = var.servers
    ssh_user = var.ssh_user
  })
}

resource "local_sensitive_file" "app_env" {
  filename        = "${path.module}/generated/app.env"
  file_permission = "0600"
  content         = "APP_TOKEN=${random_password.app_token.result}\n"
}

以及 outputs.tf:

hcl
output "inventory_path" {
  description = "生成的清单路径"
  value       = local_file.inventory.filename
}

output "app_token" {
  description = "为应用生成的令牌"
  value       = random_password.app_token.result
  sensitive   = true
}

将本地文件排除在 Git 之外

请在首次提交之前创建 .gitignore:

文本
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfplan
generated/

相反,应将 .terraform.lock.hcl 纳入版本管理,它会固定提供程序的确切版本。

初始化与验证

终端
terraform init
terraform fmt
terraform validate
命令 作用
terraform init 下载提供程序并准备目录
terraform fmt 统一格式
terraform validate 检查配置是否一致

规划与应用

保存计划,以便准确应用您已审阅过的内容:

终端
terraform plan -out=demo.tfplan
terraform apply demo.tfplan

在计划中,+ 表示创建,~ 表示修改,- 表示删除,-/+ 表示替换。应用之前请务必阅读这些行,尤其是删除和替换。

检查结果:

终端
terraform output
terraform output -raw inventory_path; echo
cat generated/inventory.ini
ls -l generated/
terraform plan

app.env 文件的权限应为 -rw-------,app_token 输出应显示为 <sensitive>,最后一次 plan 应提示 No changes。

修改基础设施

在 terraform.tfvars 中添加一台服务器:

hcl
servers = {
  web1 = "您的服务器IP"
  web2 = "第二台服务器IP"
}
终端
terraform plan -out=demo.tfplan
terraform apply demo.tfplan

计划会提示仅替换清单文件(1 to add、1 to destroy):令牌保持不变。生成的文件随后可用于 playbook,如指南 使用 Ansible 自动化管理服务器 所示。

理解状态

执行 apply 之后,Terraform 会在 terraform.tfstate 中记录它所管理的内容。请使用专用命令查看它,不要手动修改:

终端
terraform state list
terraform state show local_file.inventory
命令 用途
terraform state list 列出被跟踪的资源
terraform state show 地址 显示某个资源
terraform state mv 源地址 目标地址 重命名资源而不重新创建
terraform state rm 地址 停止跟踪某个资源,但不删除它
terraform import 地址 ID 关联一个已有对象(如果提供程序支持)

请将本地文件的权限限制到最低:

终端
chmod 600 terraform.tfstate terraform.tfstate.backup demo.tfplan 2>/dev/null || true

管理机密

不要在 .tf 文件中放置机密。请改为通过 TF_VAR_ 环境变量传入:

hcl
variable "api_token" {
  description = "提供程序所用 API 的令牌"
  type        = string
  sensitive   = true
}
终端
read -rs TF_VAR_api_token
export TF_VAR_api_token
terraform plan -out=demo.tfplan
unset TF_VAR_api_token

如果该值仅用于配置某个提供程序,或用于填充只写(write-only)参数,请将其声明为临时变量:这样 Terraform 既不会将其保存到状态中,也不会保存到计划中。

hcl
variable "api_token" {
  description = "提供程序所用 API 的令牌"
  type        = string
  sensitive   = true
  ephemeral   = true
}

临时变量在执行 terraform apply 时必须重新提供,并且不能用于任意参数。如需机密保险库,请参阅指南 安装 HashiCorp Vault。

远程存储状态

一旦有多人或多台机器使用该项目,就应将状态放入加密、私有且带锁的远程存储中。以下是使用 s3 后端的通用示例,需添加到 terraform 块中:

hcl
terraform {
  backend "s3" {
    bucket       = "mon-etat-terraform"
    key          = "demo/terraform.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true
  }
}

请通过环境变量提供凭据,切勿写入此块,然后迁移现有状态:

终端
terraform init -migrate-state

使用其他提供程序

对于任何有提供程序的服务,其逻辑都是一样的。请在 Terraform Registry 中查找,阅读其文档,并确认由谁维护。通用形式如下。editeur/service 和各个参数都是虚构的:

hcl
terraform {
  required_providers {
    service = {
      source  = "editeur/service"
      version = "~> 1.0"
    }
  }
}

provider "service" {
  api_token = var.api_token
}

请只授予 API 令牌严格必要的权限,并先在测试项目上开始:apply 会真实地作用于账户中的资源。

更新

Terraform 通过 APT 更新。提供程序则在 version 的限制范围内更新:

终端
sudo apt update
sudo apt install --only-upgrade terraform
terraform init -upgrade
terraform plan

请审阅计划,如果 .terraform.lock.hcl 文件发生了变化,则将其纳入版本管理。

备份

请将配置和 .terraform.lock.hcl 保存在私有 Git 仓库中。对于状态,请为远程存储启用版本控制。如果使用本地状态,请创建一份受保护的副本:

终端
install -m 600 /dev/null "$HOME/terraform-demo-$(date +%F).tfstate"
terraform state pull > "$HOME/terraform-demo-$(date +%F).tfstate"

该副本包含机密:请加密存放,并保存在服务器之外。如果状态丢失,Terraform 就无法知道它管理着哪些对象。

销毁资源

先预览删除操作,然后再应用:

终端
terraform plan -destroy -out=destroy.tfplan
terraform apply destroy.tfplan

在此示例中,只会删除本地文件和令牌。使用真实的提供程序时,此操作可能会删除服务及其数据。

故障排查

Inconsistent dependency lock file

所请求的提供程序与锁定文件不一致。确认变更无误后:

终端
terraform init -upgrade

Backend initialization required

后端配置已更改。请重新运行 terraform init,或运行 terraform init -migrate-state 来迁移状态。

Error acquiring the state lock

另一次执行持有该锁,或某次执行被中断。请先确认没有任何命令正在运行,之后才使用所显示的标识符:

终端
terraform force-unlock 锁ID

Saved plan is stale

自创建计划以来状态已发生变化。请生成新的计划,审阅后再应用。

Failed to query available provider packages

请检查提供程序名称、version 约束以及对 registry.terraform.io 的访问:

终端
curl -I https://registry.terraform.io/.well-known/terraform.json

No value for required variable

请在 terraform.tfvars 中填写该变量,或使用 -var,或使用 TF_VAR_nom。

计划要替换某个资源

请在计划中查找 forces replacement 字样。如果您只是重命名了某个资源,请使用 terraform state mv 或 moved 块,而不是接受其重新创建。

参考资料