Terraform 快速入门：用 IaC 管理 AWS 资源并模块化创建 DynamoDB#

Terraform 是 HashiCorp 推出的基础设施即代码工具。它把云资源写成声明式配置文件，通过 plan 预览变更，再通过 apply 创建或更新资源。对 AWS 来说，它很适合管理 VPC、IAM、KMS、DynamoDB、S3、EKS 等资源。

这篇文章用一个小而完整的例子入门：先理解 Terraform 的基础语法，再用 AWS Provider 创建 DynamoDB 表，最后把 DynamoDB 封装成 module，演示如何创建和更新资源。

适合谁阅读#

已经会使用 AWS Console 或 AWS CLI，但想用代码管理资源
想快速理解 .tf 文件、变量、输出、module、state 的关系
想用 Terraform 管理 DynamoDB 表结构、标签、TTL、二级索引

Terraform 工作流#

Terraform 的日常工作流通常是四步：

1
terraform init
2
terraform fmt
3
terraform validate
4
terraform plan
5
terraform apply

各命令的作用如下：

命令	作用
`terraform init`	初始化工作目录，下载 provider 和 module
`terraform fmt`	格式化 `.tf` 文件
`terraform validate`	检查语法和配置是否有效
`terraform plan`	预览 Terraform 将执行的创建、更新、删除
`terraform apply`	执行变更
`terraform destroy`	删除当前配置管理的资源

建议养成一个习惯：任何变更先看 plan，确认无误后再 apply。

Terraform 基础语法#

Terraform 配置语言叫 HCL，核心概念并不多。

1. Block：配置块#

Terraform 用 block 表达一组配置。常见 block 包括 terraform、provider、resource、variable、output、module。

1
resource "aws_dynamodb_table" "orders" {
2
  name         = "demo-orders"
3
  billing_mode = "PAY_PER_REQUEST"
4
}

这里的结构是：

1
resource "<资源类型>" "<本地名称>" {
2
  参数 = 值
3
}

aws_dynamodb_table.orders 是 Terraform 内部引用地址，不一定等于 AWS 上的资源名称。

2. Argument：参数#

block 内部的 name = "demo-orders"、billing_mode = "PAY_PER_REQUEST" 都是 argument。

1
region = "ap-southeast-1"

3. Expression：表达式#

Terraform 支持字符串、数字、布尔值、列表、Map、对象、条件表达式和函数调用。

1
name = "${var.project}-${var.environment}-orders"
2

3
tags = {
4
  Project     = var.project
5
  Environment = var.environment
6
  ManagedBy   = "Terraform"
7
}

在新版 Terraform 中，简单引用通常不需要 "${...}"：

1
table_name = aws_dynamodb_table.orders.name

4. Variable：变量#

变量用于把可变化的值从代码中抽出来。

1
variable "environment" {
2
  description = "部署环境，例如 dev、staging、prod"
3
  type        = string
4
  default     = "dev"
5
}

使用变量：

1
name = "demo-${var.environment}-orders"

5. Local：本地值#

locals 适合放组合出来的值，减少重复。

1
locals {
2
  name_prefix = "${var.project}-${var.environment}"
3

4
  common_tags = {
5
    Project     = var.project
6
    Environment = var.environment
7
    ManagedBy   = "Terraform"
8
  }
9
}

使用：

1
name = "${local.name_prefix}-orders"
2
tags = local.common_tags

6. Output：输出#

output 用来把关键信息暴露出来，例如表名、ARN。

1
output "orders_table_name" {
2
  value = aws_dynamodb_table.orders.name
3
}

执行 terraform apply 后，终端会显示输出值。

7. Provider：云厂商插件#

Provider 负责和云 API 通信。管理 AWS 资源时，需要配置 AWS Provider。

1
terraform {
2
  required_version = ">= 1.6.0"
3

4
  required_providers {
5
    aws = {
6
      source  = "hashicorp/aws"
7
      version = "~> 5.0"
8
    }
9
  }
10
}
11

12
provider "aws" {
13
  region = var.aws_region
14
}

8. State：状态文件#

Terraform 会把“代码中的资源”和“云上的真实资源”映射到 state。默认是本地 terraform.tfstate，团队协作时通常要改成远程后端，例如 S3 + DynamoDB Lock。

入门阶段可以先用本地 state；生产环境建议使用远程 state，并限制访问权限。

项目目录结构#

一个适合入门和扩展的目录可以这样组织：

1
terraform-aws-demo/
2
├── main.tf
3
├── variables.tf
4
├── outputs.tf
5
├── terraform.tfvars
6
└── modules/
7
    └── dynamodb_table/
8
        ├── main.tf
9
        ├── variables.tf
10
        └── outputs.tf

顶层目录描述“当前环境需要哪些资源”，modules/dynamodb_table 描述“如何创建一个标准 DynamoDB 表”。

案例一：直接创建 DynamoDB 表#

先看不使用 module 的版本，便于理解资源本身。

main.tf#

1
terraform {
2
  required_version = ">= 1.6.0"
3

4
  required_providers {
5
    aws = {
6
      source  = "hashicorp/aws"
7
      version = "~> 5.0"
8
    }
9
  }
10
}
11

