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