terraform-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Terraform Best Practices

Terraform最佳实践

This skill ensures that Terraform configurations are modular, secure, and maintainable by following established industry standards and organizational patterns.

本技能通过遵循既定的行业标准与组织规范，确保Terraform配置具备模块化、安全性与可维护性。

When to Use

适用场景

Reviewing existing Terraform code for anti-patterns and technical debt.
Refactoring monolithic
```
.tf
```
files into reusable, versioned modules.
Setting up new infrastructure projects to ensure a consistent directory structure from the start.
Validating security, naming conventions, and resource tagging before committing changes.

审查现有Terraform代码，识别反模式与技术债务。
将单体
```
.tf
```
文件重构为可复用、带版本管理的模块。
搭建新的基础设施项目，从一开始就确保目录结构的一致性。
在提交变更前，验证安全性、命名规范与资源标签设置。

Core Guidelines

核心指南

1. Standard Directory Structure

1. 标准目录结构

Every module or root configuration MUST maintain a consistent file layout:

```
main.tf
```
: Primary resource definitions.
```
variables.tf
```
: Input variable declarations (always include
```
description
```
and
```
type
```
).
```
outputs.tf
```
: Output value definitions (always include
```
description
```
).
```
versions.tf
```
: Minimum required Terraform and provider version constraints.
```
providers.tf
```
: Provider configurations (restrict this to root modules only).

所有模块或根配置必须保持一致的文件布局：

```
main.tf
```
：核心资源定义文件。
```
variables.tf
```
：输入变量声明文件（必须包含
```
description
```
与
```
type
```
）。
```
outputs.tf
```
：输出值定义文件（必须包含
```
description
```
）。
```
versions.tf
```
：Terraform及提供商的最低版本约束文件。
```
providers.tf
```
：提供商配置文件（仅限根模块使用）。

2. The Module Pattern

2. 模块模式

Encapsulate: Move complex or repetitive logic into a local
```
modules/
```
directory or a remote registry.
Root Simplicity: Root modules should primarily serve as an orchestration layer, calling sub-modules.
Decouple: Avoid hardcoding environment-specific values; pass them as variables.

封装：将复杂或重复的逻辑移至本地
```
modules/
```
目录或远程注册表中。
根模块简洁性：根模块应主要作为编排层，负责调用子模块。
解耦：避免硬编码环境特定值，应通过变量传递。

3. State Management

3. 状态管理

Remote Backends: Always use a remote backend (e.g., S3 + DynamoDB for AWS, GCS for GCP) for team collaboration.
State Locking: Ensure state locking is enabled to prevent concurrent modifications and state corruption.

远程后端：团队协作时必须使用远程后端（例如AWS的S3 + DynamoDB，GCP的GCS）。
状态锁定：必须启用状态锁定，以防止并发修改导致状态损坏。

4. Semantic Versioning (SemVer)

4. 语义化版本控制（SemVer）

All separated or shared modules MUST follow semantic versioning (

MAJOR.MINOR.PATCH

) based on the interface (variables and outputs):

MAJOR (Breaking): Incremented for breaking changes to the module's interface (e.g., removing a variable, changing a variable type, or changing the resource graph in a way that requires recreation).
MINOR (Feature): Incremented for new features that are backwards-compatible (e.g., adding a new optional variable or a new output).
PATCH (Fix): Incremented for backwards-compatible bug fixes or internal refactors that do not change the interface.
Requirement: Every version bump MUST be accompanied by successful Terratest execution.

所有独立或共享模块必须基于接口（变量与输出）遵循语义化版本控制规范（

MAJOR.MINOR.PATCH

）：

MAJOR（破坏性变更）：当模块接口发生破坏性变更时递增（例如移除变量、更改变量类型，或修改资源图谱导致需要重新创建资源）。
MINOR（功能新增）：当添加向后兼容的新功能时递增（例如新增可选变量或新的输出项）。
PATCH（问题修复）：当进行向后兼容的bug修复或不改变接口的内部重构时递增。
要求：每次版本升级必须伴随Terratest测试的成功执行。

5. Naming & Tagging Conventions

5. 命名与标签规范

Naming: Use
```
snake_case
```
for all resource, variable, and output names. Avoid repeating the resource type in the name (e.g., use
```
resource "aws_instance" "web" {}
```
instead of
```
web_instance
```
).
Standard Tagging: Taggable resources MUST include a standard
```
tags
```
block:
- ```
Owner
```
  : The team or individual responsible for the resource.
- ```
Environment
```
  : Deployment stage (e.g.,
```
dev
```
  ,
```
staging
```
  ,
```
prod
```
  ).
- ```
Project
```
  : Name of the project or application.
- ```
ManagedBy
```
  : Always set to
```
terraform
```
  .

命名：所有资源、变量与输出名称必须使用
```
snake_case
```
命名法。避免在名称中重复资源类型（例如使用
```
resource "aws_instance" "web" {}
```
而非
```
web_instance
```
）。
标准标签：所有可打标签的资源必须包含标准的
```
tags
```
块：
- ```
Owner
```
  ：负责该资源的团队或个人。
- ```
Environment
```
  ：部署阶段（例如
```
dev
```
  、
```
staging
```
  、
```
prod
```
  ）。
- ```
Project
```
  ：项目或应用的名称。
- ```
ManagedBy
```
  ：必须设置为
```
terraform
```
  。

5. Validation & Tooling

5. 验证与工具

Before finalizing changes, execute the following sequence:

Format:
```
terraform fmt
```
(automated style alignment).
Validate:
```
terraform validate
```
(syntactic and structural check).
Lint: Use
```
tflint
```
for deep linting and provider-specific best practices.
Security: Run
```
tfsec
```
or
```
checkov
```
to identify security vulnerabilities.
Test: Execute automated infrastructure tests using Terratest to verify behavioral correctness.

在最终确定变更前，需执行以下步骤：

格式化：执行
```
terraform fmt
```
（自动对齐代码风格）。
验证：执行
```
terraform validate
```
（语法与结构检查）。
代码检查：使用
```
tflint
```
进行深度代码检查，遵循提供商特定的最佳实践。
安全扫描：运行
```
tfsec
```
或
```
checkov
```
识别安全漏洞。
测试：使用Terratest执行自动化基础设施测试，验证行为正确性。

Infrastructure Testing (Terratest)

基础设施测试（Terratest）

Every module MUST include automated tests in a

tests/

directory:

Language: Use Go with the
```
gruntwork-io/terratest
```
library.
Scope:
- Unit Tests: Deploy a minimal version of the module and verify outputs/resource attributes.
- Integration Tests: Verify the module works correctly when combined with other infrastructure (e.g., VPC + DB).
Cleanup: Always use
```
defer terraform.Destroy(t, terraformOptions)
```
to ensure resources are cleaned up after tests.

每个模块必须在

tests/

目录中包含自动化测试：

编程语言：使用Go语言结合
```
gruntwork-io/terratest
```
库。
测试范围：
- 单元测试：部署模块的最小版本，验证输出与资源属性。
- 集成测试：验证模块与其他基础设施（例如VPC + 数据库）结合时的正确性。
资源清理：必须使用
```
defer terraform.Destroy(t, terraformOptions)
```
确保测试后资源被清理。

Workflow: Reviewing Existing Code

工作流：审查现有代码

Inventory: Identify all
```
.tf
```
files and their dependencies.
Gap Analysis: Compare the current layout and code against these best practices.
Detection: Look for anti-patterns:
- Missing
```
description
```
  on variables/outputs.
- Hardcoded secrets or sensitive data (recommend
```
vault
```
  or
```
aws_secretsmanager
```
  ).
- Monolithic files (> 300 lines).
Refactor Plan: Propose a step-by-step plan to modularize or fix the identified issues.

盘点：识别所有
```
.tf
```
文件及其依赖关系。
差距分析：将当前的文件布局与代码和本最佳实践进行对比。
问题检测：查找反模式问题：
- 变量/输出缺少
```
description
```
  。
- 硬编码密钥或敏感数据（推荐使用
```
vault
```
  或
```
aws_secretsmanager
```
  ）。
- 单体文件（超过300行）。
重构计划：提出分步计划，对识别出的问题进行模块化重构或修复。

Workflow: Authoring New Resources

工作流：编写新资源

Scaffold: Create the standard file set (
```
main.tf
```
,
```
variables.tf
```
, etc.).
Define: Declare variables with clear types and descriptions before writing resource blocks.
Document: Use
```
terraform-docs
```
to generate READMEs for modules.

搭建框架：创建标准文件集（
```
main.tf
```
、
```
variables.tf
```
等）。
定义变量：在编写资源块前，先声明具有清晰类型与描述的变量。
文档生成：使用
```
terraform-docs
```
为模块生成README文档。

Overriding Standards (

TERRAFORM.md

)

标准覆盖（

TERRAFORM.md

）

If a

TERRAFORM.md

file exists in the workspace root, its instructions and conventions take absolute precedence over these general guidelines. Always check for this file first.

如果工作区根目录存在

TERRAFORM.md

文件，其包含的说明与规范将优先于本通用指南。请始终先检查该文件。

terraform-best-practices

Original

Translation

Terraform Best Practices

Terraform最佳实践

When to Use

适用场景

Core Guidelines

核心指南

1. Standard Directory Structure

1. 标准目录结构

2. The Module Pattern

2. 模块模式

3. State Management

3. 状态管理

4. Semantic Versioning (SemVer)

4. 语义化版本控制（SemVer）

5. Naming & Tagging Conventions

5. 命名与标签规范

5. Validation & Tooling

5. 验证与工具

Infrastructure Testing (Terratest)

基础设施测试（Terratest）

Workflow: Reviewing Existing Code

工作流：审查现有代码

Workflow: Authoring New Resources

工作流：编写新资源

Overriding Standards (TERRAFORM.md)

标准覆盖（TERRAFORM.md）

terraform-best-practices

Original

Translation

Terraform Best Practices

Terraform最佳实践

When to Use

适用场景

Core Guidelines

核心指南

1. Standard Directory Structure

1. 标准目录结构

2. The Module Pattern

2. 模块模式

3. State Management

3. 状态管理

4. Semantic Versioning (SemVer)

4. 语义化版本控制（SemVer）

5. Naming & Tagging Conventions

5. 命名与标签规范

5. Validation & Tooling

5. 验证与工具

Infrastructure Testing (Terratest)

基础设施测试（Terratest）

Workflow: Reviewing Existing Code

工作流：审查现有代码

Workflow: Authoring New Resources

工作流：编写新资源

Overriding Standards (TERRAFORM.md)

标准覆盖（TERRAFORM.md）

Overriding Standards (
`TERRAFORM.md`
)

标准覆盖（
`TERRAFORM.md`
）

Overriding Standards (
`TERRAFORM.md`
)

标准覆盖（
`TERRAFORM.md`
）