12
provider "aws" {
13
  region = "ap-southeast-1"
14
}
15

16
resource "aws_dynamodb_table" "orders" {
17
  name         = "demo-dev-orders"
18
  billing_mode = "PAY_PER_REQUEST"
19
  hash_key     = "pk"
20
  range_key    = "sk"
21

22
  attribute {
23
    name = "pk"
24
    type = "S"
25
  }
26

27
  attribute {
28
    name = "sk"
29
    type = "S"
30
  }
31

32
  ttl {
33
    attribute_name = "expires_at"
34
    enabled        = true
35
  }
36

37
  point_in_time_recovery {
38
    enabled = true
39
  }
40

41
  tags = {
42
    Project     = "terraform-demo"
43
    Environment = "dev"
44
    ManagedBy   = "Terraform"
45
  }
46
}

执行创建#

1
terraform init
2
terraform fmt
3
terraform validate
4
terraform plan
5
terraform apply

确认 plan 中只包含你期望创建的 DynamoDB 表后，再输入 yes。

案例二：用 module 创建 DynamoDB 表#

直接写资源适合学习，但真实项目里通常会把通用资源封装成 module。module 的价值是统一命名、标签、安全配置和默认能力。

modules/dynamodb_table/variables.tf#

1
variable "name" {
2
  description = "DynamoDB 表名"
3
  type        = string
4
}
5

6
variable "hash_key" {
7
  description = "分区键名称"
8
  type        = string
9
}
10

11
variable "range_key" {
12
  description = "排序键名称，可选"
13
  type        = string
14
  default     = null
15
}
16

17
variable "attributes" {
18
  description = "DynamoDB attribute 定义"
19
  type = list(object({
20
    name = string
21
    type = string
22
  }))
23
}
24

25
variable "ttl_attribute_name" {
26
  description = "TTL 字段名，留空则不启用 TTL"
27
  type        = string
28
  default     = null
29
}
30

31
variable "global_secondary_indexes" {
32
  description = "全局二级索引配置"
33
  type = list(object({
34
    name            = string
35
    hash_key        = string
36
    range_key       = optional(string)
37
    projection_type = optional(string, "ALL")
38
  }))
39
  default = []
40
}
41

42
variable "tags" {
43
  description = "资源标签"
44
  type        = map(string)
45
  default     = {}
46
}

modules/dynamodb_table/main.tf#

1
resource "aws_dynamodb_table" "this" {
2
  name         = var.name
3
  billing_mode = "PAY_PER_REQUEST"
4
  hash_key     = var.hash_key
5
  range_key    = var.range_key
6

7
  dynamic "attribute" {
8
    for_each = var.attributes
9

10
    content {
11
      name = attribute.value.name
12
      type = attribute.value.type
13
    }
14
  }
15

16
  dynamic "ttl" {
17
    for_each = var.ttl_attribute_name == null ? [] : [var.ttl_attribute_name]
18

19
    content {
20
      attribute_name = ttl.value
21
      enabled        = true
22
    }
23
  }
24

25
  dynamic "global_secondary_index" {
26
    for_each = var.global_secondary_indexes
27

28
    content {
29
      name            = global_secondary_index.value.name
30
      hash_key        = global_secondary_index.value.hash_key
31
      range_key       = try(global_secondary_index.value.range_key, null)
32
      projection_type = try(global_secondary_index.value.projection_type, "ALL")
33
    }
34
  }
35

36
  point_in_time_recovery {
37
    enabled = true
38
  }
39

40
  tags = var.tags
41
}

这里用到了两个重要语法：

dynamic：用于动态生成重复嵌套块，比如多个 attribute、多个 global_secondary_index
for_each：遍历集合，为每个元素生成一段配置

modules/dynamodb_table/outputs.tf#

1
output "name" {
2
  description = "DynamoDB 表名"
3
  value       = aws_dynamodb_table.this.name
4
}
5

6
output "arn" {
7
  description = "DynamoDB 表 ARN"
8
  value       = aws_dynamodb_table.this.arn
9
}

顶层 variables.tf#

1
variable "aws_region" {
2
  description = "AWS 区域"
3
  type        = string
4
  default     = "ap-southeast-1"
5
}
6

7
variable "project" {
8
  description = "项目名"
9
  type        = string
10
  default     = "terraform-demo"
11
}
12

13
variable "environment" {
14
  description = "环境名"
15
  type        = string
16
  default     = "dev"
17
}

顶层 main.tf#

1
terraform {
2
  required_version = ">= 1.6.0"
3

4
  required_providers {
5
    aws = {
6
      source  = "hashicorp/aws"
7
      version = "~> 5.0"
8
    }
9
  }
10
}
11

12
provider "aws" {
13
  region = var.aws_region
14
}
15

16
locals {
17
  name_prefix = "${var.project}-${var.environment}"
18

19
  common_tags = {
20
    Project     = var.project
21
    Environment = var.environment
22
    ManagedBy   = "Terraform"
23
  }
24
}
25

