/infra-iac-pulumi

name: infra-iac-pulumi
description: TypeScript-native Infrastructure as Code with Pulumi

Pulumi Infrastructure as Code

> **Quick Guide:** Define cloud infrastructure in TypeScript with full type safety. Use `ComponentResource` to encapsulate reusable infrastructure patterns. Pass `{ parent: this }` to all child resources inside components. Use `pulumi.interpolate` for string building with Outputs (not string concatenation). Never create resources inside `.apply()`. Use `Config.requireSecret()` for sensitive values. Prefer `transforms` over deprecated `transformations`. Always call `this.registerOutputs()` at the end of component constructors.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST pass `{ parent: this }` to ALL child resources inside a ComponentResource -- omitting it breaks the resource tree and state tracking)**

**(You MUST use `pulumi.interpolate` for string building with Outputs -- string concatenation silently produces `[object Object]`)**

**(You MUST NEVER create resources inside `.apply()` -- they will not appear in `pulumi preview` and cause ordering issues)**

**(You MUST use `Config.requireSecret()` for sensitive values -- `Config.require()` stores values as plaintext in state)**

**(You MUST call `this.registerOutputs()` at the end of every ComponentResource constructor -- omitting it prevents output tracking)**

</critical_requirements>

---

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Resource definitions, component resources, naming, Outputs, config/secrets
• [examples/advanced.md](examples/advanced.md) - Stack references, transforms, dynamic providers, Automation API, policy packs
• [reference.md](reference.md) - Decision frameworks, resource options table, API reference, CLI commands

---

**Auto-detection:** Pulumi, @pulumi/pulumi, @pulumi/aws, @pulumi/gcp, @pulumi/azure, @pulumi/kubernetes, pulumi.ComponentResource, pulumi.CustomResource, pulumi.Output, pulumi.Config, pulumi.interpolate, pulumi.all, registerOutputs, StackReference, ComponentResourceOptions, CustomResourceOptions, dynamic.Resource, dynamic.ResourceProvider, LocalWorkspace, InlineProgramArgs, Automation API, CrossGuard, PolicyPack

**When to use:**

• Defining cloud infrastructure in TypeScript with type-safe resource APIs
• Creating reusable infrastructure components with `ComponentResource`
• Managing multi-stack architectures with stack references
• Handling secrets and environment-specific configuration
• Building self-service infrastructure platforms with the Automation API
• Writing compliance policies with CrossGuard policy packs

**When NOT to use:**

• One-off shell scripts that create a single resource (use the cloud CLI directly)
• Projects where the team has no TypeScript experience (consider other IaC language options)

**Key patterns covered:**

• Resource definitions with typed inputs and auto-naming
• ComponentResource encapsulation (parent, naming, registerOutputs)
• Outputs: `apply`, `all`, `interpolate`, and lifting
• Config and secrets management (`Config.require`, `Config.requireSecret`, `pulumi.secret`)
• Stack references for cross-stack data sharing
• Resource options (`dependsOn`, `protect`, `aliases`, `ignoreChanges`, `transforms`)
• Dynamic providers for custom CRUD resources
• Automation API for programmatic stack management
• CrossGuard policy packs for compliance enforcement

---

<philosophy>

Philosophy

Pulumi treats infrastructure as real code, not configuration files. TypeScript gives you type safety, IDE autocompletion, refactoring tools, and the full Node.js ecosystem. Resources are objects, dependencies are automatic, and reuse happens through functions and classes -- not a custom module language.

**Core principles:**

• **Resources are objects**: Every cloud resource is a TypeScript class instance with typed inputs and outputs
• **Dependencies are automatic**: When you pass one resource's output as another's input, Pulumi infers the dependency graph
• **Reuse through components**: `ComponentResource` encapsulates multiple resources into a single logical unit with its own inputs and outputs
• **Outputs are promises**: `Output<T>` represents a value that may not be known until after deployment -- use `apply`, `all`, or `interpolate` to work with them, never unwrap manually
• **State is managed**: Pulumi tracks every resource in state -- changing a logical name or moving a resource between files triggers a delete-and-recreate unless you use `aliases`

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Resource Definitions

Every resource takes a logical name (used for state tracking), an args bag (typed inputs), and optional resource options.

const bucket = new aws.s3.Bucket(
  "data-bucket",
  {
    versioning: { enabled: true },
    lifecycleRules: [
      { enabled: true, expiration: { days: BUCKET_EXPIRY_DAYS } },
    ],
  },
  { protect: true },
); // Prevent accidental deletion

**Key points:** Logical names must be unique per type within a stack. Pulumi auto-appends a random suffix to the physical name to prevent collisions. Use `protect: true` on critical resources. Export outputs for cross-stack consumption.

See [examples/core.md](examples/core.md) for resource naming, auto-naming configuration, and provider options.

---

Pattern 2: ComponentResource Encapsulation

Wrap related resources in a `ComponentResource` to create reusable infrastructure units.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

interface StaticSiteArgs {
  indexDocument?: string;
  errorDocument?: string;
}

class StaticSite extends pulumi.ComponentResource {
  public readonly bucketName: pulumi.Output<string>;
  public readonly websiteUrl: pulumi.Output<string>;

  constructor(
    name: string,
    args: StaticSiteArgs,
    opts?: pulumi.ComponentResourceOptions,
  ) {
    super("myinfra:web:StaticSite", name, args, opts);