开始使用 Terraform
在 Debian 或 Ubuntu 上了解 Terraform:提供程序、plan、apply、状态管理与机密保护,并附通用示例。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
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:
terraform {
required_version = ">= 1.11"
required_providers {
local = {
source = "hashicorp/local"
version = "~> 2.9"
}
random = {
source = "hashicorp/random"
version = "~> 3.9"
}
}
}声明变量
创建 variables.tf:
variable "ssh_user" {
description = "服务器的 SSH 用户"
type = string
}
variable "servers" {
description = "要写入清单的服务器(名称 => IP 地址)"
type = map(string)
validation {
condition = length(var.servers) > 0
error_message = "请至少声明一台服务器。"
}
}在 terraform.tfvars 中为它们赋值,该文件会被自动加载:
ssh_user = "您的用户名"
servers = {
web1 = "您的服务器IP"
}描述资源
创建清单模板 inventory.tftpl:
[web]
%{ for name, ip in servers ~}
${name} ansible_host=${ip} ansible_user=${ssh_user}
%{ endfor ~}然后创建 main.tf:
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:
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 planapp.env 文件的权限应为 -rw-------,app_token 输出应显示为 <sensitive>,最后一次 plan 应提示 No changes。
修改基础设施
在 terraform.tfvars 中添加一台服务器:
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_ 环境变量传入:
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 既不会将其保存到状态中,也不会保存到计划中。
variable "api_token" {
description = "提供程序所用 API 的令牌"
type = string
sensitive = true
ephemeral = true
}临时变量在执行 terraform apply 时必须重新提供,并且不能用于任意参数。如需机密保险库,请参阅指南 安装 HashiCorp Vault。
远程存储状态
一旦有多人或多台机器使用该项目,就应将状态放入加密、私有且带锁的远程存储中。以下是使用 s3 后端的通用示例,需添加到 terraform 块中:
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 和各个参数都是虚构的:
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 -upgradeBackend initialization required
后端配置已更改。请重新运行 terraform init,或运行 terraform init -migrate-state 来迁移状态。
Error acquiring the state lock
另一次执行持有该锁,或某次执行被中断。请先确认没有任何命令正在运行,之后才使用所显示的标识符:
terraform force-unlock 锁IDSaved plan is stale
自创建计划以来状态已发生变化。请生成新的计划,审阅后再应用。
Failed to query available provider packages
请检查提供程序名称、version 约束以及对 registry.terraform.io 的访问:
curl -I https://registry.terraform.io/.well-known/terraform.jsonNo value for required variable
请在 terraform.tfvars 中填写该变量,或使用 -var,或使用 TF_VAR_nom。
计划要替换某个资源
请在计划中查找 forces replacement 字样。如果您只是重命名了某个资源,请使用 terraform state mv 或 moved 块,而不是接受其重新创建。