Back to Details

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:
  1. Format: 
    terraform fmt
    (automated style alignment).
  2. Validate: 
    terraform validate
    (syntactic and structural check).
  3. Lint: Use 
    tflint
    for deep linting and provider-specific best practices.
  4. Security: Run 
    tfsec
    or 
    checkov
    to identify security vulnerabilities.
  5. Test: Execute automated infrastructure tests using Terratest to verify behavioral correctness.
在最终确定变更前，需执行以下步骤：
  1. 格式化：执行
    terraform fmt
    （自动对齐代码风格）。
  2. 验证：执行
    terraform validate
    （语法与结构检查）。
  3. 代码检查：使用
    tflint
    进行深度代码检查，遵循提供商特定的最佳实践。
  4. 安全扫描：运行
    tfsec
    或
    checkov
    识别安全漏洞。
  5. 测试：使用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

工作流：审查现有代码

  1. Inventory: Identify all 
    .tf
    files and their dependencies.
  2. Gap Analysis: Compare the current layout and code against these best practices.
  3. Detection: Look for anti-patterns:
    • Missing 
      description
      on variables/outputs.
    • Hardcoded secrets or sensitive data (recommend 
      vault
      or 
      aws_secretsmanager
      ).
    • Monolithic files (> 300 lines).
  4. Refactor Plan: Propose a step-by-step plan to modularize or fix the identified issues.
  1. 盘点：识别所有
    .tf
    文件及其依赖关系。
  2. 差距分析：将当前的文件布局与代码和本最佳实践进行对比。
  3. 问题检测：查找反模式问题：
    • 变量/输出缺少
      description
      。
    • 硬编码密钥或敏感数据（推荐使用
      vault
      或
      aws_secretsmanager
      ）。
    • 单体文件（超过300行）。
  4. 重构计划：提出分步计划，对识别出的问题进行模块化重构或修复。

Workflow: Authoring New Resources

工作流：编写新资源

  1. Scaffold: Create the standard file set (
    main.tf
    , 
    variables.tf
    , etc.).
  2. Define: Declare variables with clear types and descriptions before writing resource blocks.
  3. Document: Use 
    terraform-docs
    to generate READMEs for modules.
  1. 搭建框架：创建标准文件集（
    main.tf
    、
    variables.tf
    等）。
  2. 定义变量：在编写资源块前，先声明具有清晰类型与描述的变量。
  3. 文档生成：使用
    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
文件，其包含的说明与规范将优先于本通用指南。请始终先检查该文件。