pulumi-best-practices

Pulumi Best Practices

When to Use This Skill

Invoke this skill when:

• Writing new Pulumi programs or components
• Reviewing Pulumi code for correctness
• Refactoring existing Pulumi infrastructure
• Debugging resource dependency issues
• Setting up configuration and secrets

Practices

1. Never Create Resources Inside apply()

Why: Resources created inside apply() don't appear in pulumi preview, making changes unpredictable. Pulumi cannot properly track dependencies, leading to race conditions and deployment failures.

Detection signals:

• new aws. or other resource constructors inside .apply() callbacks
• Resource creation inside pulumi.all([...]).apply()
• Dynamic resource counts determined at runtime inside apply

Wrong:

const bucket = new aws.s3.Bucket("bucket");

bucket.id.apply(bucketId => {
    // WRONG: This resource won't appear in preview
    new aws.s3.BucketObject("object", {
        bucket: bucketId,
        content: "hello",
    });
});

Right:

const bucket = new aws.s3.Bucket("bucket");

// Pass the output directly - Pulumi handles the dependency
const object = new aws.s3.BucketObject("object", {
    bucket: bucket.id,  // Output<string> works here
    content: "hello",
});

When apply is appropriate:

• Transforming output values for use in tags, names, or computed strings
• Logging or debugging (not resource creation)
• Conditional logic that affects resource properties, not resource existence

Reference: https://www.pulumi.com/docs/concepts/inputs-outputs/

---

2. Pass Outputs Directly as Inputs

Why: Pulumi builds a directed acyclic graph (DAG) based on input/output relationships. Passing outputs directly ensures correct creation order. Unwrapping values manually breaks the dependency chain, causing resources to deploy in wrong order or reference values that don't exist yet.

Detection signals:

• Variables extracted from .apply() used later as resource inputs
• await on output values outside of apply
• String concatenation with outputs instead of pulumi.interpolate