pulumi-engineer

name	pulumi-engineer
description	Expert guide for infrastructure as code using Pulumi with TypeScript, Python, and Go. Covers stack management, state backends, component resources, secrets, testing, CI/CD integration, and migration from Terraform. Use when the user asks about pulumi engineer, pulumi engineer best practices, or needs guidance on pulumi engineer implementation. Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"devops cloud automation","category":"devops-cloud","subcategory":"cloud-infrastructure","depends":"","disclaimer":"none","difficulty":"intermediate"}

Pulumi Engineer

You are an expert in Pulumi infrastructure as code. You guide teams through project architecture, stack management, component resource design, state backends, secrets management, testing, and CI/CD integration using real programming languages instead of domain-specific configuration languages.

Core Principles

1. Real languages, real power - Use loops, conditionals, functions, classes, and type systems from your language of choice.
2. Stacks for environments - One project, multiple stacks (dev, staging, prod). Same code, different configuration.
3. Components for abstraction - Build reusable component resources that encapsulate cloud patterns.

Project Structure (TypeScript)

infrastructure/
  Pulumi.yaml                     # Project definition
  Pulumi.dev.yaml                 # Dev stack config
  Pulumi.staging.yaml
  Pulumi.prod.yaml
  index.ts                        # Entry point
  package.json
  tsconfig.json
  src/
    components/                   # Reusable component resources
      vpc.ts
      database.ts
    config/
      settings.ts
  __tests__/
    vpc.test.ts

Stack Configuration

# Pulumi.prod.yaml
config:
  aws:region: us-east-1
  my-infra:environment: production
  my-infra:vpcCidr: "10.0.0.0/16"
  my-infra:instanceType: m5.large
  my-infra:dbPassword:
    secure: AAABAMt1P8K...       # Encrypted secret

Component Resources

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

export interface VpcArgs {
  cidrBlock: string;
  azs: string[];
  enableNat?: boolean;
  tags?: Record<string, string>;
}

export class Vpc extends pulumi.ComponentResource {
  public readonly vpcId: pulumi.Output<string>;
  public readonly publicSubnetIds: pulumi.Output<string>[];
  public readonly privateSubnetIds: pulumi.Output<string>[];

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

     vpc =  aws..(, {
      : args.,
      : ,
      : { ...tags, :  },
    }, parent);

    . = vpc.;
    . = [];
    . = [];

     igw =  aws..(, {
      : vpc., : { ...tags, :  },
    }, parent);

     publicRt =  aws..(, {
      : vpc.,
      : [{ : , : igw. }],
    }, parent);

    args..( {
       pub =  aws..(, {
        : vpc., : ,
        : az, : ,
      }, parent);
      ..(pub.);

       aws..(, {
        : pub., : publicRt.,
      }, parent);

       priv =  aws..(, {
        : vpc., : ,
        : az,
      }, parent);
      ..(priv.);
    });

    .({ : . });
  }
}


 vpc =  (, {
  : config.(),
  : [, , ],
  : { : pulumi.() },
});
  vpcId = vpc.;

State Management

Backend Options

BACKEND               WHEN TO USE                      COMMAND
---------------------------------------------------------------------------
Pulumi Cloud          Default, managed, team features   pulumi login
AWS S3                Self-managed, AWS-only            pulumi login s3://bucket
Azure Blob            Self-managed, Azure-only          pulumi login azblob://ctr
GCS                   Self-managed, GCP-only            pulumi login gs://bucket
Local filesystem      Development only                  pulumi login --local

Stack References (Cross-Stack)

// networking stack exports
export const vpcId = vpc.vpcId;
export const privateSubnetIds = vpc.privateSubnetIds;

// compute stack imports
const netStack = new pulumi.StackReference("myorg/networking/prod");
const vpcId = netStack.getOutput("vpcId");
const subnetIds = netStack.getOutput("privateSubnetIds");

Secrets

pulumi config set --secret dbPassword 'my-s3cr3t'
pulumi stack init prod --secrets-provider="awskms://alias/pulumi-secrets"

const config = new pulumi.Config();
const dbPassword = config.requireSecret("dbPassword");  // Output<string>, encrypted

// Secrets propagate: interpolating a secret produces a secret
const connStr = pulumi.interpolate`postgres://admin:${dbPassword}@${db.endpoint}/mydb`;

Dynamic Providers

const provider: pulumi.dynamic.ResourceProvider = {
  async create(inputs) {
    const resp = await get(`[reference URL] {
      method: "POST", body: JSON.stringify(inputs),
    });
    const data = await resp.json();
    return { id: data.id, outs: { ...inputs, url: data.url } };
  },
  async delete(id) {
    await get(`[reference URL] { method: "DELETE" });
  },
};

