Terraform 基础设施即代码完全指南 2026：核心语法 + 状态管理 + 模块化 + CI/CD 集成

1
# ── Provider 配置 ──────────────────────────────────────────────
2
terraform {
3
  required_version = ">= 1.9.0"
4
  required_providers {
5
    aws = {
6
      source  = "hashicorp/aws"
7
      version = "~> 5.60"   # 允许 5.60.x，不允许 6.x
8
    }
9
  }
10
}
11

12
provider "aws" {
13
  region  = var.aws_region
14
  profile = "myprofile"    # ~/.aws/credentials 中的 profile
15

16
  default_tags {           # 所有资源自动加上这些标签
17
    tags = {
18
      Project     = var.project_name
19
      Environment = var.environment
20
      ManagedBy   = "terraform"
21
    }
22
  }
23
}
24

25
# ── 变量 ────────────────────────────────────────────────────────
26
variable "aws_region" {
27
  type        = string
28
  description = "AWS 部署区域"
29
  default     = "ap-northeast-1"
30
}
31

32
variable "environment" {
33
  type        = string
34
  description = "部署环境"
35
  validation {
36
    condition     = contains(["dev", "staging", "production"], var.environment)
37
    error_message = "environment 必须是 dev / staging / production 之一"
38
  }
39
}
40

41
variable "instance_type" {
42
  type    = string
43
  default = "t3.micro"
44
}
45

46
variable "project_name" {
47
  type    = string
48
  default = "myapp"
49
}
50

51
# ── Locals（本地计算值）──────────────────────────────────────────
52
locals {
53
  name_prefix = "${var.project_name}-${var.environment}"
54

55
  common_tags = {
56
    CreatedAt = timestamp()
57
  }
58

59
  # 根据环境选择不同配置
60
  instance_config = {
61
    dev        = { type = "t3.micro",  count = 1 }
62
    staging    = { type = "t3.small",  count = 1 }
63
    production = { type = "t3.medium", count = 3 }
64
  }
65
  current_config = local.instance_config[var.environment]
66
}
67

68
# ── 数据源（读取已有资源，不创建）──────────────────────────────
69
data "aws_ami" "amazon_linux" {
70
  most_recent = true
71
  owners      = ["amazon"]
72
  filter {
73
    name   = "name"
74
    values = ["al2023-ami-*-x86_64"]
75
  }
76
}
77

78
data "aws_vpc" "default" {
79
  default = true
80
}
81

82
data "aws_subnets" "public" {
83
  filter {
84
    name   = "vpc-id"
85
    values = [data.aws_vpc.default.id]
86
  }
87
}
88

89
# ── 资源 ────────────────────────────────────────────────────────
90
resource "aws_security_group" "web" {
91
  name        = "${local.name_prefix}-web-sg"
92
  description = "Web server security group"
93
  vpc_id      = data.aws_vpc.default.id
94

95
  ingress {
96
    from_port   = 80
97
    to_port     = 80
98
    protocol    = "tcp"
99
    cidr_blocks = ["0.0.0.0/0"]
100
  }
101
  ingress {
102
    from_port   = 443
103
    to_port     = 443
104
    protocol    = "tcp"
105
    cidr_blocks = ["0.0.0.0/0"]
106
  }
107
  egress {
108
    from_port   = 0
109
    to_port     = 0
110
    protocol    = "-1"
111
    cidr_blocks = ["0.0.0.0/0"]
112
  }
113
}
114

115
resource "aws_instance" "web" {
116
  count         = local.current_config.count
117
  ami           = data.aws_ami.amazon_linux.id
118
  instance_type = local.current_config.type
119
  subnet_id     = data.aws_subnets.public.ids[count.index % length(data.aws_subnets.public.ids)]
120

121
  vpc_security_group_ids = [aws_security_group.web.id]
122

123
  user_data = base64encode(templatefile("${path.module}/scripts/init.sh.tpl", {
124
    environment = var.environment
125
    app_name    = var.project_name
126
  }))
127

128
  tags = {
129
    Name = "${local.name_prefix}-web-${count.index + 1}"
130
  }
131
}
132

133
# ── 输出 ────────────────────────────────────────────────────────
134
output "instance_ids" {
135
  description = "Web 服务器实例 ID 列表"
136
  value       = aws_instance.web[*].id
137
}
138

139
output "public_ips" {
140
  description = "公网 IP 列表"
141
  value       = aws_instance.web[*].public_ip
142
}
143

144
output "security_group_id" {
145
  description = "安全组 ID"
146
  value       = aws_security_group.web.id
147
  sensitive   = false
148
}