26
module "orders_table" {
27
  source = "./modules/dynamodb_table"
28

29
  name      = "${local.name_prefix}-orders"
30
  hash_key  = "pk"
31
  range_key = "sk"
32

33
  attributes = [
34
    {
35
      name = "pk"
36
      type = "S"
37
    },
38
    {
39
      name = "sk"
40
      type = "S"
41
    },
42
    {
43
      name = "customer_id"
44
      type = "S"
45
    }
46
  ]
47

48
  ttl_attribute_name = "expires_at"
49

50
  global_secondary_indexes = [
51
    {
52
      name      = "customer-index"
53
      hash_key  = "customer_id"
54
      range_key = "sk"
55
    }
56
  ]
57

58
  tags = local.common_tags
59
}

顶层 outputs.tf#

1
output "orders_table_name" {
2
  value = module.orders_table.name
3
}
4

5
output "orders_table_arn" {
6
  value = module.orders_table.arn
7
}

执行：

1
terraform init
2
terraform plan
3
terraform apply

创建完成后，Terraform 会输出表名和 ARN。

如何更新 DynamoDB 表#

Terraform 的更新方式不是重新执行一段“更新脚本”，而是修改 .tf 配置，然后让 Terraform 计算差异。

示例 1：增加一个 GSI#

假设要按订单状态查询，可以给 module 调用增加 status-index：

1
attributes = [
2
  {
3
    name = "pk"
4
    type = "S"
5
  },
6
  {
7
    name = "sk"
8
    type = "S"
9
  },
10
  {
11
    name = "customer_id"
12
    type = "S"
13
  },
14
  {
15
    name = "status"
16
    type = "S"
17
  }
18
]
19

20
global_secondary_indexes = [
21
  {
22
    name      = "customer-index"
23
    hash_key  = "customer_id"
24
    range_key = "sk"
25
  },
26
  {
27
    name      = "status-index"
28
    hash_key  = "status"
29
    range_key = "sk"
30
  }
31
]

然后执行：

1
terraform plan
2
terraform apply

注意：DynamoDB 的 GSI 创建和回填需要时间，生产环境需要关注表容量、写入流量和索引构建状态。

示例 2：更新标签#

修改 local.common_tags：

1
locals {
2
  common_tags = {
3
    Project     = var.project
4
    Environment = var.environment
5
    ManagedBy   = "Terraform"
6
    Owner       = "platform-team"
7
  }
8
}

执行 terraform plan 后，你会看到 Terraform 只计划更新 tags。

示例 3：关闭或更换 TTL 字段#

如果不需要 TTL，可以把：

1
ttl_attribute_name = "expires_at"

改为：

1
ttl_attribute_name = null

或者干脆不传该参数。变更前建议先确认应用是否仍然写入 TTL 字段，以及是否依赖自动过期能力。

terraform.tfvars 示例#

如果不想把环境值写死在 main.tf，可以使用 terraform.tfvars：

1
aws_region  = "ap-southeast-1"
2
project     = "order-service"
3
environment = "dev"

执行 terraform plan 时，Terraform 会自动读取当前目录下的 terraform.tfvars。

也可以为不同环境准备不同变量文件：

1
terraform plan -var-file=dev.tfvars
2
terraform apply -var-file=dev.tfvars

常见坑#

1. attribute 不是字段清单#

aws_dynamodb_table 里的 attribute 只需要声明表主键和索引用到的 attribute，不需要把业务里的所有字段都写进去。DynamoDB 是 schemaless 的，普通字段由应用写入。

2. 修改 key schema 通常不是普通更新#

DynamoDB 表的主键设计非常关键。创建后如果要改 hash_key 或 range_key，通常意味着需要新建表并迁移数据。不要把主键设计当成可以随时修改的参数。

3. 生产环境不要随便 destroy#

terraform destroy 会删除当前 state 管理的资源。DynamoDB 表里通常有业务数据，生产环境建议启用删除保护策略、备份和变更审批。

4. 团队协作要使用远程 state#

多人使用本地 state 容易互相覆盖状态。生产项目建议使用 S3 backend，并配合 state lock，避免同时 apply。

一份最小命令清单#

1
# 初始化
2
terraform init
3

4
# 格式化
5
terraform fmt -recursive
6

7
# 校验
8
terraform validate
9

10
# 预览
11
terraform plan -out tfplan
12

13
# 执行指定 plan
14
terraform apply tfplan
15

16
# 查看当前 state 管理的资源
17
terraform state list
18

19
# 查看某个资源状态
20
terraform state show module.orders_table.aws_dynamodb_table.this

总结#

Terraform 入门的关键不是记住所有资源参数，而是理解它的工作方式：

用 HCL 描述期望状态
用 Provider 调用云 API
用 State 记录资源映射
用 plan 审查差异
用 module 把可复用的基础设施模式沉淀下来

DynamoDB 是一个很好的练习对象：表名、主键、TTL、PITR、GSI、标签都能覆盖 Terraform 的常见语法。掌握这个例子后，再去管理 S3、KMS、IAM、EKS 等资源，思路基本一致。