awesome-copilot 实战为 Azure 编写现代 Terraform 代码的 Copilot 指令指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilotGitHub Copilot 的指令Instructions文件是约束代码生成行为的核心机制。在 awesome-copilot 仓库中instructions/generate-modern-terraform-code-for-azure.instructions.md 就是一份专门面向 Azure Terraform 代码生成的指令文件它通过 frontmatter 声明适用范围并在正文中给出 10 条可执行的质量守则从版本锁定、代码组织、模块封装到 Provider 选型、幂等性、状态管理与验证测试一应俱全。读完本文你将理解这份指令的完整脉络掌握在 Copilot 中落地现代 Azure Terraform 代码的整套实操标准并知晓它与仓库内 terraform.instructions.md、terraform-azure.instructions.md、azure-verified-modules-terraform.instructions.md 三份配套指令的分工关系。一、先读懂这份指令文件本身1.1 文件的定位与生效机制与仓库内所有 instructions 文件一致这份文件通过 YAML frontmatter 声明元数据--- description: Guidelines for generating modern Terraform code for Azure applyTo: **/*.tf ---description向模型描述该指令的用途帮助 Copilot 在合适场景自动加载applyTo声明生效的文件范围**/*.tf意味着当用户打开或编辑任意层级的.tf文件时该指令都会作为生成代码的上下文约束。换言之这是一份文件类型级的规则注入只要 Copilot 在处理 Terraform 配置文件这 10 条准则就会被激活。仓库中另有 docs/README.instructions.md 系统介绍 instructions 的编写与使用方式可作为机制层面的延伸阅读。1.2 它与仓库内其他 Terraform 指令的关系awesome-copilot 围绕 Terraform 提供了多份指令分工各不相同阅读时可互为参照指令文件侧重点generate-modern-terraform-code-for-azure.instructions.md本文主体生成现代、高质量 Azure Terraform 代码的 10 条直接准则terraform.instructions.md通用 Terraform 约定安全、模块化、可维护性、风格格式化、文档、测试terraform-azure.instructions.mdAzure 场景最佳实践AVM 应用、反模式规避、secrets、文件夹结构、成本管理azure-verified-modules-terraform.instructions.mdAzure Verified ModulesAVM的发现、使用、版本管理与贡献规范下文各节将首先完整继承主体文件中的每一条准则再用上述配套指令与仓库内可核验的约定进行纵深扩充使每一条都具备可直接落地的操作性。二、使用最新的 Terraform 与 Azure Providers原准则始终瞄准最新稳定版 Terraform 与 Azure providers在代码中显式声明所需版本以强制执行保持 provider 版本更新以获取新功能与修复。这条准则在实际代码中的落点是required_providers块与required_version。以 azurerm provider 为例标准写法如下terraform { required_version 1.9 required_providers { azurerm { source hashicorp/azurerm version ~ 4.0 } } }required_version声明 HCL 所需的最低 Terraform 版本防止旧版二进制执行新语法如ephemeral资源、改进后的for_each语义provider 的version使用悲观约束pessimistic constraint~ 4.0锁定大版本同时允许向后兼容的小版本升级。在 terraform-azure.instructions.md 的Follow recommended Terraform practices一节中这一条被量化为 AVM 规范TFFR3始终以最新稳定版 Terraform 与 Azure provider 为目标在代码中指定版本并保持更新。与之配套的 azure-verified-modules-terraform.instructions.md 在Version Management一节进一步给出了版本检查与固定策略悲观约束用于日常开发version ~ 1.0生产环境建议固定精确版本version 1.2.3任何升级前都应先阅读 changelog。实操建议在.tf文件中把版本声明视为合同——不仅约束本地 CLI也约束 CI 流水线中的 Terraform 版本从源头消除本地能跑、CI 报错的环境漂移。三、清晰组织代码文件分工与格式化原准则用逻辑清晰的文件切分 Terraform 配置——main.tf放资源、variables.tf放输入、outputs.tf放输出遵循一致的命名与格式化terraform fmt。这是 Terraform 项目最基础的工程化骨架terraform-azure.instructions.md 在此基础上做了两处重要扩充文件分工更细增加terraform.tfprovider 配置与locals.tf本地值/复杂表达式文件拆分规则当main.tf或variables.tf过大时按资源类型或职能拆分如main.networking.tf、main.storage.tf并把对应变量同步拆到variables.networking.tf、variables.storage.tf。一个符合规范的根模块文件布局为my-azure-app/ ├── main.tf # 核心资源 ├── variables.tf # 输入变量 ├── outputs.tf # 输出 ├── terraform.tf # provider 配置与版本约束 ├── locals.tf # 本地值 └── environments/ # 环境差异配置 ├── dev.tfvars ├── test.tfvars └── prod.tfvars格式与命名层面有两点共识变量与模块名统一使用snake_casingsnake_case每次修改后执行terraform fmt统一缩进Terraform 风格指南约定每级 2 空格。terraform.instructions.md 还补充了更细的风格规则depends_on置于资源定义块最前、for_each/count紧随其后、lifecycle块置于资源定义末尾、同文件内对 providers/variables/data sources/resources/outputs 按字母序排列以提升导航效率。四、封装成模块复用而非复制原准则任何会在多个场景复用的资源组都应封装为模块——为模块定义自己的变量与输出通过引用模块而非复制代码促进复用与一致性。模块化的核心判断标准是复用价值单资源不建模块过度抽象真正相关的资源组才封装。这与 terraform.instructions.md 的模块化约定完全一致模块用于封装相关资源、避免配置重复、保持层级浅、避免模块间循环依赖。在 Azure 场景下更现代的模块化路线是优先使用 Azure Verified ModulesAVM。terraform-azure.instructions.md 明确要求任何重要资源只要存在对应 AVM 就应使用之因为 AVM 对齐 Well-Architected Framework、由微软维护、能显著减少自维护代码量若无对应 AVM则建议按 AVM 风格自建模块以便未来向社区上游贡献。AVM 模块的命名遵循Azure/avm-res-{service}-{resource}/azurerm资源模块、Azure/avm-ptn-{pattern}/azurerm模式模块、Azure/avm-utl-{utility}/azurerm工具模块三种形态使用方式见 azure-verified-modules-terraform.instructions.mdmodule resource_group { source Azure/avm-res-resources-resourcegroup/azurerm version ~ 0.1 enable_telemetry true location var.location name var.resource_group_name } module virtual_network { source Azure/avm-res-network-virtualnetwork/azurerm version ~ 0.1 enable_telemetry true location module.resource_group.location name var.vnet_name resource_group_name module.resource_group.name address_space [10.0.0.0/16] }注意这里模块间通过module.resource_group.location、module.resource_group.name引用输出形成隐式依赖——这正是模块拥有独立变量/输出接口的落地示范同时避免依赖 module 输出之外的隐式耦合。五、善用变量与输出参数化一切原准则用带类型与描述的变量参数化所有可配置值为可选变量提供默认值用输出暴露关键资源属性对敏感值做标记以保护机密。terraform-azure.instructions.md 将这一条展开为 AVM 对齐的编码标准对应 TFNFR17/18/20/22 等规范可归纳为五条硬性要求变量命名全部使用 snake_case描述性且与命名约定一致TFNFR4、TFNFR16类型与描述所有变量必须有显式type声明TFNFR18与完整descriptionTFNFR17集合类型尽量避免可空的默认值TFNFR20敏感变量正确标记sensitive避免显式写sensitive falseTFNFR22敏感默认值的处理要遵循正确姿势TFNFR23动态块与默认值可选嵌套对象用dynamic块TFNFR12默认值善用coalesce、try函数TFNFR13本地值locals.tf专用于本地值TFNFR31并为 locals 保持精确类型TFNFR33。一个参数化的变量声明范例variable environment { type string description Deployment environment (dev, test, prod) default dev validation { condition contains([dev, test, prod], var.environment) error_message Environment must be one of: dev, test, prod. } } variable owner { type string description Team or individual owning the resources }输出同样要按需而为只暴露其他配置真正需要的信息所有输出提供清晰描述包含机密的输出必须sensitive trueterraform-azure.instructions.md 给出了资源组与虚拟网络 ID 输出的标准范例。关于机密该指令还有一条更彻底的思路最好的机密是不需要存储的机密——优先用 Managed Identity 而非密码/密钥Terraform v1.11 支持ephemeralwrite-only参数时可避免把机密写入状态文件。六、Provider 选型azurerm 优先azapi 兜底原准则大多数场景使用azurermprovider——稳定性高、覆盖大多数 Azure 服务仅在需要最新 Azure 功能或azurerm尚未支持的资源时使用azapiprovider在代码注释中记录选型理由两者可混用但拿不准时优先azurerm。这条准则的实质是成熟优先的工程判断azurerm是多年打磨的稳定实现覆盖绝大多数生产需求azapi面向 ARM API 的通用 CRUD能第一时间吃到新服务/新特性但代价是需要手动维护资源 schema。两者混用的典型形态是主体资源用azurerm个别尝鲜资源用azapi并用注释说明每个azapi资源为何不能迁移回azurerm。在 terraform-azure.instructions.md 中这一选择被进一步与 AVM 结合绝大多数 Azure 服务都有对应的azurerm资源实现也通常存在官方 AVM 模块只有当服务过新、连 AVM 都未覆盖时才需要考虑azapi路线。实操建议每次引入azapi资源时务必在同一resource块上方写注释记录引入时间、对应 Azure 服务的 GA 状态、以及一旦 azurerm 支持即迁移的 TODO防止技术债沉淀。七、最小依赖保持技术栈精简原准则不引入项目范围之外的多余 providers 或模块若确需特殊 provider如random、tls或外部模块必须加注释说明并征得用户同意保持基础设施栈精简。这条准则在 terraform-azure.instructions.md 中被同样强调不得在未经用户确认的情况下引入额外 provider如random、tls或外部模块确需引入时用注释解释原因并保持栈精简。最小依赖的价值在于三重收敛风险面收敛每个 provider 都是一段需要更新、审计、可能有 CVE 的第三方代码计划面收敛额外 provider 会显著拉长terraform plan的 provider 加载与 schema 解析时间terraform.instructions.md 也提示无必要的数据源会拖慢 plan/apply认知成本收敛队友阅读代码时只需掌握少数 provider 的语义。一个典型取舍是randomprovider生成资源后缀、密码等场景确实常用但若能用timestamp()、uuid()或 AVM 内部已封装的随机逻辑替代就不必新增 provider。原则任何 provider 或模块的引入都要先解释、再批准、后引入。八、确保幂等性重复执行结果一致原准则配置可被反复 apply 且结果相同避免非幂等动作每次 apply 都运行的脚本、重复创建会冲突的资源通过多次terraform apply验证第二次运行为零变更用 lifecycle 设置或条件表达式优雅处理漂移与外部变更。幂等性是 IaC 的根基。需要警惕的高危模式包括使用local-exec/remote-execprovisioner 在每次 apply 时执行副作用脚本——除非绝对必要否则应避免terraform-azure.instructions.md 将其列为反模式依赖无确定性语义的随机生成值导致每次 plan 都提议变更资源参数依赖 API 返回的运行时值如默认生成的密码未捕获到状态。处理漂移的典型lifecycle设置resource azurerm_resource_group example { name var.resource_group_name location var.location lifecycle { # 允许外部如 Azure 门户手动操作修改 tags 时不被强制回滚 ignore_changes [tags] } }验证方法遵循 terraform-azure.instructions.md 的约定先测试再上生产——在非生产环境执行多次 apply第二次 plan 应显示 No changes。这与 terraform.instructions.md 的测试要求一脉相承用.tftest.hcl编写覆盖正反场景的测试且测试本身必须幂等、可重复执行。九、状态管理远程后端 锁 永不入库原准则使用远程后端如带状态锁的 Azure Storage安全存储状态启用团队协作绝不把状态文件提交到版本控制。落地形态是 Azure Storage 后端 blob 租约锁terraform { backend azurerm { resource_group_name tfstate-rg storage_account_name tfstateaccount container_name tfstate key my-azure-app.terraform.tfstate } }terraform-azure.instructions.md 在此基础上有更严格的纪律状态文件**/*.tfstate只允许只读操作一切变更必须通过 Terraform CLI 或 HCL 完成**/.terraform/**拉取的模块与 provider同样只读禁止手工改动启用静态加密与传输加密状态中可能包含明文属性必须配合敏感值不入状态ephemeral、sensitive、Managed Identity策略。团队协作层面状态锁可以防止多人并发 apply 造成的状态竞争而永不提交状态文件则通过.gitignore中的*.tfstate、*.tfstate.*规则落实。terraform.instructions.md 也强调用环境变量引用密钥服务的值如ARM_SUBSCRIPTION_ID使敏感值始终不落盘于状态文件——这与 Azure 场景下ARM_SUBSCRIPTION_ID由环境变量注入、而非硬编码进 provider 块的要求完全一致。十、文档与图表让基础设施可读原准则维护最新文档代码变更后同步更新 README.md新变量、新输出、使用说明考虑用terraform-docs自动化每次重大更新后同步架构图良好的文档与图表让全团队理解基础设施。文档维护有两个层次自动生成terraform-docs可从 HCL 生成变量/输出/资源清单terraform-docs markdown table . README.md即可产出结构化参考文档避免手工同步遗漏手工补充README 中保留使用说明、环境准备、后端配置、常见问题等叙述性内容与自动生成部分互补。terraform-azure.instructions.md 还强调代码变更即文档变更的节奏新增变量/输出时同步更新 README每次重大基础设施变更后更新架构图。这与 terraform.instructions.md 对注释的要求说明复杂配置与决策原因、避免冗余注释共同构成文档即代码文化。十一、验证与测试把质量门槛前置原准则apply 前先跑terraform validate并审查terraform plan输出尽早发现错误与意外变更考虑落地自动化检查CI 流水线、pre-commit hooks强制执行格式化、lint 与基础验证。推荐的本地工作流为# 1. 格式化 terraform fmt -recursive # 2. 语法与配置校验 terraform validate # 3. 静态风格检查可选但推荐 tflint # 4. 审查变更 terraform plan # 5. 确认后应用 terraform applyterraform-azure.instructions.md 对 plan 的使用有一条重要纪律运行terraform plan前必须先征求用户同意且订阅 ID 应从ARM_SUBSCRIPTION_ID环境变量读取绝不能硬编码进 provider 块。这一条也呼应了前文用户指令优先级最高、变更需确认的协作模式。在 AVM 参与的场景azure-verified-modules-terraform.instructions.md 给出了更完整的 CI 门槛任何 PR 提交前都必须执行# 格式化递归 terraform fmt -recursive # 语法校验 terraform validate # AVM 专属强制校验 ./avm pre-commit ./avm tflint ./avm pr-check这套组合拳将格式化 → 语法 → 风格 → AVM 规范四层门槛全部前置到本地与 CI避免 PR 校验阶段才发现问题导致返工。对普通非 AVM 贡献项目最小可行方案是 pre-commit 钩子中串联terraform fmt -check与terraform validate再在 CI 中加入tflint与安全扫描如 checkov/tfsec见 terraform.instructions.md 的安全审计建议。十二、组合使用从指令到生产级工作流将以上 10 条准则串联起来一份现代 Azure Terraform 代码的生成与交付闭环如下版本锁定required_versionrequired_providers固定 Terraform 与 azurerm 版本准则 1结构先行按 main/variables/outputs/terraform/locals 分文件超过规模即按资源类型拆分准则 2模块化优先引 AVM 官方模块无 AVM 时按 AVM 风格自建并设计好变量/输出接口准则 3参数化全部输入走带类型描述默认值的变量输出按需暴露机密标记sensitive准则 4Provider 取舍默认 azurerm仅新特性场景用 azapi 并注释理由准则 5依赖审查不新增无关 provider/模块确需引入先注释再确认准则 6幂等验证非生产环境连续 apply 两次第二次必须零变更准则 7状态治理Azure Storage 远程后端 状态锁 状态文件永不入库准则 8文档同步terraform-docs 自动生成 README 手工更新 架构图随变更维护准则 9质量门槛validate/plan 先于 applyCI 与 pre-commit 强制 fmt、lint 与校验准则 10。这 10 条准则并非孤立清单而是与仓库内 terraform.instructions.md通用约定、terraform-azure.instructions.mdAzure 最佳实践以及 azure-verified-modules-terraform.instructions.mdAVM 规范形成互补的完整体系。理解它们的分工就能在 Copilot 中按需组合出既现代、又可维护、且具备生产级质量保障的 Azure Terraform 代码。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 awesome-copilot 实战：为 Azure 编写现代 Terraform 代码的 Copilot 指令指南
awesome-copilot 实战为 Azure 编写现代 Terraform 代码的 Copilot 指令指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilotGitHub Copilot 的指令Instructions文件是约束代码生成行为的核心机制。在 awesome-copilot 仓库中instructions/generate-modern-terraform-code-for-azure.instructions.md 就是一份专门面向 Azure Terraform 代码生成的指令文件它通过 frontmatter 声明适用范围并在正文中给出 10 条可执行的质量守则从版本锁定、代码组织、模块封装到 Provider 选型、幂等性、状态管理与验证测试一应俱全。读完本文你将理解这份指令的完整脉络掌握在 Copilot 中落地现代 Azure Terraform 代码的整套实操标准并知晓它与仓库内 terraform.instructions.md、terraform-azure.instructions.md、azure-verified-modules-terraform.instructions.md 三份配套指令的分工关系。一、先读懂这份指令文件本身1.1 文件的定位与生效机制与仓库内所有 instructions 文件一致这份文件通过 YAML frontmatter 声明元数据--- description: Guidelines for generating modern Terraform code for Azure applyTo: **/*.tf ---description向模型描述该指令的用途帮助 Copilot 在合适场景自动加载applyTo声明生效的文件范围**/*.tf意味着当用户打开或编辑任意层级的.tf文件时该指令都会作为生成代码的上下文约束。换言之这是一份文件类型级的规则注入只要 Copilot 在处理 Terraform 配置文件这 10 条准则就会被激活。仓库中另有 docs/README.instructions.md 系统介绍 instructions 的编写与使用方式可作为机制层面的延伸阅读。1.2 它与仓库内其他 Terraform 指令的关系awesome-copilot 围绕 Terraform 提供了多份指令分工各不相同阅读时可互为参照指令文件侧重点generate-modern-terraform-code-for-azure.instructions.md本文主体生成现代、高质量 Azure Terraform 代码的 10 条直接准则terraform.instructions.md通用 Terraform 约定安全、模块化、可维护性、风格格式化、文档、测试terraform-azure.instructions.mdAzure 场景最佳实践AVM 应用、反模式规避、secrets、文件夹结构、成本管理azure-verified-modules-terraform.instructions.mdAzure Verified ModulesAVM的发现、使用、版本管理与贡献规范下文各节将首先完整继承主体文件中的每一条准则再用上述配套指令与仓库内可核验的约定进行纵深扩充使每一条都具备可直接落地的操作性。二、使用最新的 Terraform 与 Azure Providers原准则始终瞄准最新稳定版 Terraform 与 Azure providers在代码中显式声明所需版本以强制执行保持 provider 版本更新以获取新功能与修复。这条准则在实际代码中的落点是required_providers块与required_version。以 azurerm provider 为例标准写法如下terraform { required_version 1.9 required_providers { azurerm { source hashicorp/azurerm version ~ 4.0 } } }required_version声明 HCL 所需的最低 Terraform 版本防止旧版二进制执行新语法如ephemeral资源、改进后的for_each语义provider 的version使用悲观约束pessimistic constraint~ 4.0锁定大版本同时允许向后兼容的小版本升级。在 terraform-azure.instructions.md 的Follow recommended Terraform practices一节中这一条被量化为 AVM 规范TFFR3始终以最新稳定版 Terraform 与 Azure provider 为目标在代码中指定版本并保持更新。与之配套的 azure-verified-modules-terraform.instructions.md 在Version Management一节进一步给出了版本检查与固定策略悲观约束用于日常开发version ~ 1.0生产环境建议固定精确版本version 1.2.3任何升级前都应先阅读 changelog。实操建议在.tf文件中把版本声明视为合同——不仅约束本地 CLI也约束 CI 流水线中的 Terraform 版本从源头消除本地能跑、CI 报错的环境漂移。三、清晰组织代码文件分工与格式化原准则用逻辑清晰的文件切分 Terraform 配置——main.tf放资源、variables.tf放输入、outputs.tf放输出遵循一致的命名与格式化terraform fmt。这是 Terraform 项目最基础的工程化骨架terraform-azure.instructions.md 在此基础上做了两处重要扩充文件分工更细增加terraform.tfprovider 配置与locals.tf本地值/复杂表达式文件拆分规则当main.tf或variables.tf过大时按资源类型或职能拆分如main.networking.tf、main.storage.tf并把对应变量同步拆到variables.networking.tf、variables.storage.tf。一个符合规范的根模块文件布局为my-azure-app/ ├── main.tf # 核心资源 ├── variables.tf # 输入变量 ├── outputs.tf # 输出 ├── terraform.tf # provider 配置与版本约束 ├── locals.tf # 本地值 └── environments/ # 环境差异配置 ├── dev.tfvars ├── test.tfvars └── prod.tfvars格式与命名层面有两点共识变量与模块名统一使用snake_casingsnake_case每次修改后执行terraform fmt统一缩进Terraform 风格指南约定每级 2 空格。terraform.instructions.md 还补充了更细的风格规则depends_on置于资源定义块最前、for_each/count紧随其后、lifecycle块置于资源定义末尾、同文件内对 providers/variables/data sources/resources/outputs 按字母序排列以提升导航效率。四、封装成模块复用而非复制原准则任何会在多个场景复用的资源组都应封装为模块——为模块定义自己的变量与输出通过引用模块而非复制代码促进复用与一致性。模块化的核心判断标准是复用价值单资源不建模块过度抽象真正相关的资源组才封装。这与 terraform.instructions.md 的模块化约定完全一致模块用于封装相关资源、避免配置重复、保持层级浅、避免模块间循环依赖。在 Azure 场景下更现代的模块化路线是优先使用 Azure Verified ModulesAVM。terraform-azure.instructions.md 明确要求任何重要资源只要存在对应 AVM 就应使用之因为 AVM 对齐 Well-Architected Framework、由微软维护、能显著减少自维护代码量若无对应 AVM则建议按 AVM 风格自建模块以便未来向社区上游贡献。AVM 模块的命名遵循Azure/avm-res-{service}-{resource}/azurerm资源模块、Azure/avm-ptn-{pattern}/azurerm模式模块、Azure/avm-utl-{utility}/azurerm工具模块三种形态使用方式见 azure-verified-modules-terraform.instructions.mdmodule resource_group { source Azure/avm-res-resources-resourcegroup/azurerm version ~ 0.1 enable_telemetry true location var.location name var.resource_group_name } module virtual_network { source Azure/avm-res-network-virtualnetwork/azurerm version ~ 0.1 enable_telemetry true location module.resource_group.location name var.vnet_name resource_group_name module.resource_group.name address_space [10.0.0.0/16] }注意这里模块间通过module.resource_group.location、module.resource_group.name引用输出形成隐式依赖——这正是模块拥有独立变量/输出接口的落地示范同时避免依赖 module 输出之外的隐式耦合。五、善用变量与输出参数化一切原准则用带类型与描述的变量参数化所有可配置值为可选变量提供默认值用输出暴露关键资源属性对敏感值做标记以保护机密。terraform-azure.instructions.md 将这一条展开为 AVM 对齐的编码标准对应 TFNFR17/18/20/22 等规范可归纳为五条硬性要求变量命名全部使用 snake_case描述性且与命名约定一致TFNFR4、TFNFR16类型与描述所有变量必须有显式type声明TFNFR18与完整descriptionTFNFR17集合类型尽量避免可空的默认值TFNFR20敏感变量正确标记sensitive避免显式写sensitive falseTFNFR22敏感默认值的处理要遵循正确姿势TFNFR23动态块与默认值可选嵌套对象用dynamic块TFNFR12默认值善用coalesce、try函数TFNFR13本地值locals.tf专用于本地值TFNFR31并为 locals 保持精确类型TFNFR33。一个参数化的变量声明范例variable environment { type string description Deployment environment (dev, test, prod) default dev validation { condition contains([dev, test, prod], var.environment) error_message Environment must be one of: dev, test, prod. } } variable owner { type string description Team or individual owning the resources }输出同样要按需而为只暴露其他配置真正需要的信息所有输出提供清晰描述包含机密的输出必须sensitive trueterraform-azure.instructions.md 给出了资源组与虚拟网络 ID 输出的标准范例。关于机密该指令还有一条更彻底的思路最好的机密是不需要存储的机密——优先用 Managed Identity 而非密码/密钥Terraform v1.11 支持ephemeralwrite-only参数时可避免把机密写入状态文件。六、Provider 选型azurerm 优先azapi 兜底原准则大多数场景使用azurermprovider——稳定性高、覆盖大多数 Azure 服务仅在需要最新 Azure 功能或azurerm尚未支持的资源时使用azapiprovider在代码注释中记录选型理由两者可混用但拿不准时优先azurerm。这条准则的实质是成熟优先的工程判断azurerm是多年打磨的稳定实现覆盖绝大多数生产需求azapi面向 ARM API 的通用 CRUD能第一时间吃到新服务/新特性但代价是需要手动维护资源 schema。两者混用的典型形态是主体资源用azurerm个别尝鲜资源用azapi并用注释说明每个azapi资源为何不能迁移回azurerm。在 terraform-azure.instructions.md 中这一选择被进一步与 AVM 结合绝大多数 Azure 服务都有对应的azurerm资源实现也通常存在官方 AVM 模块只有当服务过新、连 AVM 都未覆盖时才需要考虑azapi路线。实操建议每次引入azapi资源时务必在同一resource块上方写注释记录引入时间、对应 Azure 服务的 GA 状态、以及一旦 azurerm 支持即迁移的 TODO防止技术债沉淀。七、最小依赖保持技术栈精简原准则不引入项目范围之外的多余 providers 或模块若确需特殊 provider如random、tls或外部模块必须加注释说明并征得用户同意保持基础设施栈精简。这条准则在 terraform-azure.instructions.md 中被同样强调不得在未经用户确认的情况下引入额外 provider如random、tls或外部模块确需引入时用注释解释原因并保持栈精简。最小依赖的价值在于三重收敛风险面收敛每个 provider 都是一段需要更新、审计、可能有 CVE 的第三方代码计划面收敛额外 provider 会显著拉长terraform plan的 provider 加载与 schema 解析时间terraform.instructions.md 也提示无必要的数据源会拖慢 plan/apply认知成本收敛队友阅读代码时只需掌握少数 provider 的语义。一个典型取舍是randomprovider生成资源后缀、密码等场景确实常用但若能用timestamp()、uuid()或 AVM 内部已封装的随机逻辑替代就不必新增 provider。原则任何 provider 或模块的引入都要先解释、再批准、后引入。八、确保幂等性重复执行结果一致原准则配置可被反复 apply 且结果相同避免非幂等动作每次 apply 都运行的脚本、重复创建会冲突的资源通过多次terraform apply验证第二次运行为零变更用 lifecycle 设置或条件表达式优雅处理漂移与外部变更。幂等性是 IaC 的根基。需要警惕的高危模式包括使用local-exec/remote-execprovisioner 在每次 apply 时执行副作用脚本——除非绝对必要否则应避免terraform-azure.instructions.md 将其列为反模式依赖无确定性语义的随机生成值导致每次 plan 都提议变更资源参数依赖 API 返回的运行时值如默认生成的密码未捕获到状态。处理漂移的典型lifecycle设置resource azurerm_resource_group example { name var.resource_group_name location var.location lifecycle { # 允许外部如 Azure 门户手动操作修改 tags 时不被强制回滚 ignore_changes [tags] } }验证方法遵循 terraform-azure.instructions.md 的约定先测试再上生产——在非生产环境执行多次 apply第二次 plan 应显示 No changes。这与 terraform.instructions.md 的测试要求一脉相承用.tftest.hcl编写覆盖正反场景的测试且测试本身必须幂等、可重复执行。九、状态管理远程后端 锁 永不入库原准则使用远程后端如带状态锁的 Azure Storage安全存储状态启用团队协作绝不把状态文件提交到版本控制。落地形态是 Azure Storage 后端 blob 租约锁terraform { backend azurerm { resource_group_name tfstate-rg storage_account_name tfstateaccount container_name tfstate key my-azure-app.terraform.tfstate } }terraform-azure.instructions.md 在此基础上有更严格的纪律状态文件**/*.tfstate只允许只读操作一切变更必须通过 Terraform CLI 或 HCL 完成**/.terraform/**拉取的模块与 provider同样只读禁止手工改动启用静态加密与传输加密状态中可能包含明文属性必须配合敏感值不入状态ephemeral、sensitive、Managed Identity策略。团队协作层面状态锁可以防止多人并发 apply 造成的状态竞争而永不提交状态文件则通过.gitignore中的*.tfstate、*.tfstate.*规则落实。terraform.instructions.md 也强调用环境变量引用密钥服务的值如ARM_SUBSCRIPTION_ID使敏感值始终不落盘于状态文件——这与 Azure 场景下ARM_SUBSCRIPTION_ID由环境变量注入、而非硬编码进 provider 块的要求完全一致。十、文档与图表让基础设施可读原准则维护最新文档代码变更后同步更新 README.md新变量、新输出、使用说明考虑用terraform-docs自动化每次重大更新后同步架构图良好的文档与图表让全团队理解基础设施。文档维护有两个层次自动生成terraform-docs可从 HCL 生成变量/输出/资源清单terraform-docs markdown table . README.md即可产出结构化参考文档避免手工同步遗漏手工补充README 中保留使用说明、环境准备、后端配置、常见问题等叙述性内容与自动生成部分互补。terraform-azure.instructions.md 还强调代码变更即文档变更的节奏新增变量/输出时同步更新 README每次重大基础设施变更后更新架构图。这与 terraform.instructions.md 对注释的要求说明复杂配置与决策原因、避免冗余注释共同构成文档即代码文化。十一、验证与测试把质量门槛前置原准则apply 前先跑terraform validate并审查terraform plan输出尽早发现错误与意外变更考虑落地自动化检查CI 流水线、pre-commit hooks强制执行格式化、lint 与基础验证。推荐的本地工作流为# 1. 格式化 terraform fmt -recursive # 2. 语法与配置校验 terraform validate # 3. 静态风格检查可选但推荐 tflint # 4. 审查变更 terraform plan # 5. 确认后应用 terraform applyterraform-azure.instructions.md 对 plan 的使用有一条重要纪律运行terraform plan前必须先征求用户同意且订阅 ID 应从ARM_SUBSCRIPTION_ID环境变量读取绝不能硬编码进 provider 块。这一条也呼应了前文用户指令优先级最高、变更需确认的协作模式。在 AVM 参与的场景azure-verified-modules-terraform.instructions.md 给出了更完整的 CI 门槛任何 PR 提交前都必须执行# 格式化递归 terraform fmt -recursive # 语法校验 terraform validate # AVM 专属强制校验 ./avm pre-commit ./avm tflint ./avm pr-check这套组合拳将格式化 → 语法 → 风格 → AVM 规范四层门槛全部前置到本地与 CI避免 PR 校验阶段才发现问题导致返工。对普通非 AVM 贡献项目最小可行方案是 pre-commit 钩子中串联terraform fmt -check与terraform validate再在 CI 中加入tflint与安全扫描如 checkov/tfsec见 terraform.instructions.md 的安全审计建议。十二、组合使用从指令到生产级工作流将以上 10 条准则串联起来一份现代 Azure Terraform 代码的生成与交付闭环如下版本锁定required_versionrequired_providers固定 Terraform 与 azurerm 版本准则 1结构先行按 main/variables/outputs/terraform/locals 分文件超过规模即按资源类型拆分准则 2模块化优先引 AVM 官方模块无 AVM 时按 AVM 风格自建并设计好变量/输出接口准则 3参数化全部输入走带类型描述默认值的变量输出按需暴露机密标记sensitive准则 4Provider 取舍默认 azurerm仅新特性场景用 azapi 并注释理由准则 5依赖审查不新增无关 provider/模块确需引入先注释再确认准则 6幂等验证非生产环境连续 apply 两次第二次必须零变更准则 7状态治理Azure Storage 远程后端 状态锁 状态文件永不入库准则 8文档同步terraform-docs 自动生成 README 手工更新 架构图随变更维护准则 9质量门槛validate/plan 先于 applyCI 与 pre-commit 强制 fmt、lint 与校验准则 10。这 10 条准则并非孤立清单而是与仓库内 terraform.instructions.md通用约定、terraform-azure.instructions.mdAzure 最佳实践以及 azure-verified-modules-terraform.instructions.mdAVM 规范形成互补的完整体系。理解它们的分工就能在 Copilot 中按需组合出既现代、又可维护、且具备生产级质量保障的 Azure Terraform 代码。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考