export class CustomResource extends pulumi.dynamic.Resource {
  public readonly url!: pulumi.Output<string>;
  constructor(name: string, args: any, opts?: pulumi.CustomResourceOptions) {
    super(provider, name, { url: undefined, ...args }, opts);
  }
}

Testing

Unit Tests

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

pulumi.runtime.setMocks({
  newResource(args) { return { id: `${args.name}-id`, state: args.inputs }; },
  call(args) { return args.inputs; },
});

describe("VPC Component", () => {
  it("should create subnets per AZ", async () => {
    const { Vpc } = await import("../src/components/vpc");
    const vpc = new Vpc("test", { cidrBlock: "10.0.0.0/16", azs: ["us-east-1a", "us-east-1b"] });
    const pubIds = await new Promise(resolve => pulumi.all(vpc.publicSubnetIds).apply(resolve));
    expect(pubIds).toHaveLength(2);
  });
});

Integration Tests (Automation API)

import { LocalWorkspace } from "@pulumi/pulumi/automation";

const stack = await LocalWorkspace.createOrSelectStack({
  stackName: `test-${Date.now()}`, projectName: "test-infra",
  program: async () => {
    const vpc = new aws.ec2.Vpc("test", { cidrBlock: "10.0.0.0/16" });
    return { vpcId: vpc.id };
  },
});
const result = await stack.up();
expect(result.outputs.vpcId.value).toBeDefined();
await stack.destroy();

CI/CD (GitHub Actions)

name: Infrastructure
on:
  pull_request:
    paths: ["infrastructure/**"]
  push:
    branches: [main]
    paths: ["infrastructure/**"]

jobs:
  preview:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
        working-directory: infrastructure
      - uses: pulumi/actions@v5
        with:
          command: preview
          stack-name: myorg/staging
          work-dir: infrastructure
          comment-on-pr: true
        env:
          PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}

  deploy:
    if:   
     
    
        
        
         {   }
         
         
        
        
           
           
           
        
             

Migration from Terraform

pulumi import --from terraform ./terraform.tfstate
pulumi convert --from terraform --language typescript --out ./pulumi-infra
pulumi import aws:ec2/instance:Instance web i-0123456789abcdef0

Concept Mapping

TERRAFORM              PULUMI
---------------------------------------------
.tf files              TypeScript/Python/Go
terraform.tfstate      Pulumi state (backend)
Modules                Component Resources
Variables              Config + function args
Outputs                Stack exports
Data sources           Provider functions
Workspaces             Stacks
terraform plan         pulumi preview
terraform apply        pulumi up

Common Commands

pulumi stack init dev             # Create stack
pulumi stack select prod          # Switch stack
pulumi preview                    # Show diff
pulumi up                         # Apply changes
pulumi up --yes --skip-preview    # Non-interactive (CI)
pulumi destroy                    # Tear down
pulumi refresh                    # Sync state with cloud
pulumi config set key value       # Set config
pulumi config set --secret k v    # Set secret

Production Checklist

PROJECT:
  [ ] Consistent structure with components and tests
  [ ] TypeScript strict mode for type safety
  [ ] Stack config per environment (no hardcoded values)
  [ ] Secrets encrypted via Pulumi Cloud, KMS, or Vault

STATE:
  [ ] Remote backend configured
  [ ] State access restricted to authorized roles
  [ ] Stack references for cross-stack deps

CI/CD:
  [ ] Preview on PRs with comments
  [ ] Deploy on merge to main
  [ ] Separate jobs per stack (staging -> prod)
  [ ] Policy packs for compliance

RESOURCES:
  [ ] protect: true on critical resources
  [ ] retainOnDelete where needed
  [ ] Consistent tagging via helper function
  [ ] Resource naming convention enforced

When to Use

Use this skill when:

• Designing or implementing pulumi engineer solutions
• Reviewing or improving existing pulumi engineer approaches
• Making architectural or implementation decisions about pulumi engineer
• Learning pulumi engineer patterns and best practices
• Troubleshooting pulumi engineer-related issues

Do NOT use this skill when:

• The question is about a fundamentally different technology domain
• A more specific sibling skill covers the exact topic needed
• The user needs a complete hands-on tutorial rather than expert guidance

Output Format

# Pulumi Engineer Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]

Example

Input: "Help me implement pulumi engineer for a medium-scale production application"

Output: A structured analysis covering current state assessment, recommended pulumi engineer approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

Edge Cases

• Legacy system integration: When pulumi engineer must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
• Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
• Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
• Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities