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

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](references/_sections.md) - Category structure and impact levels
• [Rule template](assets/templates/_template.md) - Template for adding new rules

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md