pulumi

Files (52)

• AGENTS.md
• README.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• auto-automation-api-workflows.md · references/
• auto-ci-cd-preview.md · references/
• auto-deployments-api.md · references/
• auto-drift-detection.md · references/
• auto-inline-programs.md · references/
• auto-review-stacks.md · references/
• graph-avoid-apply-side-effects.md · references/
• graph-conditional-resources.md · references/
• graph-explicit-depends.md · references/
• graph-output-dependencies.md · references/
• graph-parallel-resources.md · references/
• graph-stack-references-minimal.md · references/
• lifecycle-aliases.md · references/
• lifecycle-custom-timeouts.md · references/
• lifecycle-delete-before-replace.md · references/
• lifecycle-ignore-changes.md · references/
• lifecycle-protect-stateful.md · references/
• lifecycle-replace-on-changes.md · references/
• lifecycle-retain-on-delete.md · references/
• pcomp-component-resources.md · references/
• pcomp-multi-language.md · references/
• pcomp-parent-child.md · references/
• pcomp-register-outputs.md · references/
• pcomp-transformations.md · references/
• pcomp-unique-naming.md · references/
• pstate-backend-selection.md · references/
• pstate-checkpoint-skipping.md · references/
• pstate-export-import.md · references/
• pstate-import-existing.md · references/
• pstate-refresh-targeting.md · references/
• pstate-stack-size.md · references/
• secrets-avoid-state-exposure.md · references/
• secrets-environment-isolation.md · references/
• secrets-external-providers.md · references/
• secrets-generate-random.md · references/
• secrets-provider-rotation.md · references/
• secrets-use-secret-config.md · references/
• stack-naming-conventions.md · references/
• stack-output-minimal.md · references/
• stack-references-parameterized.md · references/
• stack-separation-by-lifecycle.md · references/
• test-integration-ephemeral.md · references/
• test-preview-assertions.md · references/
• test-property-policies.md · references/
• test-stack-reference-mocking.md · references/
• test-unit-mocking.md · references/

SKILL.md (first lines)

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

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills