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 stackspstate-checkpoint-skipping- Enable checkpoint skipping for large stackspstate-stack-size- Keep stacks under 500 resourcespstate-refresh-targeting- Use targeted refresh instead of full stackpstate-export-import- Use state export/import for migrationspstate-import-existing- Import existing resources before managing
2. Resource Graph Optimization (CRITICAL)
graph-parallel-resources- Structure resources for maximum parallelismgraph-output-dependencies- Use outputs to express true dependenciesgraph-explicit-depends- Use dependsOn only for external dependenciesgraph-avoid-apply-side-effects- Avoid side effects in apply functionsgraph-conditional-resources- Use conditional logic at resource levelgraph-stack-references-minimal- Minimize stack reference depth
3. Component Design (HIGH)
pcomp-component-resources- Use ComponentResource for reusable abstractionspcomp-parent-child- Pass parent option to child resourcespcomp-unique-naming- Use name prefix pattern for unique resource namespcomp-register-outputs- Register component outputs explicitlypcomp-multi-language- Design components for multi-language consumptionpcomp-transformations- Use transformations for cross-cutting concerns
4. Secrets and Configuration (HIGH)
secrets-use-secret-config- Use secret config for sensitive valuessecrets-avoid-state-exposure- Prevent secret leakage in statesecrets-external-providers- Use external secret managers for productionsecrets-generate-random- Generate secrets with random providersecrets-provider-rotation- Rotate secrets provider when team members leavesecrets-environment-isolation- Isolate secrets by environment
5. Stack Organization (MEDIUM-HIGH)
stack-separation-by-lifecycle- Separate stacks by deployment lifecyclestack-references-parameterized- Parameterize stack referencesstack-output-minimal- Export only required outputsstack-naming-conventions- Use consistent stack naming convention
6. Resource Options and Lifecycle (MEDIUM)
lifecycle-protect-stateful- Protect stateful resourceslifecycle-delete-before-replace- Use deleteBeforeReplace for unique constraintslifecycle-retain-on-delete- Use retainOnDelete for shared resourceslifecycle-ignore-changes- Use ignoreChanges for externally managed propertieslifecycle-replace-on-changes- Use replaceOnChanges for immutable dependencieslifecycle-aliases- Use aliases for safe resource renaminglifecycle-custom-timeouts- Set custom timeouts for long-running resources
7. Testing and Validation (MEDIUM)
test-unit-mocking- Use mocks for fast unit teststest-property-policies- Use policy as code for property testingtest-integration-ephemeral- Use ephemeral stacks for integration teststest-preview-assertions- Assert on preview results before deploymenttest-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 workflowsauto-inline-programs- Use inline programs for dynamic infrastructureauto-ci-cd-preview- Run preview in PR checksauto-deployments-api- Use Pulumi Deployments for GitOpsauto-review-stacks- Use review stacks for PR environmentsauto-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