pulumi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pulumi Best Practices

Pulumi最佳实践

Comprehensive performance and reliability guide for Pulumi infrastructure as code, designed for AI agents and LLMs. Contains 46 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

专为AI Agent和大语言模型设计的Pulumi基础设施即代码性能与可靠性综合指南。包含8个类别下的46条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new Pulumi infrastructure code
Designing component abstractions for reuse
Configuring secrets and sensitive values
Organizing stacks and cross-stack references
Setting up CI/CD pipelines for infrastructure

在以下场景中参考本指南：

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

Rule Categories by Priority

按优先级划分的规则类别


pstate-
graph-
pcomp-
secrets-
stack-
lifecycle-
test-
auto-

Priority	Category	Impact	Prefix
1	State Management and Backend	CRITICAL	`pstate-`
2	Resource Graph Optimization	CRITICAL	`graph-`
3	Component Design	HIGH	`pcomp-`
4	Secrets and Configuration	HIGH	`secrets-`
5	Stack Organization	MEDIUM-HIGH	`stack-`
6	Resource Options and Lifecycle	MEDIUM	`lifecycle-`
7	Testing and Validation	MEDIUM	`test-`
8	Automation and CI/CD	LOW-MEDIUM	`auto-`


pstate-
graph-
pcomp-
secrets-
stack-
lifecycle-
test-
auto-

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

Quick Reference

快速参考

1. State Management and Backend (CRITICAL)

1. 状态管理与后端（关键）

```
pstate-backend-selection
```
- Use managed backend for production stacks
```
pstate-checkpoint-skipping
```
- Enable checkpoint skipping for large stacks
```
pstate-stack-size
```
- Keep stacks under 500 resources
```
pstate-refresh-targeting
```
- Use targeted refresh instead of full stack
```
pstate-export-import
```
- Use state export/import for migrations
```
pstate-import-existing
```
- Import existing resources before managing

```
pstate-backend-selection
```
- 生产环境栈使用托管后端
```
pstate-checkpoint-skipping
```
- 大型栈启用检查点跳过
```
pstate-stack-size
```
- 栈资源数量保持在500个以下
```
pstate-refresh-targeting
```
- 使用定向刷新而非全栈刷新
```
pstate-export-import
```
- 迁移时使用状态导出/导入
```
pstate-import-existing
```
- 管理前先导入现有资源

2. Resource Graph Optimization (CRITICAL)

2. 资源图优化（关键）

```
graph-parallel-resources
```
- Structure resources for maximum parallelism
```
graph-output-dependencies
```
- Use outputs to express true dependencies
```
graph-explicit-depends
```
- Use dependsOn only for external dependencies
```
graph-avoid-apply-side-effects
```
- Avoid side effects in apply functions
```
graph-conditional-resources
```
- Use conditional logic at resource level
```
graph-stack-references-minimal
```
- Minimize stack reference depth

```
graph-parallel-resources
```
- 构建资源结构以实现最大并行度
```
graph-output-dependencies
```
- 使用输出表达真实依赖关系
```
graph-explicit-depends
```
- 仅对外部依赖使用dependsOn
```
graph-avoid-apply-side-effects
```
- 避免在apply函数中产生副作用
```
graph-conditional-resources
```
- 在资源层面使用条件逻辑
```
graph-stack-references-minimal
```
- 最小化栈引用深度

3. Component Design (HIGH)

3. 组件设计（高）

```
pcomp-component-resources
```
- Use ComponentResource for reusable abstractions
```
pcomp-parent-child
```
- Pass parent option to child resources
```
pcomp-unique-naming
```
- Use name prefix pattern for unique resource names
```
pcomp-register-outputs
```
- Register component outputs explicitly
```
pcomp-multi-language
```
- Design components for multi-language consumption
```
pcomp-transformations
```
- Use transformations for cross-cutting concerns

```
pcomp-component-resources
```
- 使用ComponentResource实现可复用抽象
```
pcomp-parent-child
```
- 向子资源传递parent选项
```
pcomp-unique-naming
```
- 使用名称前缀模式确保资源名称唯一
```
pcomp-register-outputs
```
- 显式注册组件输出
```
pcomp-multi-language
```
- 设计支持多语言调用的组件
```
pcomp-transformations
```
- 使用转换处理横切关注点

