1.4.8.1. 变更管理

在大规模 Terraform 模块治理的过程中，变更管理是一个不可或缺的环节。由于治理的模块是开源项目，不仅会接收公司内部开发者的提交，也有可能吸引外部贡献者的代码改进。这为模块的演进带来了持续的活力，但同时也带来了挑战：如何确保每一个变更都是高质量、安全、可控的。

本节将详细介绍模块的贡献流程，以及维护者如何高效且稳健地管理变更。

1.4.8.1.1. 规范贡献流程的重要性

Terraform 模块直接操作云端基础设施，出错的后果可能是资源创建失败，甚至意外修改、破坏已有的生产环境资源。因此，每一次代码变更都需要经过严格的质量和安全把关。

建立规范的贡献流程，不仅保障了模块本身的安全与稳定，也为外部贡献者提供了清晰的路径，避免在未对齐预期的情况下投入不必要的精力。

以下我们以 Azure Verified Module 的变更规范为例进行讲解：

1.4.8.1.2. 提前沟通

在提交任何新功能、修复或优化前，贡献者应先创建一个 Issue，详细描述问题或改进建议。这有助于模块维护团队提前评估可行性，并确保拟议的变更符合模块的发展方向。

1.4.8.1.3. 分支与开发

获得认可后，贡献者应基于模块仓库的 main 分支创建新的工作分支。推荐采用清晰的命名规范，例如：

fix/variable-docs
feature/add-network-acl

这样可以使维护者在 PR 列表中快速识别变更内容。

1.4.8.1.4. 遵循开发规范

开发过程中，贡献者需确保：

  • 所有改动符合 HashiCorp 官方和 Azure Verified Modules 的模块规范。
  • 在提交代码前，本地运行 pre-commit 钩子，这会自动检查代码格式、生成/更新文档、并执行基本的静态分析，确保改动满足基础要求。
  • AVM 提供了与 make pr-check 命令等价的检查流水线，可以在持续集成流水线所使用的容器镜像中执行与流水线一致的，无需凭据的检查，通过 pr-check 检查的 Pull Request 也就确定可以通过持续集成流水线的前置检查。可以通过 ./avm pre-commit 和 ./avm pr-check 在容器中执行命令。

1.4.8.1.5. 提交 PR

开发完成后，贡献者应提交 Pull Request。PR 内容应包括：

  • 清晰的标题与详细描述，说明改动内容、目的及潜在影响。
  • 完成贡献模板中的各项检查清单。

提示：详尽的 PR 描述能够帮助维护者快速理解上下文，显著提高审查效率。

1.4.8.1.6. 自动化检查

提交 PR 后，流水线会自动触发一系列检查，包括：

  • 代码格式检查：确保遵循模块的格式与风格规范。
  • 基本功能验证：通过 terraform validate 检查模块是否存在语法错误。
  • 代码静态分析检查： 通过 TFLint 对代码进行静态语法分析，阻止代码规范中明令禁止的反模式，检查模块所声明的标准接口输入变量的类型与变量描述是否与标准一致，检查对 Provider 的版本限制、所使用的外部模块来源是否符合标准规范。
  • 文档检查： 确保所有文档与当前 Terraform 模块的实际情况一致。
  • 策略规则检查： 确保 examples 下所有的示例代码都遵循了 AVM 规范所规定的各条规则。我们将在后续的规则章节中进行详细说明。
  • 示例计划测试：确保 examples/ 下的示例代码可以正常执行 terraform apply，并且反复 apply 不会引发配置漂移(Configuration Drift)，最后确认示例代码创建的基础设施可以被正确地 terraform destroy 掉。我们将在后续有关测试的章节中对此进行更详细的说明。

如有检查失败，贡献者应参考流水线输出的提示修正后重新提交。

1.4.8.1.7. 维护者审查

每一个 PR 都必须经过模块维护者的人工审查，主要审查点包括：

  • 改动是否符合模块的长期发展规划。
  • 是否存在潜在的安全风险。
  • 输入输出变量及结构设计是否合理，类型与描述是否与 Provider 一致。
  • 文档与示例是否完善、易懂。

如有需要，维护者会提出修改意见，贡献者应积极响应并进行改进。

1.4.8.1.8. 合并策略

审查通过后，模块维护者会采取以下合并策略：

  • 创建 release 分支，从 main 分支创建一个新的 release/<描述> 分支。
  • 调整 PR 的目标分支为 release 分支。
  • 将 PR 合并到 release 分支。
  • 发起从 release 分支到 main 分支的新合并 PR，以触发端到端测试。
  • 测试通过后，正式合并到 main 分支。

这种流程确保 main 分支始终保持高稳定性，避免直接合并潜在不稳定的改动。

1.4.8.1.9. 处理失败情况

如果端到端测试未通过，模块维护者会：

  • 分析失败原因；
  • 根据具体情况，决定是退回贡献者修改，还是由维护团队直接修复问题。

安全始终是第一要务。一旦发现安全风险，维护者有权关闭 PR，并在必要时上报安全团队。涉及安全问题以及攻击尝试，必须交由专业团队进行后续处理。

1.4.8.1.10. 小结

变更管理不仅仅是代码审查的过程，更是维护模块质量与安全的核心环节。通过建立清晰、规范的贡献流程，既能为外部贡献者提供良好的体验，也能确保模块持续、高质量地发展。

results matching ""

    No results matching ""