Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท CI/CD and Operations

The Pulumi Automation API: Infrastructure as a Library

Drive Pulumi from your own code with the Automation API: inline programs, LocalWorkspace, stack config, up, outputs, events, error handling and self-service platform patterns.

Normally you run Pulumi through the CLI: pulumi new, pulumi up. The Automation API turns the same engine into a library. Your own program can create stacks, set config, run updates, read outputs and destroy resources, all in code, with typed results and error handling instead of shell scripts and string parsing.

That unlocks things the CLI is awkward for: self-service portals ("create a database for my team"), SaaS back ends that provision a stack per customer, integration test harnesses, and custom CLIs for your company. The Automation API needs the Pulumi CLI and a backend, so the real code here is read-only. The stand-in mimics its structure so you can learn the design.

Two ways to use it

  • Inline program: the infrastructure is a function inside your application. No project folder needed.
  • Local program: point at an existing Pulumi project directory (LocalWorkspace.createOrSelectStack({ stackName, workDir })).

Available in Node.js/TypeScript, Python, Go, .NET and Java.

TypeScript
import { LocalWorkspace, InlineProgramArgs } from "@pulumi/pulumi/automation";
import * as aws from "@pulumi/aws";

// 1. the infrastructure as a function
const pulumiProgram = async () => {
  const bucket = new aws.s3.BucketV2("customer-data");
  return { bucketName: bucket.id };         // becomes stack outputs
};

// 2. the stack identity
const args: InlineProgramArgs = {
  stackName: "customer-42",
  projectName: "tenant-buckets",
  program: pulumiProgram,
};

// 3. create or select, configure, deploy
const stack = await LocalWorkspace.createOrSelectStack(args);
await stack.workspace.installPlugin("aws", "v6.50.0");
await stack.setConfig("aws:region", { value: "eu-central-1" });
await stack.setConfig("dbPassword", { value: "s3cret", secret: true });

const preview = await stack.preview({ onOutput: console.info });
console.log(preview.changeSummary);           // { create: 2, ... }

const result = await stack.up({ onOutput: console.info });
console.log("bucket:", result.outputs.bucketName.value);
console.log("summary:", result.summary.kind, result.summary.result);

// 4. later
await stack.refresh();
await stack.destroy();
await stack.workspace.removeStack("customer-42");

Building blocks

Piece Purpose
LocalWorkspace Runs the CLI in a working directory; creates or selects stacks
Stack Object for one stack: up, preview, refresh, destroy, outputs(), setConfig, history(), exportStack/importStack
onOutput Streams text output as it is produced
onEvent Receives structured engine events (resource pre/post, diagnostics)
workspace.listStacks() Enumerate stacks, for dashboards and janitors
Stack.cancel() Cancel an in-progress update

The workspace needs a login and secrets provider, exactly like the CLI. For a multi-tenant service, use a self-managed backend or Pulumi Cloud organizations, and pass a projectSettings and secretsProvider per stack so each tenant's secrets are encrypted separately if you need that isolation.

Patterns

  1. Stack per tenant: customer-${id} stacks created on sign-up, all from one inline program. Operations apply to a fleet with a loop and a concurrency limit.
  2. Self-service API: an HTTP endpoint validates a request, runs up for a fixed program with user-supplied parameters (stored as config), and returns outputs. Keep the program fixed and the inputs validated; never let users submit arbitrary Pulumi code.
  3. Ordered multi-stack rollouts: deploy network, then data, then app, reading outputs of one and passing them as config to the next, or use stack references.
  4. Test harness: create a stack, up, check behavior, destroy in finally (see Integration Testing and Ephemeral Stacks).
  5. Wrappers with guardrails: a company CLI that sets tags, regions and policies, then calls Automation API.

Concurrency and errors

Updates to one stack are serialized by the backend lock; updates to different stacks can run in parallel (watch cloud API rate limits). Errors are exceptions you can catch and classify:

  • ConcurrentUpdateError: the stack is locked.
  • StackAlreadyExistsError, StackNotFoundError: lifecycle problems.
  • CommandError (and subtypes such as InvalidVersionError): failed CLI command; the message carries the engine output.

A robust service reports these distinctly: retry later on a lock, surface the message to the user on a validation failure, alert on others.

Stand-in: a workspace, stacks and an inline program

The next stand-in is not Pulumi but has the same shape: a workspace creates stacks, a stack has config and outputs, and up runs an inline program against a fake cloud, reports a change summary and throws a typed error when a stack is busy.

Node.js Stand-in: a mini Automation API

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The Promise.allSettled line shows the lock behavior: of two simultaneous up calls on the same stack, one succeeds and one gets ConcurrentUpdateError.

Stand-in: fleet rollout with a concurrency limit

A tenant-per-stack service often has to apply a change to hundreds of stacks. Doing them all at once exhausts cloud API rate limits; doing them one at a time is slow. A simple worker pool balances both and records failures instead of stopping.

Node.js Stand-in: rolling an update across many stacks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Security and operations notes

  • The process that runs the Automation API holds powerful credentials. Run it with a dedicated, least-privilege role, and keep its network exposure small.
  • Validate every input that reaches config or the program. A tenant name used in resource names must match a strict pattern.
  • Streams from onOutput can contain sensitive values if you print them; secrets are masked by the engine, but your own logging may not be.
  • Updates take minutes. Run them on a job queue and report status, instead of holding an HTTP request open.
  • Store the stack name to tenant mapping in your own database, and run a janitor for stacks of deleted tenants.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an inline program in the Automation API?

    An inline program is a function passed to LocalWorkspace, so no separate Pulumi project directory is needed.
  2. 2. Two simultaneous updates are started on the same stack. What happens?

    The backend lock serializes updates for one stack, so the second caller is rejected.
  3. 3. Which use case fits the Automation API best?

    Programmatic, repeatable provisioning from application code is the core use case, alongside test harnesses and custom CLIs.
  4. 4. Why validate user input before it reaches the program or config in a self-service portal?

    User-controlled values flow into real cloud resources. Strict validation protects names, scope and permissions.

Summary

  • The Automation API runs the Pulumi engine from code: stacks, config, up, preview, refresh, destroy and outputs.
  • Use inline programs for application-embedded infrastructure or point at a local project directory.
  • Updates to one stack are serialized; handle typed errors for locks and missing stacks.
  • Good patterns: stack per tenant, self-service APIs with fixed programs, ordered multi-stack rollouts and test harnesses.
  • Treat the automation process as a privileged service: least privilege, strict input validation and a job queue.

Next: Safe Operations: Upgrades, Rollbacks and Day-2 Tasks