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

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
Identify language -- Ask which language the user is working in if not obvious. Pulumi code looks fundamentally different across languages.
Load context -- Read the relevant reference file.
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

Program execution -- Pulumi runs your code (TypeScript, Python, etc.) to declare desired resources
Resource registration -- Each new Resource(...) call registers a resource with the Pulumi engine
Diff -- Engine compares declared resources against the current state
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

pulumi

SKILL.mdplugins/devops/skills/pulumi/SKILL.md