terraform-style-check

Terraform 风格指南

按照 HashiCorp 的官方风格约定和最佳实践生成并维护 Terraform 代码。

参考： HashiCorp Terraform 风格指南

代码生成策略

生成 Terraform 代码时：

1. 从提供商配置和版本约束开始
2. 在依赖资源之前创建数据源
3. 按依赖顺序构建资源
4. 为关键资源属性添加输出
5. 使用变量表示所有可配置的值

文件组织

文件	用途
terraform.tf	Terraform 和提供商的版本要求
providers.tf	提供商配置
main.tf	主要资源和数据源
variables.tf	输入变量声明（按字母顺序排列）
outputs.tf	输出值声明（按字母顺序排列）
locals.tf	局部值声明

示例结构

# terraform.tf
terraform {
  required_version = ">= 1.7"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

# variables.tf
variable "environment" {
  description = "Target deployment environment"
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be dev, staging, or prod."
  }
}

# locals.tf
locals {
  common_tags = {
    Environment = var.environment
    ManagedBy   = "Terraform"
  }
}

# main.tf
resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_hostnames = true

  tags = merge(local.common_tags, {
    Name = "${var.project_name}-${var.environment}-vpc"
  })
}

# outputs.tf
output "vpc_id" {
  description = "ID of the created VPC"
  value       = aws_vpc.main.id
}

代码格式

缩进与对齐

• 每个嵌套层级使用 两个空格（不要使用制表符）
• 对齐连续参数的等号

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
  subnet_id     = "subnet-12345678"

  tags = {
    Name        = "web-server"
    Environment = "production"
  }
}

块组织

参数放在块之前，元参数优先：

resource "aws_instance" "example" {
  # Meta-arguments
  count = 3

  # Arguments
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"

  # Blocks
  root_block_device {
    volume_size = 20
  }

  # Lifecycle last
  lifecycle {
    create_before_destroy = true
  }
}

命名约定

• 所有名称使用 小写字母和下划线
• 使用 描述性名词，不包含资源类型
• 名称应具体且有意义

# Bad
resource "aws_instance" "webAPI-aws-instance" {}
variable "name" {}

# Good
resource "aws_instance" "web_api" {}
variable "application_name" {}

变量

每个变量都必须包含 type 和 description：

variable "instance_type" {
  description = "EC2 instance type for the web server"
  type        = string
  default     = "t2.micro"

  validation {
    condition     = contains(["t2.micro", "t2.small", "t2.medium"], var.instance_type)
    error_message = "Instance type must be t2.micro, t2.small, or t2.medium."
  }
}

variable "database_password" {
  description = "Password for the database admin user"
  type        = string
  sensitive   = true
}

输出

每个输出都必须包含 description：

output "instance_id" {
  description = "ID of the EC2 instance"
  value       = aws_instance.web.id
}

output "database_password" {
  description = "Database administrator password"
  value       = aws_db_instance.main.password
  sensitive   = true
}

动态创建资源

优先使用 for_each，而非 count

# Bad - count for multiple resources
resource "aws_instance" "web" {
  count = var.instance_count
  tags  = { Name = "web-${count.index}" }
}

# Good - for_each with named instances
variable "instance_names" {
  type    = set(string)
  default = ["web-1", "web-2", "web-3"]
}

resource "aws_instance" "web" {
  for_each = var.instance_names
  tags     = { Name = each.key }
}

使用 count 进行条件创建

resource "aws_cloudwatch_metric_alarm" "cpu" {
  count = var.enable_monitoring ? 1 : 0

  alarm_name = "high-cpu-usage"
  threshold  = 80
}

安全最佳实践

生成代码时，应用安全加固措施：

• 默认启用静态加密
• 在适用情况下配置私有网络
• 对安全组应用最小权限原则
• 启用日志记录和监控
• 切勿将凭据或机密硬编码
• 将敏感输出标记为 sensitive = true

示例：安全的 S3 存储桶

resource "aws_s3_bucket" "data" {
  bucket = "${var.project}-${var.environment}-data"
  tags   = local.common_tags
}

resource "aws_s3_bucket_versioning" "data" {
  bucket = aws_s3_bucket.data.id

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "data" {
  bucket = aws_s3_bucket.data.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm     = "aws:kms"
      kms_master_key_id = aws_kms_key.s3.arn
    }
  }
}

resource "aws_s3_bucket_public_access_block" "data" {
  bucket = aws_s3_bucket.data.id

  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

版本固定

terraform {
  required_version = ">= 1.7"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Allow minor updates
    }
  }
}

版本约束运算符：

• = 1.0.0 - 精确版本
• >= 1.0.0 - 大于或等于
• ~> 1.0 - 允许最右侧的版本组件递增
• >= 1.0, < 2.0 - 版本范围

提供商配置

provider "aws" {
  region = "us-west-2"

  default_tags {
    tags = {
      ManagedBy = "Terraform"
      Project   = var.project_name
    }
  }
}

# Aliased provider for multi-region
provider "aws" {
  alias  = "east"
  region = "us-east-1"
}

版本控制

切勿提交：

• terraform.tfstate、terraform.tfstate.backup
• .terraform/ 目录
• *.tfplan
• 包含敏感数据的 .tfvars 文件

始终提交：

• 所有 .tf 配置文件
• .terraform.lock.hcl（依赖锁定文件）

验证工具

提交前运行：

terraform fmt -recursive
terraform validate

其他工具：

• tflint - 代码检查和最佳实践
• checkov / tfsec - 安全扫描

代码审查清单

• 使用 terraform fmt 格式化代码
• 使用 terraform validate 验证配置
• 按照标准结构组织文件
• 所有变量都包含类型和描述
• 所有输出都包含描述
• 资源名称使用带下划线的描述性名词
• 明确固定版本约束
• 将敏感值标记为 sensitive = true
• 没有硬编码的凭据或机密
• 已应用安全最佳实践

---

依据：HashiCorp Terraform 风格指南