terraform-style-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Terraform Style Guide

Terraform 风格指南

Generate and maintain Terraform code following HashiCorp's official style conventions and best practices.

Reference: HashiCorp Terraform Style Guide

遵循HashiCorp官方风格规范和最佳实践生成并维护Terraform代码。

参考文档： HashiCorp Terraform 风格指南

Code Generation Strategy

代码生成策略

When generating Terraform code:

Start with provider configuration and version constraints
Create data sources before dependent resources
Build resources in dependency order
Add outputs for key resource attributes
Use variables for all configurable values

生成Terraform代码时：

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

File Organization

文件组织结构

File	Purpose
`terraform.tf`	Terraform and provider version requirements
`providers.tf`	Provider configurations
`main.tf`	Primary resources and data sources
`variables.tf`	Input variable declarations (alphabetical)
`outputs.tf`	Output value declarations (alphabetical)
`locals.tf`	Local value declarations

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

Example Structure

示例结构

hcl

undefined

hcl

undefined

terraform.tf

terraform { required_version = ">= 1.7"

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

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." } }

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" }) }

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 }

undefined

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

undefined

Code Formatting

代码格式规范

Indentation and Alignment

缩进与对齐

Use two spaces per nesting level (no tabs)
Align equals signs for consecutive arguments

hcl

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

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

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

hcl

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

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

Block Organization

块组织方式

Arguments precede blocks, with meta-arguments first:

hcl

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
  }
}

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

hcl

resource "aws_instance" "example" {
  # 元参数
  count = 3

  # 参数
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"

  # 块
  root_block_device {
    volume_size = 20
  }

  # 生命周期块放在最后
  lifecycle {
    create_before_destroy = true
  }
}

Naming Conventions

命名规范

Use lowercase with underscores for all names
Use descriptive nouns excluding the resource type
Be specific and meaningful

hcl

undefined

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

hcl

undefined

Bad

不规范

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

Good

规范

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

undefined

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

undefined

Variables

变量规范

Every variable must include

type

and

description

hcl

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
}

每个变量必须包含

type

和

description

：

hcl

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
}

Outputs

输出规范

Every output must include

description

hcl

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
}

每个输出必须包含

description

：

hcl

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
}

Dynamic Resource Creation

动态资源创建

Prefer for_each over count

优先使用for_each而非count

hcl

undefined

hcl

undefined

Bad - count for multiple resources

不规范 - 使用count创建多资源

resource "aws_instance" "web" { count = var.instance_count tags = { Name = "web-${count.index}" } }

Good - for_each with named instances

规范 - 使用for_each创建命名实例

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 } }

undefined

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 } }

undefined

count for Conditional Creation

使用count实现条件式创建

hcl

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

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

hcl

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

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

Security Best Practices

安全最佳实践

When generating code, apply security hardening:

Enable encryption at rest by default
Configure private networking where applicable
Apply principle of least privilege for security groups
Enable logging and monitoring
Never hardcode credentials or secrets
Mark sensitive outputs with
```
sensitive = true
```

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

默认启用静态加密
适用时配置私有网络
为安全组应用最小权限原则
启用日志与监控
绝不硬编码凭证或密钥
为敏感输出标记
```
sensitive = true
```

Example: Secure S3 Bucket

示例：安全的S3存储桶

hcl

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
}

hcl

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
}

Version Pinning

版本固定

hcl

terraform {
  required_version = ">= 1.7"

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

Version constraint operators:

```
= 1.0.0
```
- Exact version
```
>= 1.0.0
```
- Greater than or equal
```
~> 1.0
```
- Allow rightmost component to increment
```
>= 1.0, < 2.0
```
- Version range

hcl

terraform {
  required_version = ">= 1.7"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # 允许小版本更新
    }
  }
}

版本约束操作符：

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

Provider Configuration

提供商配置

hcl

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

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

hcl

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" }

undefined

provider "aws" { alias = "east" region = "us-east-1" }

undefined

Version Control

版本控制

Never commit:

terraform.tfstate

terraform.tfstate.backup

```
.terraform/
```
directory
```
*.tfplan
```
```
.tfvars
```
files with sensitive data

Always commit:

All
```
.tf
```
configuration files
```
.terraform.lock.hcl
```
(dependency lock file)

绝不提交：

terraform.tfstate

、

terraform.tfstate.backup

```
.terraform/
```
目录
```
*.tfplan
```
包含敏感数据的
```
.tfvars
```
文件

必须提交：

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

Validation Tools

验证工具

Run before committing:

bash

terraform fmt -recursive
terraform validate

Additional tools:

```
tflint
```
- Linting and best practices
```
checkov
```
/
```
tfsec
```
- Security scanning

提交前运行：

bash

terraform fmt -recursive
terraform validate

额外工具：

```
tflint
```
- 代码检查与最佳实践验证
```
checkov
```
/
```
tfsec
```
- 安全扫描

Code Review Checklist

代码审查检查清单

Code formatted with
```
terraform fmt
```
Configuration validated with
```
terraform validate
```
Files organized according to standard structure
All variables have type and description
All outputs have descriptions
Resource names use descriptive nouns with underscores
Version constraints pinned explicitly
Sensitive values marked with
```
sensitive = true
```
No hardcoded credentials or secrets
Security best practices applied

Based on: HashiCorp Terraform Style Guide

代码已使用
```
terraform fmt
```
格式化
配置已通过
```
terraform validate
```
验证
文件组织结构符合标准规范
所有变量均包含类型和描述
所有输出均包含描述
资源名称使用带下划线的描述性名词
版本约束已明确固定
敏感值已标记
```
sensitive = true
```
无硬编码凭证或密钥
已应用安全最佳实践

基于：HashiCorp Terraform 风格指南