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

pstate-

graph-

pcomp-

secrets-

stack-

lifecycle-

test-

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