Pulumi Technology Expert

This skill covers Pulumi across all supported versions (3.x). Pulumi is an infrastructure as code platform that uses general-purpose programming languages instead of DSLs. Current version is 3.x.

For foundational IaC concepts (state, drift, idempotency), refer to the parent IaC agent.

How to Approach Tasks

1. Classify the request:

   • Troubleshooting -- Load references/diagnostics.md
   • Architecture -- Load references/architecture.md
   • Best practices -- Load references/best-practices.md
   • Language-specific -- Identify which SDK language (TypeScript, Python, Go, C#, Java) and tailor examples accordingly

2. Identify language -- Ask which language the user is working in if not obvious. Pulumi code looks fundamentally different across languages.

3. Load context -- Read the relevant reference file.

4. Recommend -- Provide code examples in the user's language with explanations.

Core Architecture

How Pulumi Works

┌──────────────────┐     ┌──────────────────┐
│  Pulumi Program  │     │  Pulumi Engine    │
│  (TypeScript,    │────▶│                  │
│   Python, Go,    │     │  - Resource graph │
│   C#, Java)      │     │  - Diff engine   │
└──────────────────┘     │  - Step generator │
                          └──────┬───────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
             ┌──────▼──────┐ ┌──▼──────┐ ┌───▼─────┐
             │  Provider   │ │Provider │ │Provider │
             │  AWS        │ │ Azure   │ │ K8s     │
             └──────┬──────┘ └────┬────┘ └────┬────┘
                    │            │           │
               Cloud APIs    Cloud APIs   K8s API

1. Program execution -- Pulumi runs your code (TypeScript, Python, etc.) to declare desired resources
2. Resource registration -- Each new Resource(...) call registers a resource with the Pulumi engine
3. Diff -- Engine compares declared resources against the current state
4. Deploy -- Engine calls provider CRUD operations to reconcile

Language SDKs

Language	Package	Minimum Version
TypeScript/JavaScript	@pulumi/pulumi	Node.js 18+
Python	pulumi	Python 3.9+
Go	github.com/pulumi/pulumi/sdk/v3	Go 1.21+
C#	Pulumi	.NET 6+
Java	com.pulumi:pulumi	Java 11+
YAML	Native	N/A

Stacks

A stack is an instance of a Pulumi program with its own configuration and state:

# Create stacks per environment
pulumi stack init dev
pulumi stack init staging
pulumi stack init production

# Switch stacks
pulumi stack select production

# Stack-specific configuration
pulumi config set aws:region us-east-1
pulumi config set --secret dbPassword SuperSecret123

Key Concepts

Resources

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

// Create a resource
const bucket = new aws.s3.Bucket("my-bucket", {
    acl: "private",
    tags: { Environment: "production" },
});

// Export outputs
export const bucketName = bucket.id;
export const bucketArn = bucket.arn;

# Python example
import pulumi
import pulumi_aws as aws

bucket = aws.s3.Bucket("my-bucket",
    acl="private",
    tags={"Environment": "production"},
)

pulumi.export("bucket_name", bucket.id)
pulumi.export("bucket_arn", bucket.arn)

Outputs and Inputs

Pulumi uses Output<T> to represent values that are resolved asynchronously (after resource creation):

// Outputs are resolved after the resource is created
const bucket = new aws.s3.Bucket("my-bucket");

// Use .apply() to transform outputs
const bucketUrl = bucket.id.apply(id => `https://${id}.s3.amazonaws.com`);

// Use pulumi.interpolate for string interpolation with outputs
const greeting = pulumi.interpolate`Bucket: ${bucket.id}`;

// Chain outputs
const objectKey = bucket.id.apply(id => {
    return new aws.s3.BucketObject(`${id}-index`, {
        bucket: id,
        key: "index.html",
        content: "<h1>Hello</h1>",
    });
});

Component Resources

Reusable abstractions that group multiple resources:

class VpcComponent extends pulumi.ComponentResource {
    public readonly vpcId: pulumi.Output<string>;
    public readonly subnetIds: pulumi.Output<string>[];

    constructor(name: string, args: VpcArgs, opts?: pulumi.ComponentResourceOptions) {
        super("custom:networking:Vpc", name, {}, opts);

        const vpc = new aws.ec2.Vpc(`${name}-vpc`, {
            cidrBlock: args.cidrBlock,
        }, { parent: this });

        this.vpcId = vpc.id;
        // ... create subnets, route tables, etc.

        this.registerOutputs({
            vpcId: this.vpcId,
        });
    }
}

// Use the component
const network = new VpcComponent("prod", {
    cidrBlock: "10.0.0.0/16",
});

Configuration and Secrets

const config = new pulumi.Config();

// Plain config
const region = config.require("aws:region");
const instanceCount = config.requireNumber("instanceCount");

// Secret config (encrypted in state)
const dbPassword = config.requireSecret("dbPassword");

# Set configuration
pulumi config set instanceCount 3
pulumi config set --secret dbPassword MySecret123

# Configuration stored in Pulumi.<stack>.yaml

State Management

Backends

Backend	Command	Use Case
Pulumi Cloud	Default	Managed state, secrets, RBAC, CI/CD integration
S3	pulumi login s3://bucket	Self-hosted, AWS
Azure Blob	pulumi login azblob://container	Self-hosted, Azure
GCS	pulumi login gs://bucket	Self-hosted, GCP
Local	pulumi login --local	Development only

State Operations

# Export state
pulumi stack export > state.json

# Import state (after manual editing)
pulumi stack import < state.json

# Refresh (detect drift)
pulumi refresh

# Delete a resource from state without destroying
pulumi state delete <urn>

# Unprotect a resource (remove deletion protection)
pulumi state unprotect <urn>

CLI Reference

# Core workflow
pulumi new aws-typescript     # Create new project from template
pulumi up                     # Preview and deploy
pulumi preview                # Preview only (no changes)
pulumi destroy                # Destroy all resources
pulumi refresh                # Detect drift

# Stack management
pulumi stack ls                # List stacks
pulumi stack select <name>     # Switch stacks
pulumi stack output            # Show stack outputs
pulumi stack rm <name>         # Delete stack

# Configuration
pulumi config set <key> <value>
pulumi config set --secret <key> <value>
pulumi config get <key>

# Import existing resources
pulumi import aws:s3/bucket:Bucket my-bucket my-existing-bucket-name

Reference Files

• references/architecture.md — Engine internals, provider system, resource lifecycle, Output/Input model, deployment engine, Pulumi Cloud architecture
• references/best-practices.md — Project organization, component design, testing, CI/CD integration, secret management, multi-stack patterns
• references/diagnostics.md — Common errors (Output resolution, provider auth, state conflicts), debugging techniques, migration from Terraform