名称: pulumi 描述: Pulumi 基础设施即代码性能和可靠性指南。该技能应在编写、审查或重构 Pulumi 代码时使用，以确保最佳部署性能和基础设施可靠性。适用于涉及 Pulumi 栈、组件、状态管理、秘密配置、资源生命周期选项或 CI/CD 自动化的任务。
Pulumi 最佳实践
Pulumi 基础设施即代码的全面性能和可靠性指南，专为 AI 代理和 LLMs 设计。包含 8 个类别中的 46 条规则，按影响优先级排序，以指导自动化重构和代码生成。
何时应用
参考这些指南当：
- 编写新的 Pulumi 基础设施代码
- 设计用于重用的组件抽象
- 配置秘密和敏感值
- 组织栈和跨栈引用
- 为基础设施设置 CI/CD 流水线
按优先级分类的规则类别
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 状态管理和后端 | 关键 | pstate- |
| 2 | 资源图优化 | 关键 | graph- |
| 3 | 组件设计 | 高 | pcomp- |
| 4 | 秘密和配置 | 高 | secrets- |
| 5 | 栈组织 | 中高 | stack- |
| 6 | 资源选项和生命周期 | 中 | lifecycle- |
| 7 | 测试和验证 | 中 | test- |
| 8 | 自动化和 CI/CD | 低中 | auto- |
快速参考
1. 状态管理和后端（关键）
pstate-backend-selection- 为生产栈使用托管后端pstate-checkpoint-skipping- 为大型栈启用检查点跳过pstate-stack-size- 保持栈资源数低于 500 个pstate-refresh-targeting- 使用目标刷新而非全栈刷新pstate-export-import- 使用状态导出/导入进行迁移pstate-import-existing- 在管理前导入现有资源
2. 资源图优化（关键）
graph-parallel-resources- 结构化资源以实现最大并行度graph-output-dependencies- 使用输出表达真实依赖关系graph-explicit-depends- 仅对外部依赖使用 dependsOngraph-avoid-apply-side-effects- 避免在 apply 函数中产生副作用graph-conditional-resources- 在资源级别使用条件逻辑graph-stack-references-minimal- 最小化栈引用深度
3. 组件设计（高）
pcomp-component-resources- 使用 ComponentResource 实现可重用抽象pcomp-parent-child- 向子资源传递父选项pcomp-unique-naming- 使用名称前缀模式确保唯一资源名称pcomp-register-outputs- 显式注册组件输出pcomp-multi-language- 设计支持多语言使用的组件pcomp-transformations- 使用转换处理横切关注点
4. 秘密和配置（高）
secrets-use-secret-config- 使用秘密配置处理敏感值secrets-avoid-state-exposure- 防止秘密在状态中泄露secrets-external-providers- 在生产环境中使用外部秘密管理器secrets-generate-random- 使用随机提供程序生成秘密secrets-provider-rotation- 在团队成员离开时轮换秘密提供程序secrets-environment-isolation- 按环境隔离秘密
5. 栈组织（中高）
stack-separation-by-lifecycle- 按部署生命周期分离栈stack-references-parameterized- 参数化栈引用stack-output-minimal- 仅导出必需输出stack-naming-conventions- 使用一致的栈命名约定
6. 资源选项和生命周期（中）
lifecycle-protect-stateful- 保护有状态资源lifecycle-delete-before-replace- 对唯一约束使用 deleteBeforeReplacelifecycle-retain-on-delete- 对共享资源使用 retainOnDeletelifecycle-ignore-changes- 对外部管理属性使用 ignoreChangeslifecycle-replace-on-changes- 对不可变依赖使用 replaceOnChangeslifecycle-aliases- 使用别名安全重命名资源lifecycle-custom-timeouts- 为长时间运行资源设置自定义超时
7. 测试和验证（中）
test-unit-mocking- 使用模拟进行快速单元测试test-property-policies- 使用策略即代码进行属性测试test-integration-ephemeral- 使用临时栈进行集成测试test-preview-assertions- 在部署前对预览结果进行断言test-stack-reference-mocking- 在单元测试中模拟栈引用
8. 自动化和 CI/CD（低中）
auto-automation-api-workflows- 使用 Automation API 处理复杂工作流auto-inline-programs- 使用内联程序处理动态基础设施auto-ci-cd-preview- 在 PR 检查中运行预览auto-deployments-api- 使用 Pulumi Deployments 实现 GitOpsauto-review-stacks- 为 PR 环境使用审查栈auto-drift-detection- 为生产环境启用漂移检测
如何使用
阅读单个参考文件以获取详细解释和代码示例：
完整编译文档
完整指南包含所有规则扩展：AGENTS.md