1
terraform {
2
  backend "s3" {
3
    bucket         = "mycompany-terraform-state"
4
    key            = "myapp/production/terraform.tfstate"
5
    region         = "ap-northeast-1"
6
    encrypt        = true              # 加密存储
7

8
    # DynamoDB 状态锁（防止并发 apply）
9
    dynamodb_table = "terraform-state-lock"
10
  }
11
}

1
aws_region    = "ap-northeast-1"
2
environment   = "production"
3
project_name  = "myapp"
4
instance_type = "t3.medium"

1
variable "name_prefix"     { type = string }
2
variable "instance_type"   { type = string }
3
variable "ami_id"          { type = string }
4
variable "subnet_ids"      { type = list(string) }
5
variable "sg_ids"          { type = list(string) }
6
variable "instance_count"  { type = number; default = 1 }
7

8
resource "aws_instance" "this" {
9
  count                  = var.instance_count
10
  ami                    = var.ami_id
11
  instance_type          = var.instance_type
12
  subnet_id              = var.subnet_ids[count.index % length(var.subnet_ids)]
13
  vpc_security_group_ids = var.sg_ids
14
  tags = { Name = "${var.name_prefix}-${count.index + 1}" }
15
}
16

17
output "instance_ids" { value = aws_instance.this[*].id }
18
output "private_ips"  { value = aws_instance.this[*].private_ip }

1
import {
2
  id = "i-0a1b2c3d4e5f67890"
3
  to = aws_instance.web
4
}
5

6
# 可以先用 terraform plan 确认 import 内容，再 apply
7
# terraform plan      → 查看将要导入的资源
8
# terraform apply     → 执行导入，将资源纳入 state 管理

1
# 将 aws_instance.old_name 重命名为 aws_instance.new_name
2
moved {
3
  from = aws_instance.old_name
4
  to   = aws_instance.new_name
5
}
6

7
# 将模块内资源移动到另一个模块
8
moved {
9
  from = module.legacy.aws_s3_bucket.data
10
  to   = module.storage.aws_s3_bucket.data
11
}

1
name: Terraform CI/CD
2

3
on:
4
  push:
5
    branches: [main]
6
    paths: ["infrastructure/**"]
7
  pull_request:
8
    branches: [main]
9
    paths: ["infrastructure/**"]
10

11
permissions:
12
  contents: read
13
  pull-requests: write    # 在 PR 上写 plan 评论
14
  id-token: write         # OIDC 认证 AWS
15

16
env:
17
  TF_VERSION:  "1.9.4"
18
  AWS_REGION:  "ap-northeast-1"
19
  WORKING_DIR: "infrastructure/environments/production"
20

21
jobs:
22
  terraform:
23
    name: Terraform Plan & Apply
24
    runs-on: ubuntu-24.04
25
    defaults:
26
      run:
27
        working-directory: ${{ env.WORKING_DIR }}
28

29
    steps:
30
      - uses: actions/checkout@v4
31

32
      # OIDC 认证（无需 Access Key）
33
      - name: Configure AWS credentials
34
        uses: aws-actions/configure-aws-credentials@v4
35
        with:
36
          role-to-assume: arn:aws:iam::123456789:role/terraform-github-role
37
          aws-region: ${{ env.AWS_REGION }}
38

39
      - name: Setup Terraform
40
        uses: hashicorp/setup-terraform@v3
41
        with:
42
          terraform_version: ${{ env.TF_VERSION }}
43

44
      - name: Terraform Init
45
        run: terraform init
46

47
      - name: Terraform Format Check
48
        run: terraform fmt -check -recursive
49

50
      - name: Terraform Validate
51
        run: terraform validate
52

53
      # Plan（每次 PR 触发）
54
      - name: Terraform Plan
55
        id: plan
56
        run: |
57
          terraform plan \
58
            -var-file="terraform.tfvars" \
59
            -no-color \
60
            -out=tfplan
61
        continue-on-error: true
62

63
      # 将 plan 结果评论到 PR
64
      - name: Comment Plan on PR
65
        uses: actions/github-script@v7
66
        if: github.event_name == 'pull_request'
67
        with:
68
          script: |
69
            const output = `### Terraform Plan
70
            \`\`\`
71
            ${{ steps.plan.outputs.stdout }}
72
            \`\`\`
73
            *Pushed by: @${{ github.actor }}, Action: \`${{ github.event_name }}\`*`;
74

75
            github.rest.issues.createComment({
76
              issue_number: context.issue.number,
77
              owner: context.repo.owner,
78
              repo: context.repo.repo,
79
              body: output
80
            })
81

82
      # 仅 main 分支 push 时自动 Apply
83
      - name: Terraform Apply
84
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
85
        run: terraform apply -auto-approve tfplan