Pulumi Best Practices

interface:
  display_name: "Pulumi Best Practices"
  short_description: "Best practices for robust Pulumi programs"
  default_prompt: "Use $pulumi-best-practices to apply reliable Pulumi coding patterns to this task."


---
name: pulumi-best-practices
version: 1.0.0
description: Load when the user is writing, reviewing, or debugging Pulumi TypeScript/Python programs; asks about Output<T> or apply() usage; wants to create ComponentResource classes; needs to refactor resources without destroying them (aliases); is setting up secrets or config; or is configuring a pulumi preview/up CI workflow. Also load for questions about resource dependency order, parent/child resource relationships, or pulumi.interpolate.
---

# 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**:

```typescript
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**:

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

**Wrong**:

```typescript
const vpc = new aws.ec2.Vpc("vpc", { cidrBlock: "10.0.0.0/16" });

// WRONG: Extracting the value breaks the dependency chain
let vpcId: string;
vpc.id.apply(id => { vpcId = id; });

const subnet = new aws.ec2.Subnet("subnet", {
    vpcId: vpcId,  // May be undefined, no tracked dependency
    cidrBlock: "10.0.1.0/24",
});
```

**Right**:

```typescript
const vpc = new aws.ec2.Vpc("vpc", { cidrBlock: "10.0.0.0/16" });

const subnet = new aws.ec2.Subnet("subnet", {
    vpcId: vpc.id,  // Pass the Output directly
    cidrBlock: "10.0.1.0/24",
});
```

**For string interpolation**:

```typescript
// WRONG
const name = bucket.id.apply(id => `prefix-${id}-suffix`);

// RIGHT - use pulumi.interpolate for template literals
const name = pulumi.interpolate`prefix-${bucket.id}-suffix`;

// RIGHT - use pulumi.concat for simple concatenation
const name = pulumi.concat("prefix-", bucket.id, "-suffix");
```

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

---

### 3. Use Components for Related Resources

**Why**: ComponentResource classes group related resources into reusable, logical units. Withou