Azure Developer CLIazd安全、Hook、CI/CD 与运维实战基于 awesome-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-copilot本指南以本仓库 azure-developer-cli 技能 的官方参考文档 security-cicd-operations.md 为核心骨架系统讲解 Azure Developer CLIazd在身份与密钥管理、hooks 扩展、部署工作流、CI/CD 流水线、预部署验证、故障排查与资源清理上的官方推荐做法。读完本文你将掌握如何在 azd 项目中构建默认安全、可审计、可回滚、可自动化的端到端发布链路并能在代码评审与排障时对照仓库内的示例配置逐项落地。一、身份与密钥处理从优先顺序到绝对红线azd 项目的安全性首先取决于以什么身份、用什么凭据来访问 Azure。参考文档给出了明确的优先级顺序从最受推荐到仅在万不得已时使用托管身份 最小权限 RBAC让应用与部署管道自身携带 Azure 托管身份通过资源组或资源级作用域的 RBAC 角色分配获取访问权不持有任何静态凭据。CI/CD 中的工作负载身份联合Workload identity federation在流水线中利用 OIDC 短期令牌完成身份交换避免把长期凭据放进流水线。通过azd env set-secret的 Key Vault 引用当确需使用密钥时让 AZD 环境保存指向 Key Vault 的引用而非明文。短生命周期密钥材料仅在没有任何基于身份的选择可用时才允许出现短期密钥且必须严格控制生命周期。这份优先级与本技能 SKILL.md 中Apply safety guardrails一节的默认值表完全一致默认依次选择托管身份/RBAC 优先其次才是 Key Vault 引用。绝对禁止清单Never 清单参考文档同时划出了不可逾越的红线评审任何 azd 项目时都应逐条检查不要把明文密钥写入.azure/environment/.env不要把环境文件、凭据、证书或 Terraform 状态文件提交进源码仓库不要把密钥放进 IaC 的输出outputs中——部署输出会被复制进 AZD 环境等于变相落盘不要在 hooks 或流水线中不加区分地回显环境变量值不要在命令行上直接传递密钥尤其是当 shell 或 CI 系统会记录命令历史时不要授予超出实际需要的订阅级角色能用资源组或资源级作用域就绝不放宽。azd env set-secret的两种落地路径azd env set-secret name的作用是把一个 Key Vault 引用写入 AZD 环境而不是把明文塞进.env。参考文档给出了三种按需解析方式映射为 Bicep 的secure()参数通过 hook 的secrets映射提供给 hook 进程在流水线变量保存 Key Vault 引用与流水线密钥保存解析后的值之间做出选择。推荐的取舍原则是只要流水线身份能够读取 Key Vault就优先采用引用方案——这样密钥轮换时无需重新发布解析后的流水线密钥轮换成本趋近于零。对照 iac-and-environments.md 中的 Bicep 段落可知配合secure()参数时还需要在main.parameters.json中映射该引用并且绝不把安全值写入输出该文档还特别提醒当前 AZD 官方文档说明环境密钥与.bicepparam文件尚不兼容。二、Hooks用脚本补齐生命周期缺口Hooks 用于承载 IaC 与 azd 原生行为无法表达的校验、生成的运行时配置、数据准备、冒烟检查与生命周期协调。原则是能用声明式 IaC 和原生服务配置解决的就不用 hook见 SKILL.md 中Add hooks only for lifecycle gaps一节。Hook 编写规则优先使用外部脚本而非一长串内联命令脚本统一存放于scripts/azd目录下纳入版本管理显式声明shell: sh或shell: pwsh当语法存在差异时同时提供windows与posix两种实现使用相对于文档声明的 hook 工作目录的路径脚本必须幂等可安全重复执行除非该操作仅是观测性质或确实可选否则保持continueOnError: false在 CI 中必须采用非交互行为如果一次性的可复现工具安装即可满足要求就不要在每次运行时安装未固定版本的依赖不要记录密钥值或全部环境变量在把 hook 接入完整部署流程之前先用azd hooks run hook-name独立测试。参考 YAML 示例参考文档给出的完整示例与本仓库 examples/azure.yaml 中的 hooks 片段一致hooks: preprovision: windows: shell: pwsh run: ./scripts/azd/validate.ps1 interactive: false continueOnError: false posix: shell: sh run: ./scripts/azd/validate.sh interactive: false continueOnError: false示例中两个值得注意的点一是interactive: false保证在 CI 中不会卡在交互提示上二是preprovision放在根级 hooks 下表示这是**项目级root hook**行为。规则是根 hooks 覆盖整个项目而服务专属的 hooks 应挂在该服务对应的azure.yaml条目下服务级 hook。这与 project-structure.md 中根 hooks 处理项目级工作、服务 hooks 处理单个服务的设计一致且 hook 不应重复应用测试或声明式 IaC 已覆盖的行为。三、部署工作流azd up与分离式阶段命令AZD 的标准生命周期包含三步打包应用工件package预置或更新基础设施provision部署应用工件deploy。azd up是三者合并的便捷工作流适合日常开发与简单部署。参考文档建议在以下场景改用分离命令部署前需要基础设施评审或审批应用频繁重新部署而基础设施不变排障时希望把打包、预置、部署的失败相互隔离复杂依赖要求自定义执行顺序。azd package azd provision -e environment azd deploy -e environment注意-e environment显式指定目标环境。只有存在真实依赖例如预置阶段产出的端点必须先于某个构建存在时才需要定制workflows.up.steps不要仅仅为了迎合某个流水线的命名习惯就改写默认工作流——这与 SKILL.mdBuild CI/CD deliberately中的立场一致。更完整的按阶段命令可参考 iac-and-environments.md 中环境管理一节azd provision -e environment --no-prompt azd deploy -e environment --no-prompt自动化与潜在破坏性操作中--no-prompt与显式-e必须同时出现。四、全栈与多服务依赖先映射再选择机制对于前端 后端等多服务项目参考文档要求实现前先完成依赖映射并按以下次序选择解耦机制让 Bicep 或 Terraform 处理单向基础设施依赖使用**预置输出provisioning outputs**传递部署阶段所需的端点与名称当配置需要在不重建的情况下变化时使用运行时配置如 Azure App Configuration 或生成的配置文件避免前端与后端之间的循环编译期依赖仅当输出与运行时配置都无法解决依赖时才引入 hooks 或自定义工作流在开发、测试与类生产环境中独立验证该依赖策略。从源码结构看project-structure.md 推荐的仓库布局把每个可独立部署的服务放在src/service-name下服务间依赖使用azure.yaml中受支持的uses关系显式声明而不是依赖文件顺序的隐式假设。在 Bicep 侧iac-and-environments.md 强调用稳定命名的 outputs如output SERVICE_API_ENDPOINT_URL string api.outputs.endpoint作为预置阶段与后续阶段之间的契约因为服务、hooks 与流水线都会把它们当作环境变量消费。五、CI/CD 流水线七阶段骨架与自动化纪律健壮流水线的阶段划分参考文档推荐把流水线清晰拆分为 7 个阶段每个阶段职责单一、可独立失败应用层的格式化、lint、构建与测试IaC 的格式与静态校验在正确作用域上执行 what-if / plan 评审使用显式 AZD 环境执行预置部署冒烟或健康检查生产审批与回滚/清理流程。同时强制使用如下纪律自动化中一律--no-prompt固定-e/--environment不依赖当前选中环境iac-and-environments.md 同样强调不要在脚本中假设当前选中环境为生产环境启用受保护环境与必需评审人使用并发控制防止对同一环境的并发写入使用最小权限且作用域限定到目标环境的身份固定 action 与工具版本并配有受管理的升级流程。azd pipeline configbeta 特性使用前检查清单当前 Microsoft 官方文档将azd pipeline config标记为beta。运行之前必须审阅模板自带的流水线定义确认仓库、组织、环境、订阅与认证模式预期其副作用仓库、身份、变量、密钥、提交、推送与流水线都会发生变更在用于生产前审阅生成的工作流与权限改动当pipeline.variables或pipeline.secrets变化时重新运行该命令。对于GitHub ActionsAZD 在受支持的场景下默认配置 OIDC/联合凭据但官方文档说明AZD 的 Terraform 流水线流程不支持 OIDC因此必须显式评估认证取舍而不是默默回退到长期凭据。对于Terraform项目务必在流水线配置前先准备好受保护的远程状态——远程状态的后端访问密钥不得进入源码控制详见 iac-and-environments.md 的 Remote state 一节。六、验证与预览在触碰 Azure 之前先本地把关参考文档要求任何会改变 Azure 资源的命令执行之前先运行本地检查。Bicepaz bicep build --file infra/main.bicep注意what-if 分析必须在使用模板声明的正确作用域targetScope上执行不要想当然地假设是资源组作用域。Terraformterraform fmt -check -recursive terraform init -backendfalse terraform validate只有在确认了后端、workspace/state key、变量与 Azure 身份之后才执行terraform plan。AZD 与应用层运行现有的应用检查格式化、lint、类型检查、构建、测试独立运行相关 hooksazd hooks run hook-name执行azd package验证服务路径与打包逻辑确认 IaC 输出与部署阶段消费的变量一一对应在 provision、deploy、down 之前检查环境名。这些检查项与 SKILL.mdValidate before finishing一节给出的校验矩阵一致后者还补充了检查.gitignore是否排除.azure、密钥、本地状态与生成产物以及无密钥出现在被跟踪内容或命令输出中两条验收标准。七、故障排查八步最小化定位法当部署失败时参考文档给出了从粗到细的排查顺序判断失败属于打包、预置、部署、hook、认证、资源发现中的哪一类重新运行最小的失败阶段而不是重跑azd up核对所选环境以及预期的订阅、租户与区域检查azure.yaml中的路径、provider、服务名、host 类型与资源发现标签当 Azure 侧状态被其他方改变时用azd env refresh刷新环境输出对于 Terraform同时验证 AZD 与 Azure CLI 的认证以及正确的远程状态对于 hooks直接运行该 hook核对它的 shell、工作目录与环境依赖仅在必要时开启调试日志分享日志前先脱敏敏感值。其中第 5 步azd env refresh的价值在 iac-and-environments.md 中被反复强调当其他参与者修改了部署输出后用它同步环境在团队共享环境时还应配置 AZD 远程状态state.remote后端为 AzureBlobStorage。注意 AZD 远程状态同步的是.env与config.json与 Terraform 远程状态是两套独立存储Terraform 协作项目可能两者都需要。八、清理azd down前必须确认的三件事清理环节最容易造成数据事故参考文档的要求包括确认精确的环境名再执行azd down向用户说明清理可能删除承载数据的资源保留外部拥有或共享的资源本技能 SKILL.md 的安全护栏同样要求保留当前 azd 项目之外拥有的资源与状态对临时环境自动化清理流程并为流水线运行失败提供兜底验证删除结果而不是默认命令成功即成功。对于临时环境如 PR 环境的命名与清理联动可对照 iac-and-environments.md 的环境命名策略project-pr-number这类临时环境名必须同时有自动化保障其清理。九、落地清单把参考文档变成评审与实施检查表结合 SKILL.md 的安全护栏与本文内容一个可直接照做的检查表如下.gitignore排除.azure、*.env、凭据、本地 Terraform 状态与生成产物azure.yaml、IaC 参数文件、hooks、源码与会被记录的参数中无字面密钥密钥一律走托管身份/RBAC或 Key Vault 引用 azd env set-secret任何创建/修改/删除 Azure 资源的命令执行前核对环境、订阅、租户、区域与作用域运行azd pipeline config前完成 beta 特性审阅与 Terraform 受保护远程状态配置hooks 均位于scripts/azd、显式声明 shell、幂等且已在 CI 中非交互验证预置前依次完成az bicep build或terraform fmt/init/validate与azd packageIaC 输出名称稳定且不含安全值且与部署消费变量一致自动化脚本全部带-e environment与--no-prompt。本文所有结论均可在仓库内交叉验证核心参考文档为 security-cicd-operations.md配套的顶层技能说明见 SKILL.md可执行的配置示例见 examples/azure.yaml基础设施与环境策略见 iac-and-environments.md仓库布局规范见 project-structure.md。关于快速变化的功能如azd pipeline config的 beta 状态、环境密钥与.bicepparam的兼容性、Terraform 流水线的 OIDC 限制均以 official-docs.md 所指向的 Microsoft Learn 当前文档为准不要依赖记忆中的语法。【免费下载链接】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），仅供参考