# Pulumi

> Pulumi Best Practices

- Skill: `comeonoliver/pulumi` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/pulumi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/pulumi/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/comeonoliver/pulumi

---

# 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](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`