Pulumi Best Practices
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.
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
Rule Categories by Priority
| 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- |
Quick Reference
1. State Management and Backend (CRITICAL)
- •
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
2. Resource Graph Optimization (CRITICAL)
- •
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
3. Component Design (HIGH)
- •
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
4. Secrets and Configuration (HIGH)
- •
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
5. Stack Organization (MEDIUM-HIGH)
- •
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
6. Resource Options and Lifecycle (MEDIUM)
- •
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
7. Testing and Validation (MEDIUM)
- •
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
8. Automation and CI/CD (LOW-MEDIUM)
- •
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
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