4. Secrets and Configuration (HIGH)

4. 机密与配置（高）

```
secrets-use-secret-config
```
- Use secret config for sensitive values
```
secrets-avoid-state-exposure
```
- Prevent secret leakage in state
```
secrets-external-providers
```
- Use external secret managers for production
```
secrets-generate-random
```
- Generate secrets with random provider
```
secrets-provider-rotation
```
- Rotate secrets provider when team members leave
```
secrets-environment-isolation
```
- Isolate secrets by environment

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

5. Stack Organization (MEDIUM-HIGH)

5. 栈组织（中高）

```
stack-separation-by-lifecycle
```
- Separate stacks by deployment lifecycle
```
stack-references-parameterized
```
- Parameterize stack references
```
stack-output-minimal
```
- Export only required outputs
```
stack-naming-conventions
```
- Use consistent stack naming convention

```
stack-separation-by-lifecycle
```
- 按部署生命周期拆分栈
```
stack-references-parameterized
```
- 对栈引用进行参数化
```
stack-output-minimal
```
- 仅导出必要的输出
```
stack-naming-conventions
```
- 使用统一的栈命名规范

6. Resource Options and Lifecycle (MEDIUM)

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

```
lifecycle-protect-stateful
```
- Protect stateful resources
```
lifecycle-delete-before-replace
```
- Use deleteBeforeReplace for unique constraints
```
lifecycle-retain-on-delete
```
- Use retainOnDelete for shared resources
```
lifecycle-ignore-changes
```
- Use ignoreChanges for externally managed properties
```
lifecycle-replace-on-changes
```
- Use replaceOnChanges for immutable dependencies
```
lifecycle-aliases
```
- Use aliases for safe resource renaming
```
lifecycle-custom-timeouts
```
- Set custom timeouts for long-running resources

```
lifecycle-protect-stateful
```
- 保护有状态资源
```
lifecycle-delete-before-replace
```
- 对唯一约束使用deleteBeforeReplace
```
lifecycle-retain-on-delete
```
- 对共享资源使用retainOnDelete
```
lifecycle-ignore-changes
```
- 对外部管理的属性使用ignoreChanges
```
lifecycle-replace-on-changes
```
- 对不可变依赖使用replaceOnChanges
```
lifecycle-aliases
```
- 使用别名实现安全的资源重命名
```
lifecycle-custom-timeouts
```
- 为长运行资源设置自定义超时

7. Testing and Validation (MEDIUM)

7. 测试与验证（中）

```
test-unit-mocking
```
- Use mocks for fast unit tests
```
test-property-policies
```
- Use policy as code for property testing
```
test-integration-ephemeral
```
- Use ephemeral stacks for integration tests
```
test-preview-assertions
```
- Assert on preview results before deployment
```
test-stack-reference-mocking
```
- Mock stack references in unit tests

```
test-unit-mocking
```
- 使用模拟实现快速单元测试
```
test-property-policies
```
- 使用策略即代码进行属性测试
```
test-integration-ephemeral
```
- 使用临时栈进行集成测试
```
test-preview-assertions
```
- 部署前对预览结果进行断言
```
test-stack-reference-mocking
```
- 单元测试中模拟栈引用

8. Automation and CI/CD (LOW-MEDIUM)

8. 自动化与CI/CD（中低）

```
auto-automation-api-workflows
```
- Use Automation API for complex workflows
```
auto-inline-programs
```
- Use inline programs for dynamic infrastructure
```
auto-ci-cd-preview
```
- Run preview in PR checks
```
auto-deployments-api
```
- Use Pulumi Deployments for GitOps
```
auto-review-stacks
```
- Use review stacks for PR environments
```
auto-drift-detection
```
- Enable drift detection for production

```
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
```
- 生产环境启用漂移检测

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明与代码示例：

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

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

包含所有扩展规则的完整指南：

AGENTS.md