pulumi

Pulumi 最佳实践

面向 AI Agent 和大模型的 Pulumi 基础设施即代码综合性能与可靠性指南。包含 8 个类别中的 46 条规则，并按影响程度排序，以指导自动化重构和代码生成。

适用场景

在以下情况下，请参考这些指南：

• 编写新的 Pulumi 基础设施代码
• 设计可复用的组件抽象
• 配置机密和敏感值
• 组织堆栈及跨堆栈引用
• 设置基础设施的 CI/CD 流水线

按优先级划分的规则类别

优先级	类别	影响	前缀
1	状态管理与后端	CRITICAL	pstate-
2	资源图优化	CRITICAL	graph-
3	组件设计	HIGH	pcomp-
4	机密与配置	HIGH	secrets-
5	堆栈组织	MEDIUM-HIGH	stack-
6	资源选项与生命周期	MEDIUM	lifecycle-
7	测试与验证	MEDIUM	test-
8	自动化与 CI/CD	LOW-MEDIUM	auto-

快速参考

1. 状态管理与后端（CRITICAL）

• pstate-backend-selection - 生产堆栈使用托管后端
• pstate-checkpoint-skipping - 为大型堆栈启用检查点跳过
• pstate-stack-size - 将堆栈控制在 500 个资源以内
• pstate-refresh-targeting - 使用定向刷新，而非刷新整个堆栈
• pstate-export-import - 迁移时使用状态导出/导入
• pstate-import-existing - 在管理现有资源前先将其导入

2. 资源图优化（CRITICAL）

• graph-parallel-resources - 组织资源，以实现最大并行度
• graph-output-dependencies - 使用输出表达实际依赖关系
• graph-explicit-depends - 仅对外部依赖使用 dependsOn
• graph-avoid-apply-side-effects - 避免在 apply 函数中产生副作用
• graph-conditional-resources - 在资源层级使用条件逻辑
• graph-stack-references-minimal - 尽量减少堆栈引用层级

3. 组件设计（HIGH）

• pcomp-component-resources - 使用 ComponentResource 创建可复用的抽象
• pcomp-parent-child - 将 parent 选项传递给子资源
• pcomp-unique-naming - 使用名称前缀模式确保资源名称唯一
• pcomp-register-outputs - 显式注册组件输出
• pcomp-multi-language - 设计可供多种语言使用的组件
• pcomp-transformations - 使用 transformations 处理横切关注点

4. 机密与配置（HIGH）

• secrets-use-secret-config - 对敏感值使用机密配置
• secrets-avoid-state-exposure - 防止机密泄露到状态中
• secrets-external-providers - 在生产环境中使用外部机密管理器
• secrets-generate-random - 使用 random provider 生成机密
• secrets-provider-rotation - 团队成员离开时轮换机密提供方
• secrets-environment-isolation - 按环境隔离机密

5. 堆栈组织（MEDIUM-HIGH）

• stack-separation-by-lifecycle - 按部署生命周期拆分堆栈
• stack-references-parameterized - 将堆栈引用参数化
• stack-output-minimal - 仅导出必需的输出
• stack-naming-conventions - 使用一致的堆栈命名约定

6. 资源选项与生命周期（MEDIUM）

• lifecycle-protect-stateful - 保护有状态资源
• lifecycle-delete-before-replace - 对具有唯一性约束的资源使用 deleteBeforeReplace
• lifecycle-retain-on-delete - 对共享资源使用 retainOnDelete
• lifecycle-ignore-changes - 对由外部管理的属性使用 ignoreChanges
• lifecycle-replace-on-changes - 对不可变依赖项使用 replaceOnChanges
• lifecycle-aliases - 使用 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 实现 GitOps
• auto-review-stacks - 使用审查堆栈为 PR 提供环境
• auto-drift-detection - 为生产环境启用漂移检测

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 分类结构和影响级别
• 规则模板 - 添加新规则的模板

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md