The Complete Pulumi Guide

This is part one of three. It covers everything you need to do real work with Pulumi, not a teaser. By the end you can install the tool, create a project, describe cloud infrastructure in a programming language you already know, preview what will change before it changes, deploy it, keep secrets out of your repository, run the same program for several environments, read the errors Pulumi prints, and tear everything down so you are not billed for it. Mid-level and Senior take the same topics further; nothing here is thrown away.

Each section ends with a Try it task. Do them as you go. They take a few minutes each, and infrastructure as code only sticks once you have watched a preview, a deployment, and a destroy with your own eyes. The guide is written against Pulumi CLI v3.266.0 (released 30 September 2026). Pulumi ships a new minor version about every week, so read "v3.26x or later" wherever a version matters, and never copy a patch version out of a blog post into your own notes.

What Pulumi is, and the problem it solves

Pulumi is a tool for creating and changing cloud infrastructure (servers, networks, databases, storage buckets, Kubernetes clusters, DNS records) by writing a program in a general-purpose language: TypeScript, JavaScript, Python, Go, C#, Java, or YAML. You describe the infrastructure you want. Pulumi compares that description with what it created last time, shows you the difference, and on your approval makes the cloud match.

That diagram is the entire idea, and the rest of this guide is detail about each box. The word that matters most is declarative in intent, imperative in expression. Your code is ordinary code (it has variables, loops, functions, and imports) but running it does not create a server. Running it tells Pulumi "these are the resources that should exist." Pulumi then works out what to do.

Why does anyone need this? Think about how infrastructure is created without it. Someone opens the cloud provider's web console, clicks through a wizard to create a storage bucket, ticks a few options, and moves on. Two weeks later a colleague needs the same bucket in a second environment and cannot remember which options were ticked. A month later the bucket is misconfigured and nobody knows whether that was always so or whether someone changed it. The infrastructure exists, but the knowledge of how it was made lives in someone's memory and in a console history nobody reads.

Infrastructure as code moves that knowledge into files you commit. The bucket's settings are lines in a repository, so they are reviewed in a pull request, versioned, diffed, and reproducible. To make a second environment you run the same program again. To find out who changed a setting you run git log. To recover from a disaster you run the program against an empty account.

What you need to follow along: a terminal, a programming language runtime (this guide uses TypeScript on Node.js, with Python shown alongside wherever the difference matters), and ideally an AWS account, although every concept works the same on Azure, Google Cloud, or Kubernetes, and a section below shows how to practise with no cloud account at all.

What came before, and where Pulumi fits

Three generations of tooling led here, and knowing them helps you understand the choices Pulumi made and helps in interviews, where the comparison comes up constantly.

Scripts. The first automation was shell scripts calling the cloud provider's command line: aws ec2 run-instances .... Scripts are imperative: they describe steps, not the desired outcome. Run one twice and you get two servers. Nothing records what the script made, so cleaning up means writing a second script. There is no preview and no notion of "the difference between what exists and what I want."

Template languages. Tools such as AWS CloudFormation (JSON and YAML templates) and Terraform (its own language, HCL) introduced the declarative model: you list the resources you want, and the tool computes the steps. They also introduced state, the tool's record of what it created, which makes preview, update, and delete possible. Their weakness is that the template language is deliberately limited. Loops, conditionals, and reuse exist but are awkward, and sharing logic means learning a parallel set of concepts (modules, count, for_each, functions) that your application language already does better.

General-purpose languages. Pulumi keeps the declarative model and the state, and replaces the template language with real languages. A loop is a for loop. A reusable building block is a class or a function. A dependency is an npm or pip package. You can unit-test a component with the test framework you already use. The trade-off is honest: a full programming language can do more, including things that make infrastructure harder to reason about. Section after section below comes back to keeping programs simple.

Terraform and OpenTofu remain widely used, and you will meet them in most job descriptions. They are covered in the Terraform guide. Pulumi can also read Terraform: it can convert HCL to a Pulumi program and can use Terraform providers. The two tools are cousins, not enemies, and the vocabulary you learn here (state, plan, apply) maps across with small renames.

One more neighbour deserves a mention. Pulumi also runs on Kubernetes (you can create Deployments and Services with it) and works alongside Helm, which is covered in the Helm guide. Whether you describe a cluster's workloads with Pulumi, with Helm, or with Kustomize is a team decision, and Pulumi can drive all three.

The mental model: project, program, stack, resource

Pulumi has a small vocabulary, and nearly every confusing moment for a beginner is one of these words used loosely. Learn the four nouns below precisely and most of the tool makes sense.

A project is a directory that contains a file named Pulumi.yaml. That file holds the project's name, the language runtime it uses, and a short description. The program is the code in the directory, index.ts or __main__.py or main.go. The project name may contain letters, digits, hyphens, underscores, and periods.

A stack is an isolated, independently configurable instance of a program. The code is one; the stacks are many. A typical project has a dev stack, a staging stack, and a prod stack, each with its own configuration (a small instance size in dev, a large one in prod) and each with its own state. Deploying dev does not touch prod, even though both come from the same code. Stack names may contain letters, digits, hyphens, underscores, and periods. The fully qualified name of a stack is organization/project/stack, for example acme/website/dev, and you will see it in the console and in commands that refer to another stack.

A resource is the declaration of one cloud object: a bucket, a virtual machine, a DNS record. In code it looks like new aws.s3.Bucket("my-bucket"). Resources come in two kinds. A custom resource is managed by a provider and maps to exactly one cloud object. A component resource is a logical grouping of other resources that you define yourself, for example "a web service" made of a load balancer, a container service, and a DNS record. Components appear later in this guide.

State is Pulumi's memory. After each deployment, Pulumi records every resource it manages: its inputs, its outputs, its dependencies, and which provider created it. The next time you run, Pulumi compares your program's declarations against this record. That comparison is the source of everything useful: a preview can tell you what will change because it knows what exists, and a deletion happens when you remove a resource from code because Pulumi remembers that it was there.

Three supporting words come up constantly, so define them now.

A provider is the plugin that knows how to talk to one cloud or service: aws, azure-native, gcp, kubernetes, cloudflare, random, and several hundred others. Your program says "I want a bucket"; the AWS provider knows which API calls create one. Providers are downloaded automatically the first time they are needed and cached under ~/.pulumi/plugins. Each provider also ships as a package for your language, such as @pulumi/aws on npm or pulumi_aws on PyPI, which gives you typed classes and editor autocompletion.

The backend is where state is stored. By default that is Pulumi Cloud, a hosted service with a free individual tier: it stores state, locks a stack while an update is running so two people cannot collide, keeps a history of every update, and encrypts secrets. The alternative is a DIY backend: state as files on your own disk, in an S3 bucket, in Azure Blob Storage, or in Google Cloud Storage. Both are covered in the next sections.

Config is the set of per-stack settings: which region, how large an instance, which domain name. It lives in a file named Pulumi.<stack>.yaml next to your program, for example Pulumi.dev.yaml.

How a Pulumi run actually works

Knowing what happens when you type pulumi up turns many later errors from mysteries into things you can predict, so this section is worth the five minutes.

Your program is not run by Pulumi's engine directly. Three separate processes cooperate, all on your own machine, talking to each other over a local connection (gRPC on 127.0.0.1).

1. The CLI and its deployment engine. This is the pulumi command you typed. The engine is the brain: it decides what to create, update, replace, or delete.
2. The language host. A helper program named like pulumi-language-nodejs or pulumi-language-python. It starts your program using your installed Node.js or Python and watches it run.
3. One or more resource providers. The plugins that make the real API calls to AWS, Azure, or whichever service is involved.

When your code executes new aws.s3.Bucket("my-bucket"), the language SDK does not call AWS. It sends a registration ("there should be a bucket called my-bucket with these arguments") to the engine. The engine reads the last recorded state, decides whether this bucket is new, changed, or unchanged, and if it needs to act, asks the provider to do so. The provider makes the API call and returns the result, which the engine records in state and hands back to your program as outputs.

Two consequences follow, and both cause real confusion if nobody tells you.

Your program's side effects are not infrastructure. If your code calls console.log, reads a file, or fetches a web page, that happens on your machine each time the program runs, including during preview. Only resources you register are managed. This is why you should keep programs free of side effects: a program that writes a file or sends an email will do so on every preview.

Anything removed from the code is deleted from the cloud. The engine deletes resources that exist in state but were not registered in this run. That is the feature (delete a resource from code, run pulumi up, it is gone) and also the trap: commenting out a block of code is a deletion request. The preview shows it, which is one of the many reasons the preview is not optional reading.

If you ever see commands hang with no output on a work laptop, this architecture is usually why: a corporate proxy is intercepting the local 127.0.0.1 traffic between the three processes. Add 127.0.0.1 and localhost to your NO_PROXY setting. Pulumi also needs to reach https://api.pulumi.com (and app.pulumi.com for the console), so a firewall that blocks them will stall a Pulumi Cloud login.

Installing Pulumi and checking your setup

Pulumi needs about 2 GHz of CPU, 4 GB of RAM, and 1 GB of disk. On macOS you need Ventura (13) or later; on Windows, version 8 or later.

On macOS, the official Homebrew tap is the recommended route:

brew install pulumi/tap/pulumi

On Linux (and macOS without Homebrew) use the install script, which puts the CLI in ~/.pulumi/bin and edits your shell profile so the directory is on your PATH:

curl -fsSL https://get.pulumi.com | sh

You can pin a version by adding -s -- --version 3.266.0 after sh. On Windows, use either package manager:

winget install pulumi

choco install pulumi

Now verify it worked, and look at what you have:

pulumi version

v3.266.0

pulumi about

pulumi about prints the CLI version, the plugins installed, the language runtime it detects, the current backend, and the host operating system. It is also the first thing to paste into a support question or an issue report.

Pulumi does not include your language. Install it separately:

• Node.js for TypeScript and JavaScript. Since CLI 3.249.0 the Pulumi Node.js SDK requires Node.js 22 or later, and Node 20 no longer works. Use a current LTS release (22 or 24). A typical failure on an old laptop is a cryptic error right after pulumi up starts; node --version tells you if that is the cause. Keep TypeScript at version 6 or earlier: TypeScript 7 is not yet compatible with how Pulumi compiles your program.
• Python, any currently supported version. Pulumi can use pip, poetry, or uv to manage dependencies, and pip with a virtual environment is the default.
• Go, any currently supported version.
• YAML needs nothing extra: the YAML runtime ships inside the CLI. It is a fine way to start if you only want to see the engine working, although most of this guide's ideas (loops, functions) need a real language.

Finally, install shell completion so you can tab-complete commands. Generate the script for your shell (bash, zsh, fish, or powershell) and follow your shell's instructions for loading it:

pulumi gen-completion zsh

Everything Pulumi stores on your machine (downloaded plugins, workspace files, templates, stored logins, logs) lives under ~/.pulumi by default. You can move that directory with the PULUMI_HOME environment variable, which is useful in CI or on a machine with a small home disk.

Logging in: where your state lives

Before Pulumi can remember anything it needs somewhere to store state. You choose this once with pulumi login, and the choice is remembered on your machine.

pulumi login

With no argument, this signs you in to Pulumi Cloud. A browser window opens (or, on a machine without one, you paste an access token), and a free individual account is created if you do not have one. Confirm who you are and where you are connected with:

pulumi whoami -v

The output lists your user name, the organizations you belong to, and the backend URL. Pulumi Cloud is the recommended starting point for a beginner for practical reasons. It locks a stack while an update runs, it keeps a browsable history of every update with a diff you can open in the browser, it encrypts secrets with a per-stack key, and it needs nothing set up beforehand. pulumi console opens the page for your current stack.

If you would rather not create an account, or you work where sending state to a third party is not allowed, use a DIY backend. The simplest is a local folder:

pulumi login --local

State is then written under ~/.pulumi on your machine. That is fine for learning, and useless for a team, because nobody else can see it. For a team without Pulumi Cloud the same command accepts a cloud bucket, for example pulumi login s3://my-team-pulumi-state, and Azure Blob Storage and Google Cloud Storage work the same way. A DIY backend is free, but you give up the hosted conveniences: there is no history page, no role-based access, and Pulumi ESC (covered in later levels) does not work with it. The Pulumi documentation also warns that a DIY backend cannot transparently recover from certain kinds of partial failure, which is why most teams choose Pulumi Cloud unless a rule forbids it.

Your program also needs credentials for the cloud you are building on, and these are separate from Pulumi's login. For AWS, Pulumi uses the same credential chain as the AWS command line: environment variables such as AWS_ACCESS_KEY_ID, or a named profile in ~/.aws/credentials, or a single sign-on session. If aws sts get-caller-identity works in your terminal, Pulumi's AWS provider will find the same identity. Azure uses az login, and Google Cloud uses gcloud auth application-default login. You will see in a moment that a missing credential shows up as an error from the provider during pulumi up, not as a Pulumi login problem.

Your first project, step by step

The fastest way to start is a template, a ready-made project for a given cloud and language. Create an empty folder and run pulumi new inside it:

mkdir hello-pulumi && cd hello-pulumi
pulumi new aws-typescript

If you run pulumi new with no template name, recent versions ask two plain questions: which cloud provider, and which language. (Before CLI 3.258 it listed every template; before 3.257 it also offered an AI mode, which has been retired. If an older tutorial shows different prompts, the tutorial is out of date.) Since 3.259 the interactive flow asks you to confirm the project name, stack name, and initial configuration together in one step rather than one prompt per value. Accept the defaults (project name hello-pulumi, stack name dev) and set the AWS region to one near you when asked.

When the command finishes, look at what it created:

ls

Pulumi.dev.yaml  Pulumi.yaml  index.ts  node_modules  package.json  tsconfig.json

Each file has one job.

Open Pulumi.yaml. It is short:

name: hello-pulumi
description: A minimal AWS TypeScript Pulumi program
runtime:
  name: nodejs
  options:
    packagemanager: npm

The runtime key tells the CLI which language host to launch. Now open index.ts, which is your program. The template's content varies between releases, so replace it with this small, stable version:

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

// Declare one storage bucket.
const bucket = new aws.s3.Bucket("my-bucket");

// Export values so you can read them after deployment.
export const bucketName = bucket.id;

Read it line by line. The first two lines import the Pulumi core library and the AWS provider library. The next line creates a resource: new aws.s3.Bucket("my-bucket"). The first argument, "my-bucket", is the resource's logical name, the name Pulumi uses to identify it inside the stack. It is not necessarily the bucket's name in AWS (more on that shortly). The last line exports the bucket's ID as a stack output, so that after a deployment you can read it.

The Python equivalent, in __main__.py, is nearly the same:

import pulumi
import pulumi_aws as aws

bucket = aws.s3.Bucket("my-bucket")

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

Before deploying, make sure dependencies and plugins are installed. pulumi new usually does this, but running it again is harmless and is the fix when you clone someone else's project:

pulumi install

Now ask Pulumi what it would do, without doing it:

pulumi preview

Previewing update (dev):
     Type                 Name              Plan
 +   pulumi:pulumi:Stack  hello-pulumi-dev  create
 +   └─ aws:s3:Bucket     my-bucket         create

Resources:
    + 2 to create

Two resources to create: the bucket you declared, and a stack resource that Pulumi adds automatically as the root of everything in the stack. Now make it real:

pulumi up

Pulumi runs the preview again, then asks for confirmation with a menu: yes, no, or details. Choose details once to see the full property list, then yes. After a few seconds:

Updating (dev):
     Type                 Name              Status
 +   pulumi:pulumi:Stack  hello-pulumi-dev  created
 +   └─ aws:s3:Bucket     my-bucket         created

Outputs:
    bucketName: "my-bucket-d7c2fa0"

Resources:
    + 2 created

Duration: 6s

Notice the bucket's real name: my-bucket-d7c2fa0. You asked for my-bucket and Pulumi added a random suffix. That is auto-naming, and it is deliberate: S3 bucket names are global across all AWS accounts, so a fixed name like my-bucket would collide with someone else's. Auto-naming also lets Pulumi create a replacement before deleting the old one, which a fixed name would prevent. You can read the real name any time:

pulumi stack output bucketName

Run pulumi up again without changing anything. The preview says Resources: 2 unchanged. That is the declarative model working: Pulumi compared your program to its state, found no difference, and did nothing. Run your program a hundred times and you still have one bucket.

Reading a preview: the four symbols

The preview is the most important output Pulumi produces, and reading it fluently is the skill that separates people who use Pulumi safely from people who hit yes and hope. Every line carries a symbol.

There are two more you will meet, = for an import and > for a read of an existing object, but these four cover nearly everything.

Make a change and see them. Add tags to the bucket in index.ts:

const bucket = new aws.s3.Bucket("my-bucket", {
  tags: { team: "data-platform", env: "dev" },
});

Run pulumi preview --diff. The --diff flag shows property-level changes instead of a summary:

  pulumi:pulumi:Stack: (same)
    ~ aws:s3/bucket:Bucket: (update)
        [id=my-bucket-d7c2fa0]
      ~ tags: {
          + env : "dev"
          + team: "data-platform"
        }
Resources:
    ~ 1 to update
    1 unchanged

A ~ means the bucket can be changed in place and nothing is destroyed. The properties that changed are listed with their own symbols. Apply it with pulumi up.

Now the dangerous one. Some properties cannot be changed on an existing cloud object; the provider must destroy and recreate it. Pulumi calls this a replace, and the preview shows +- along with which property forced it. For example, changing the availability zone of a virtual machine or the name of a database forces a replacement. A replace of a stateless web server is fine. A replace of a database means data loss unless you have planned for it.

For a machine-readable version in scripts, pulumi preview --json and --output json print a structured summary. For human review in a pull request, most teams post the --diff text to the pull request. That habit, preview on every change, is the single most valuable thing Pulumi gives you over clicking in a console.

Inputs and outputs: the idea that trips everyone

Every beginner hits the same wall within the first hour, and this section exists so you hit it gently. The wall is the Output type.

When you declare a resource, some of its values are known immediately because you wrote them: the tags above. Others are only known after the cloud creates the thing: the bucket's ARN, a virtual machine's IP address, a database's endpoint. Your program runs before the cloud object exists, so it cannot hold that value as a plain string. Pulumi wraps it in an Output: a container for a value that will arrive later, similar to a Promise or a Future in other languages.

const bucket = new aws.s3.Bucket("my-bucket");

// bucket.arn is not a string. It is Output<string>.
export const arn = bucket.arn;

An Output carries three things: the eventual value, the list of resources it depends on, and a flag saying whether it is secret. During pulumi preview, outputs of resources that do not exist yet are unknown, and the engine knows that. This is how it draws the dependency graph: if resource B uses an output of resource A, Pulumi knows to create A first, without you writing anything.

Because the value is not available yet, you cannot use it like a string. The mistake looks innocent:

// WRONG: building a string from an Output
const url = `https://${bucket.bucketDomainName}/index.html`;

Pulumi catches it and prints a message like this:

Calling [toString] on an [Output<T>] is not supported.
To get the value of an Output<T> as an Output<string> consider either:
1: o.apply(v => `prefix${v}suffix`)
2: pulumi.interpolate `prefix${v}suffix`

In Python the same mistake reads Calling __str__ on an Output[T] is not supported. Read it as: "that value is not a string, it is a promise of one, and your template literal turned it into the text Calling toString... instead." The fix is one of three tools.

pulumi.interpolate (TypeScript) builds a string from Outputs, the way a template literal builds a string from values. It is the tool you will use most:

export const url = pulumi.interpolate`https://${bucket.bucketDomainName}/index.html`;

apply runs a function when the value becomes known and returns a new Output. Use it when you need to transform a value rather than just embed it:

export const upperName = bucket.bucket.apply(name => name.toUpperCase());

pulumi.all combines several Outputs so you can use them together:

export const summary = pulumi
  .all([bucket.bucket, bucket.region])
  .apply(([name, region]) => `${name} lives in ${region}`);

In Python the same three tools are Output.format, .apply, and Output.all:

url = pulumi.Output.format("https://{0}/index.html", bucket.bucket_domain_name)
upper_name = bucket.bucket.apply(lambda name: name.upper())
summary = pulumi.Output.all(bucket.bucket, bucket.region).apply(
    lambda args: f"{args[0]} lives in {args[1]}"
)

Notice that the f-string in the last line is inside the apply callback, where args holds real strings. That is the rule: inside apply, the values are plain; outside it, they are Outputs.

A resource's inputs, by contrast, accept either a plain value or an Output. You can pass bucket.id directly as an argument to another resource, and Pulumi unwraps it for you. That is why you rarely need apply just to connect resources: you only need it when you want to compute something.

Names: logical, physical, and the URN

Pulumi tracks every resource by a URN (uniform resource name), a string that is unique within a stack:

urn:pulumi:dev::hello-pulumi::aws:s3/bucket:Bucket::my-bucket

Read it left to right: the stack (dev), the project (hello-pulumi), the resource's type (aws:s3/bucket:Bucket, a package, a module, and a type), and finally the logical name you gave it (my-bucket). The logical name is what you wrote in code. The physical name is the name in the cloud (my-bucket-d7c2fa0). The URN is how the engine decides "this is the same resource as last time," and that has a consequence beginners hit early.

If you change a resource's logical name, Pulumi sees a deletion and a creation. The old URN is gone from your code, so the old resource is deleted; the new URN is new, so a new one is created. Rename "my-bucket" to "website-bucket" and the preview shows +-: a new bucket and the old bucket deleted, along with its contents. If you truly want to rename without recreating, add the aliases resource option telling Pulumi "this is the same thing as the old name," which is covered in the options section.

The same mechanism causes another classic error when you create resources in a loop and forget to make their names unique:

error: Duplicate resource URN 'urn:pulumi:dev::hello-pulumi::aws:s3/bucket:Bucket::logs'; try giving it a unique name

Two resources of the same type and the same logical name have the same URN. Give each a distinct name, such as `logs-${i}` or `${name}-logs`.

Auto-naming, the random suffix, can be controlled. The default is the right choice for learning. When you need predictable names (a DNS name, a bucket referenced by another system), set the physical name yourself with the resource's name argument, for example bucket: "acme-dev-logs", and accept that a fixed name prevents Pulumi from creating a replacement before deleting the old one. A project-wide policy is also available through the pulumi:autonaming configuration setting, which is a topic for the mid-level guide.

Stacks: one program, several environments

A stack is how one program becomes several environments. You already have one: dev. List stacks with:

pulumi stack ls

NAME  LAST UPDATE    RESOURCE COUNT  URL
dev*  2 minutes ago  2               https://app.pulumi.com/you/hello-pulumi/dev

The asterisk marks the currently selected stack, the one every command acts on. Create a second stack and switch to it:

pulumi stack init staging
pulumi stack select dev

stack init creates and selects the new stack; stack select switches between existing ones. Each stack has its own state, its own config file (Pulumi.staging.yaml), and its own set of real cloud resources. Running pulumi up while staging is selected creates a second bucket, entirely separate from the dev one.

Stacks are also where you look at outputs. The exports from your program belong to the stack:

pulumi stack output
pulumi stack output bucketName
pulumi stack output --json

Values that Pulumi knows are secret are masked unless you pass --show-secrets.

Other stack commands you will use in your first month:

A stack can only be removed once it has no resources. Destroy first, then stack rm. Pulumi refuses otherwise, which protects you from orphaning real infrastructure. If you do want to remove everything in one go, pulumi destroy --remove destroys the resources and then removes the stack and its config file.

Configuration: making one program behave differently per stack

If two stacks were identical there would be no point in two stacks. Config holds the values that differ: a region, an instance size, a feature flag, a domain. It lives in Pulumi.<stack>.yaml and is managed with pulumi config.

pulumi config set aws:region me-central-1
pulumi config set bucketPrefix acme-dev
pulumi config

KEY               VALUE
aws:region        me-central-1
hello-pulumi:bucketPrefix  acme-dev

This edits Pulumi.dev.yaml, which you commit to git:

config:
  aws:region: me-central-1
  hello-pulumi:bucketPrefix: acme-dev

Keys have a namespace: aws:region belongs to the AWS provider, and a bare key such as bucketPrefix is stored under your own project's name (hello-pulumi:bucketPrefix). Provider settings use the provider's name, and your own settings use the project's.

Read config in your program with the Config class:

const config = new pulumi.Config();
const prefix = config.require("bucketPrefix");          // fails if unset
const retentionDays = config.getNumber("retentionDays") ?? 30; // optional, with a default

const bucket = new aws.s3.Bucket("my-bucket", {
  bucketPrefix: `${prefix}-`,
  tags: { retention: String(retentionDays) },
});

config = pulumi.Config()
prefix = config.require("bucketPrefix")
retention_days = config.get_int("retentionDays") or 30

The methods follow a pattern you can memorise. require fails with a helpful message if the key is missing; get returns nothing (undefined or None) if it is missing; and there are typed variants (getNumber, getBoolean, getObject in TypeScript; get_int, get_bool, get_object in Python). Use require for values the program cannot work without, and get with a default for optional ones.

When a required value is missing you see:

error: Missing required configuration variable 'hello-pulumi:bucketPrefix'
	please set a value using the command `pulumi config set bucketPrefix <value>`

Pulumi even prints the command that fixes it. Set the value per stack; each stack has its own:

pulumi config set bucketPrefix acme-staging --stack staging

Secrets: passwords that never appear in plain text

Some config values are sensitive: database passwords, API tokens, private keys. Committing them to git in plain text is how credentials leak. Pulumi's answer is to encrypt them.

pulumi config set --secret dbPassword 'S3cr3t-Value!'

Look at what was written to Pulumi.dev.yaml:

config:
  aws:region: me-central-1
  hello-pulumi:dbPassword:
    secure: v1:xYz1Abc...:Q8m2...

The value is ciphertext. The file is safe to commit, and only someone with access to the stack's encryption key can read it. With Pulumi Cloud, the key is managed per stack by the service. With a DIY backend the default is a passphrase you choose, which you must supply through the PULUMI_CONFIG_PASSPHRASE environment variable (or a file named in PULUMI_CONFIG_PASSPHRASE_FILE) in non-interactive contexts. The other options, cloud key management services such as AWS KMS, are for later levels.

Read a secret in your program with the Secret variants:

const dbPassword = config.requireSecret("dbPassword"); // Output<string>, flagged secret

db_password = config.require_secret("dbPassword")

The result is an Output carrying a secret flag, and that flag is contagious: any value computed from a secret is also secret. When you pass it to a resource, Pulumi encrypts it in state as well, and in the CLI it prints [secret] instead of the value.

Outputs:
    dbPassword: [secret]

To view it deliberately, pulumi config get dbPassword prints the plaintext of one config value, and pulumi stack output --show-secrets shows secret outputs. Use them knowing that your terminal history and screen-sharing software can see the result.

Practising without a cloud account

You do not need an AWS account to learn Pulumi's workflow. Providers exist for things that are not clouds. The random provider, for instance, creates random values and records them in state, which is enough to watch preview, update, replace, and destroy without paying for anything.

Create a project with the local backend:

pulumi login --local
mkdir sandbox && cd sandbox
pulumi new typescript --yes
npm install @pulumi/random

The typescript template is a cloud-free starter, and --yes accepts the defaults. Because a local backend uses a passphrase, set PULUMI_CONFIG_PASSPHRASE in your shell first, or the command prompts for one. Replace index.ts:

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

const pet = new random.RandomPet("server-name", { length: 2 });
const id = new random.RandomId("deploy-id", { byteLength: 4 });

export const petName = pet.id;
export const deployId = id.hex;

Run pulumi up and you get a stack with two resources and two outputs, for example petName: "quiet-heron". Now change length: 2 to length: 3 and preview. You will see the replacement (+-) because the provider cannot change the length of an existing random value, only make a new one. That is a safe, free demonstration of the most important lesson in the preview section.

Everything in the rest of this guide, apart from the cloud-specific resources, works the same way in this sandbox.

The everyday commands, grouped by what you are trying to do

You have now met most of the day-to-day surface area. Here it is grouped by intent, because you will look things up by what you want, not by command name.

Starting and setting up

Seeing what would happen, and making it happen

Inspecting

Configuring

Cleaning up

Two habits make these commands pleasant. First, use --help liberally: pulumi up --help lists every flag. Second, notice that most commands accept --stack (short -s) and --cwd (short -C) so you can point them at a stack or folder without changing your shell's state.

Resources and their options

So far you have created resources with a name and an arguments object. There is a third argument, the resource options, that changes how Pulumi treats the resource rather than what the cloud object looks like. You will use a handful of them early.

const logs = new aws.s3.Bucket("logs");

const site = new aws.s3.Bucket("site", {
  tags: { purpose: "website" },
}, {
  dependsOn: [logs],   // create after logs
  protect: true,       // refuse to delete
});

The options you should know on day one:

dependsOn is rarely needed. Pulumi builds the dependency graph automatically from Outputs, so if resource B uses a.id, A is created first. Reach for dependsOn only when the dependency is real but invisible in the values.

protect is worth adopting immediately for anything stateful. With it on, pulumi destroy or a removal from code fails with a message like this:

error: resource "urn:pulumi:dev::hello-pulumi::aws:s3/bucket:Bucket::site" cannot be deleted because it is protected.
To unprotect the resource, either remove the `protect` flag from the resource in your Pulumi program and run `pulumi up`, or use the command: `pulumi state unprotect urn:pulumi:dev::hello-pulumi::aws:s3/bucket:Bucket::site`

That error is the feature working, not a bug. Resources you adopt with the pulumi import command are protected by default for the same reason.

provider becomes essential when you need two regions. The default provider reads the aws:region config; an explicit provider overrides it for chosen resources:

const dubai = new aws.Provider("uae", { region: "me-central-1" });
const ireland = new aws.Provider("ireland", { region: "eu-west-1" });

const primary = new aws.s3.Bucket("primary", {}, { provider: dubai });
const backup = new aws.s3.Bucket("backup", {}, { provider: ireland });

aliases rescues a rename. After changing the logical name from "my-bucket" to "site-bucket", add the old name as an alias and Pulumi treats it as the same resource:

const bucket = new aws.s3.Bucket("site-bucket", {}, {
  aliases: [{ name: "my-bucket" }],
});

Keep the alias in place until every stack has been updated once, then you may remove it.

Real-language superpowers: loops, functions, and components

Everything so far could be done in a template language. This is where Pulumi's choice to use real languages pays off, and also where beginners can tie themselves in knots, so the pattern here is small and careful.

Loops create several similar resources from data. One logical name per item, unique:

const teams = ["data", "ml", "platform"];

const buckets = teams.map(team =>
  new aws.s3.Bucket(`${team}-artifacts`, {
    tags: { team },
  })
);

export const bucketNames = buckets.map(b => b.id);

teams = ["data", "ml", "platform"]

buckets = [
    aws.s3.Bucket(f"{team}-artifacts", tags={"team": team})
    for team in teams
]

pulumi.export("bucket_names", [b.id for b in buckets])

Adding "security" to the list adds one bucket on the next up; removing one deletes that bucket. The data drives the infrastructure.

Functions remove repetition:

function managedBucket(name: string, team: string): aws.s3.Bucket {
  return new aws.s3.Bucket(name, {
    tags: { team, managedBy: "pulumi" },
  });
}

const raw = managedBucket("raw-data", "data");
const models = managedBucket("models", "ml");

Components are the next step up. A component resource groups related resources into one named unit, with its own inputs and outputs. It is a class that extends ComponentResource:

interface TeamStorageArgs {
  team: string;
}

class TeamStorage extends pulumi.ComponentResource {
  public readonly artifactsBucket: pulumi.Output<string>;
  public readonly logsBucket: pulumi.Output<string>;

  constructor(name: string, args: TeamStorageArgs, opts?: pulumi.ComponentResourceOptions) {
    super("acme:storage:TeamStorage", name, {}, opts);

    const artifacts = new aws.s3.Bucket(`${name}-artifacts`, {
      tags: { team: args.team },
    }, { parent: this });

    const logs = new aws.s3.Bucket(`${name}-logs`, {
      tags: { team: args.team },
    }, { parent: this });

    this.artifactsBucket = artifacts.id;
    this.logsBucket = logs.id;

    this.registerOutputs({
      artifactsBucket: this.artifactsBucket,
      logsBucket: this.logsBucket,
    });
  }
}

const mlStorage = new TeamStorage("ml", { team: "ml" });
export const mlArtifacts = mlStorage.artifactsBucket;

Four details make a component correct. The super call takes a type token in the form package:module:Type (here acme:storage:TeamStorage; the package part is your own choice), the name, a properties object, and the options. Children pass { parent: this } so they nest under the component in the output tree. Child names include the component's name (`${name}-artifacts`) so two instances do not collide on URNs. And registerOutputs tells Pulumi the component has finished and which values it exposes.

In the preview, the tree makes the grouping visible:

 +   pulumi:pulumi:Stack           hello-pulumi-dev  create
 +   └─ acme:storage:TeamStorage   ml                create
 +      ├─ aws:s3:Bucket           ml-artifacts      create
 +      └─ aws:s3:Bucket           ml-logs           create

Start with loops and functions. Reach for a component when you find yourself copying the same group of three resources and wanting one name for them. Deeper component patterns (packaging, sharing across languages, testing) are mid-level territory.

Destroying and cleaning up

Cloud resources cost money while they exist, so learning to remove them is half of learning to create them. The command that deletes everything a stack manages is pulumi destroy:

pulumi destroy

It shows a preview in which every line is a -, asks for confirmation, and deletes the resources in reverse dependency order: things that depend on others go first. When it finishes, the stack still exists but is empty, and its history remains. Remove the empty stack and its config file with:

pulumi stack rm dev

or do both at once with pulumi destroy --remove. Stack config files are not deleted by destroy alone; Pulumi.dev.yaml stays in your folder until the stack is removed.

Destroy can fail, and the reasons are instructive. An S3 bucket that still contains objects cannot be deleted by the cloud unless the bucket is marked forceDestroy: true; set that in code, run pulumi up to apply it, and then destroy. A virtual machine with termination protection on, or a database with deletion protection, behaves the same way: the provider refuses because the cloud refuses. The fix is always "change the attribute in code, apply it, then destroy," because Pulumi's record must match reality at each step.

If a destroy fails because your cloud credentials expired since the resources were created, Pulumi reuses the provider configuration it saved in state, which can be stale. Re-authenticate, then run pulumi destroy --run-program, which re-runs your program so the provider gets fresh settings.

Common errors and how to read them

Pulumi's error messages are usually good, and often include the fix. The skill is knowing which part to read. A failed update prints the resource that failed, the provider's message, and a summary. Read from the bottom up: the last error: line is the cause, and the lines above it are context.

Some deserve a paragraph.

Interrupted updates. If you press Ctrl-C during an up, or your laptop sleeps, or a CI job is killed, Pulumi may not know whether a create call finished. The next run warns about pending operations. Do not ignore the warning. Run pulumi refresh interactively: it asks about each pending operation and reconciles state with the cloud. If an interrupted create left a cloud object behind, refresh can adopt it or you can delete it by hand; either way state and reality agree again. In scripts, pulumi refresh --clear-pending-creates --yes clears the record when you know the resource was not created.

Locks and conflicts. Pulumi Cloud gives each update a lease on the stack so two runs cannot overlap. A message starting [409] Conflict means a lease is active. First check whether a teammate's or a CI job's update is really running; if it is, wait. If the lease belongs to a run that died, pulumi cancel releases it. A DIY backend uses a lock file and says the stack is currently locked by 1 lock(s), with the same remedy.

Provider errors. When the cloud rejects a request, Pulumi prints the provider's message verbatim: AccessDenied, BucketAlreadyExists, InvalidParameterValue. These are not Pulumi bugs. Read the message, then read the resource's documentation in the Pulumi Registry (search for the resource type, such as aws.s3.Bucket) to check the argument. An AccessDenied almost always means your cloud identity lacks a permission, not that Pulumi is misconfigured. For a first diagnosis try aws sts get-caller-identity to confirm which identity Pulumi is using.

Node and TypeScript version errors. Since CLI 3.249 the Node.js SDK needs Node 22 or later. If an upgrade suddenly breaks a working project with an unexplained runtime error, check node --version first, then confirm TypeScript is version 6 or earlier.

When you are stuck, add -v=3 --logtostderr to a command for detailed logs, or --debug for engine debug output. Automatic logging is also on by default since 3.249, written (encrypted) under ~/.pulumi/logs, and the pulumi logs family of subcommands manages them. Share output with care: verbose logs can contain values you would rather not paste into a public issue.

Putting it all together

Here is a small end-to-end project that uses every idea above: a project, two stacks, config, a secret, a loop, a component, protection, outputs, and a clean destroy. It creates storage buckets for a team's ML work. Budget about thirty minutes.

1. Create the project and two stacks.

mkdir ml-storage && cd ml-storage
pulumi new aws-typescript --name ml-storage --stack dev --yes
pulumi stack init staging
pulumi stack select dev

2. Set configuration per stack. The region, which environment this is, and a list of team names as a JSON array, plus a secret that a later application would use.

pulumi config set aws:region me-central-1
pulumi config set environment dev
pulumi config set --path 'teams[0]' data
pulumi config set --path 'teams[1]' ml
pulumi config set --secret apiToken 'replace-me-with-a-real-token'

The --path flag writes structured values; here it builds a list named teams. Do the same for staging, using --stack staging and only one team if you like.

3. Write the program.

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

const config = new pulumi.Config();
const environment = config.require("environment");
const teams = config.requireObject<string[]>("teams");
const apiToken = config.requireSecret("apiToken");

class TeamStorage extends pulumi.ComponentResource {
  public readonly artifactsBucket: pulumi.Output<string>;

  constructor(name: string, team: string, env: string, opts?: pulumi.ComponentResourceOptions) {
    super("acme:storage:TeamStorage", name, {}, opts);

    const artifacts = new aws.s3.Bucket(`${name}-artifacts`, {
      tags: { team, environment: env, managedBy: "pulumi" },
      forceDestroy: env !== "prod",
    }, { parent: this, protect: env === "prod" });

    this.artifactsBucket = artifacts.id;
    this.registerOutputs({ artifactsBucket: this.artifactsBucket });
  }
}

const storages = teams.map(team => new TeamStorage(`${environment}-${team}`, team, environment));

export const bucketNames = storages.map(s => s.artifactsBucket);
export const tokenPreview = apiToken.apply(t => t.length);

Read what each part does. Config supplies the environment and team list, so the same code serves both stacks. The secret is read with requireSecret, and the only thing exported is its length (still a secret output, because it derives from a secret). The component wraps one bucket per team with consistent tags. forceDestroy is on outside production so practice stacks can be cleaned up, and protect is on only in production. The loop turns the team list into components with unique names that include the environment.

4. Preview, read, and deploy.

pulumi preview --diff
pulumi up -m "first deployment of team storage"
pulumi stack output --json

The preview shows a stack, two components, and two buckets, all +. After up, the outputs list two real bucket names. The token length shows as [secret].

5. Change something and watch the diff. Add a third team, security:

pulumi config set --path 'teams[2]' security
pulumi preview

Exactly one new component and one bucket appear as +, and everything else is unchanged. Apply it.

6. Deploy the second stack and compare.

pulumi stack select staging
pulumi config set environment staging
pulumi config set aws:region me-central-1
pulumi config set --path 'teams[0]' data
pulumi config set --secret apiToken 'another-token'
pulumi up

The same program, a different set of buckets. pulumi stack ls now shows two stacks with their own resource counts.

7. Destroy both.

pulumi destroy --yes --remove
pulumi stack select dev
pulumi destroy --yes --remove

Afterwards pulumi stack ls is empty, the AWS console shows no buckets from the exercise, and the two Pulumi.<stack>.yaml files are gone with the stacks. To keep the project, commit Pulumi.yaml, index.ts, package.json, and the lock file to git, and commit each stack's config file too: secrets are encrypted in it, so it is safe. Do not commit node_modules, and do not commit any plaintext credentials.

What you can now do, and what comes next

You can explain what Pulumi does and how it differs from scripts and template tools, install the CLI and check the setup, choose a backend, create a project from a template, read a preview and tell an update from a replacement, understand Outputs and use interpolate, apply, and all, create stacks and give each its own configuration, keep secrets encrypted, apply resource options such as protect and provider, build resources from loops and components, read Pulumi's common errors, and destroy cleanly. That is a working practitioner's toolkit, enough to own a small project's infrastructure.

Mid-level takes every one of those topics further: how the engine diffs, replaces, and orders resources, structured and typed configuration, stack references to share values between projects, Pulumi ESC for configuration and secrets, importing existing infrastructure, components packaged and shared across languages, testing with mocks, and running Pulumi from CI pipelines with OIDC instead of long-lived keys.

Senior then covers what you own when Pulumi is a platform for a team: state surgery and recovery, scaling large stacks, the trust model and supply chain of providers, policy as code, Pulumi Deployments, the Automation API and the Kubernetes operator, multi-tenancy, cost, and upgrades.

Natural neighbours to read next in this catalogue: the Terraform guide for the tool Pulumi is most often compared with, the Kubernetes guide for what many teams deploy onto the infrastructure Pulumi creates, and the Helm guide for packaging those Kubernetes workloads.

Sources

• Pulumi documentation home
• Download and install Pulumi
• How Pulumi works
• State and backends
• Using a DIY backend
• Projects and the Pulumi.yaml file
• Stacks
• Configuration
• Secrets
• Inputs and outputs
• Resource names and auto-naming
• Resource options
• Resource providers
• Component resources
• Languages and SDKs
• CLI command reference
• CLI environment variables
• Troubleshooting
• Pulumi CLI changelog

Part one of three. A twenty-five-minute review of the Beginner Detailed track, then the questions interviewers ask. Mid-level reviews this plus its own material; Senior reviews all three. The guide is written against Pulumi CLI v3.266.0, and where behaviour changed recently the text says so, because interviewers like to probe exactly those places.

The thirty-second answer

Pulumi is an infrastructure-as-code tool: you write a program in a general-purpose language such as TypeScript or Python that declares cloud resources, and Pulumi's engine compares that declaration with its recorded state, shows you a preview, and makes the cloud match. Each deployed copy of the program is a stack, so the same code serves dev, staging, and production.

Then the line that shows you have used it: "running the program does not create anything by itself; it registers resources with the engine, which diffs them against state, so anything I delete from the code is deleted from the cloud."

The model

Why Pulumi, compared with the alternatives

Expect "why would you choose this over Terraform?" in some form. A balanced answer names real differences and does not pretend one tool wins.

The honest framing: both tools share the core model of desired state, a recorded state, and a plan before apply. Pulumi's bet is that infrastructure logic deserves a real programming language; Terraform's bet is that a constrained declarative language is easier to read and review. Neither is wrong. The Terraform guide covers the other side.

What happens when you run pulumi up

This is a favourite question, and a precise answer impresses.

1. The CLI reads Pulumi.yaml and starts the language host for your runtime, for example the Node.js host.
2. The language host runs your program. Each time it constructs a resource, the SDK sends a registration to the engine over a local gRPC connection on 127.0.0.1. No cloud call happens from your code.
3. The engine loads the stack's last recorded state and compares each registered resource with it, working out whether it is new, changed, unchanged, or needs replacing. Anything in state that was not registered in this run is scheduled for deletion.
4. The engine shows the preview and, on confirmation, asks the relevant provider to perform each operation in dependency order.
5. Results come back as outputs, are written to state, and are handed back to your program.

The model answer to "does Pulumi refresh state first?" is no. It trusts its recorded state unless you run pulumi refresh or pulumi up --refresh, so manual changes in the cloud console are invisible until then. That is drift.

The commands to have ready

pulumi version                       # CLI version
pulumi about                         # environment, plugins, backend, language
pulumi login                         # Pulumi Cloud; `--local` for a local file backend
pulumi whoami -v                     # user, organizations, backend URL
pulumi new aws-typescript            # project from a template
pulumi install                       # dependencies and plugins
pulumi preview --diff                # what would change, with property detail
pulumi up -y -m "message"            # deploy, skip the prompt, label the update
pulumi stack init dev                # new stack
pulumi stack select dev              # switch stack
pulumi stack ls                      # list stacks
pulumi stack output --json           # read outputs
pulumi config set key value          # plain config
pulumi config set --secret key value # encrypted config
pulumi refresh                       # reconcile state with the real cloud
pulumi destroy --remove              # delete resources, then the stack
pulumi cancel                        # release a stuck update lease (use with care)

Say what each does in one sentence, and say which ones are read-only: version, about, whoami, preview, stack ls, stack output, and config without set change nothing in the cloud.

Reading a preview

The four symbols are a standard quick question.

The follow-up is usually "what forces a replace?" The answer: a property the provider marks as immutable, such as a name or an availability zone. The preview names the property that forces it. Pulumi's default order is create-before-delete, which reduces downtime, but the option deleteBeforeReplace flips it when the cloud forbids two objects with the same name at once. The safety answer: check the preview for - and +- on anything stateful and protect such resources with protect: true.

Inputs, outputs, and apply

What an Output is, in one breath: a value that will exist after deployment, carrying with it which resources it depends on and whether it is secret. Why it is needed: the program runs before the resources exist. What it buys you: Pulumi can build the dependency graph from how values flow, with no hand-written ordering.

The three tools:

• apply transforms one Output with a function that receives the plain value.
• pulumi.all / Output.all combines several Outputs so one apply can use them all.
• pulumi.interpolate / Output.format builds a string from Outputs.

And the warning that goes with them: never create a resource inside apply. It will not appear in pulumi preview, because the callback only runs once the value is known.

Stacks and configuration

State that a stack is one deployed instance of a project, and that stacks differ by config while sharing code. Name the files: Pulumi.yaml for the project and Pulumi.<stack>.yaml for each stack's settings.

Config namespaces are a detail worth knowing. aws:region belongs to the AWS provider; bucketPrefix is stored as <project>:bucketPrefix. In code, new pulumi.Config() reads the project namespace and new pulumi.Config("aws") reads the provider's.

Typical reading methods: require (fails if missing), get (returns nothing if missing), typed variants such as getNumber, and the *Secret variants that return a secret Output. The error for a missing key includes the exact pulumi config set command to fix it.

Secrets

The model answer has four parts. pulumi config set --secret encrypts the value in Pulumi.<stack>.yaml so the file is safe to commit. In code you read it with requireSecret, which gives an Output flagged as secret. The flag propagates: anything computed from a secret is secret, and Pulumi encrypts it in state too. The CLI masks it as [secret] unless you pass --show-secrets.

The encryption key depends on the backend and provider. With Pulumi Cloud, a per-stack key held by the service. With a DIY backend, a passphrase from PULUMI_CONFIG_PASSPHRASE (or a file named by PULUMI_CONFIG_PASSPHRASE_FILE) by default, or a cloud key management service by choice.

Be ready for the limits. A secret is only a secret where it is marked; a plain config.require of a sensitive value is not protected. Logging inside apply leaks the plaintext. And state contains your resource details, so access to state is sensitive even though cloud credentials are not stored in it.

Backends

A recent change worth knowing: in CLI 3.257 the deprecation warning for the old DIY "non-project" layout became an error, and pulumi state upgrade is the fix. Mention it if the conversation turns to self-managed state.

Also mention pulumi logout: since CLI 3.246 it deletes all stored backend configuration from the machine.

Names, URNs, and renames

A resource has a logical name (in code) and a physical name (in the cloud). Auto-naming appends a random suffix to the physical name, such as my-bucket-d7c2fa0, which avoids global name collisions and allows create-before-delete replacements. The URN is urn:pulumi:<stack>::<project>::<type>::<logical-name>.

The trap: changing a logical name changes the URN, so Pulumi plans to delete the old resource and create a new one. The fix: the aliases resource option, which tells Pulumi the two names are the same resource.

The related error: Duplicate resource URN ...; try giving it a unique name, caused by two resources with the same type, name, and parent, typically in a loop. Fix it by including a distinguishing value in each logical name.

Resource options

Deprecated to mention only if asked: the transformations option, replaced by transforms.

The protect error is worth memorising: resource "<urn>" cannot be deleted because it is protected, and the two fixes (remove the flag and run pulumi up, or pulumi state unprotect <urn>). Resources adopted with the CLI's pulumi import are protected by default.

Components versus custom resources

A custom resource is managed by a provider and maps to one cloud object. A component resource is a class extending ComponentResource that groups children under a single name, takes its own arguments, and exposes outputs. Four details to recite: the type token package:module:Type passed to super, { parent: this } on children, child names derived from the component name, and registerOutputs at the end.

The traps, and why they share one cause

Nearly every beginner trap comes from forgetting that the program describes a desired state and the engine diffs it against a record, rather than executing steps.

Errors you should be able to read aloud

Common interview questions

What is the difference between a project and a stack? A project is the code and its Pulumi.yaml; a stack is one deployed instance of that project with its own config and state. One project commonly has several stacks, one per environment.

What happens if I run pulumi up twice? The second run finds no difference between the program and recorded state and changes nothing. Pulumi is idempotent, because it reconciles to a desired state rather than executing steps.

Where does Pulumi store state, and why does it matter? In the backend: Pulumi Cloud by default, or a DIY backend such as a local folder or an object storage bucket. It matters because state is how Pulumi knows what it created, enables previews and deletions, holds encrypted secrets, and must be shared safely if a team works on the same stack.

Does the state contain my cloud credentials? No. Credentials stay on your machine or in CI and come from the provider's normal credential chain. State does contain resource details and encrypted secrets, so access to it should still be controlled.

What is an Output, and why can't I concatenate it with a string? An Output is a value that is not known until the resource exists. It cannot be treated as a string at program time. Use pulumi.interpolate, Output.format, or apply to compose it.

How does Pulumi know the order to create resources? From the Outputs: when one resource uses another's output, that creates a dependency edge, and the engine orders operations accordingly. dependsOn adds an edge where no value flows.

I renamed a resource and Pulumi wants to delete and recreate it. Why, and how do I avoid it? The logical name is part of the URN, so a rename looks like a removal plus an addition. Add aliases: [{ name: "old-name" }] to keep the identity.

How do you keep a database from being deleted by accident? Set protect: true, tag it, review previews for - and +-, and restrict who can run destroy. Mention that protection is enforced by Pulumi, and that provider settings like deletion protection add a second layer at the cloud.

How do you handle secrets? pulumi config set --secret for config, requireSecret in code, pulumi.secret() for computed values, never log them, and choose a secrets provider appropriate for the backend. Keep the passphrase, if any, in a password manager.

What does pulumi refresh do, and when do you use it? It reads the real cloud and updates state to match, without changing the cloud. Use it after suspected manual changes, after an interrupted update, or before an up when drift is likely.

An update was interrupted and now Pulumi warns about pending operations. What do you do? Run pulumi refresh interactively to reconcile. If you know a create did not happen, pulumi refresh --clear-pending-creates --yes clears it. Never ignore the warning.

Two teammates get [409] Conflict. What is going on? The stack has a single update lease. Check whether someone's or a CI job's update is really running. If the holder died, pulumi cancel releases it, but warn the person whose update will fail.

How would you deploy the same infrastructure to dev and prod? One project, two stacks, per-stack config for the differences (region, sizes, names), and the same code. Protect production resources and require reviewed previews for that stack.

What are the language options? TypeScript and JavaScript on Node.js, Python, Go, C#, Java, and YAML, with an HCL runtime added recently. All use the same engine, so concepts are identical. Mention the Node.js requirement: Node 22 or later for the SDK since CLI 3.249.

Can you use Pulumi with a cloud that has no provider? Usually yes: Pulumi can generate a provider SDK from a Terraform provider with pulumi package add terraform-provider <name>, and many clouds and services already have native or bridged providers.

What would you check first if pulumi up hangs with no output? A corporate proxy intercepting local 127.0.0.1 gRPC traffic, because the CLI, language host, and provider talk to each other locally. Add 127.0.0.1 and localhost to NO_PROXY, and confirm https://api.pulumi.com is reachable.

When would you use a DIY backend? When data must stay in a specific region or organisation, or a team has no access to a hosted service. The cost is losing the hosted locking UX, history, RBAC, and ESC, and owning the bucket, the encryption choice, and the backups.

What is the danger of full programming languages in infrastructure code? Programs can hide side effects and nondeterminism: reading files, calling services, or random values make previews unreliable. Keep programs pure: branch on config, not on the environment, and keep logic in small tested functions.

Sixty-second self-test

Answer aloud, without scrolling up.

1. What is the difference between a project, a program, and a stack?
2. What do +, ~, -, and +- mean?
3. Why is ${bucket.arn} in a template string wrong, and what do you use instead?
4. What happens if you delete a resource block from the code and run pulumi up?
5. Why does renaming a logical name recreate the resource, and how do you avoid it?
6. How do you store a password so it is safe to commit, and how do you read it in code?
7. What does pulumi refresh do that pulumi up does not?
8. What are the two ways out of a protect error?
9. What do you do when an update says [409] Conflict?
10. Name the three processes involved in a pulumi up.

If you hesitated on more than two, reread the matching section of the Beginner Detailed track and try the exercise again.

Part one of three. A few root causes produce most beginner problems with Pulumi: you forget that the program is a declaration diffed against a record, you forget that an Output is not a string, or you lose track of which stack you are on. Start with the table, then the habits, then the practice cards and recipes.

Common errors at this level

The habits that pay off most

Expanding on the ones that need a sentence of justification.

Commit the right files and only those. Commit Pulumi.yaml, your program, the dependency manifest and lock file, and every Pulumi.<stack>.yaml (secrets in them are encrypted). Do not commit node_modules, a Python virtual environment, or any file holding a plaintext credential. A .gitignore produced by the template already handles most of this; do not delete it.

Keep one stack per environment, and keep them boring. Dev, staging, and prod should differ only in config values. If you find yourself writing if (stack === "prod") throughout the program, move the difference into config (a boolean or a number) so the code stays one story.

Pin versions. Your dependency lock file pins provider SDK versions. Commit it. A provider major version can change behaviour, so upgrade deliberately and read pulumi preview --diff afterwards for unexpected replacements.

Treat the preview as the code review for infrastructure. On a team, post pulumi preview --diff output in the pull request, so reviewers see what will change in the cloud and not only what changed in code.

Keep programs free of side effects. No file writes, no network calls, no random numbers in the program body. The program runs on every preview, and anything nondeterministic makes the preview unreliable.

Practice cards

Each card takes five to ten minutes. Do them in a cloud-free sandbox (local backend plus the random provider) or a low-cost AWS account.

Debugging a run that failed

When an update fails, follow the same order every time. It saves more time than any trick.

1. Read the last error: line. That is the cause. The lines above it are context.
2. Decide who is speaking. If the message is AccessDenied, InvalidParameterValue, or BucketAlreadyExists, the cloud is speaking and Pulumi is relaying. If it mentions config, stacks, or URNs, Pulumi is speaking.
3. Check your position. Run pulumi stack and pulumi whoami -v. A surprising number of problems are the wrong stack, the wrong folder, or the wrong backend.
4. Check the cloud identity. aws sts get-caller-identity (or the Azure and Google equivalents) tells you which account and role the provider is using.
5. Re-run with more detail. pulumi up -v=3 --logtostderr prints engine and provider logs. Add --debug for engine debug output.
6. Open the update in the console. pulumi console shows the failed step, the diff, and the event stream for Pulumi Cloud stacks.
7. Reconcile if in doubt. After an interrupted or partly failed update, pulumi refresh makes state match reality before you try again.

Preview and up: a rhythm that works

A safe rhythm for every change, which becomes automatic after a week:

pulumi stack                 # which stack am I on?
pulumi preview --diff        # what will change?
pulumi up -m "add tags"      # apply, with a message
pulumi stack output --json   # confirm the outputs

When something looks odd in the preview, such as a replacement you did not expect, do not apply and hope. Find the property that forces it by reading the diff, then decide: is this change worth a replacement, can it be expressed differently, or should the resource be protected and the change planned as a migration? For changes that touch only one resource you can limit the operation with --target <urn>, though that is an escape hatch rather than a workflow, because targeted updates can leave the rest of the stack out of step.

If you suspect drift before a risky change, refresh first:

pulumi refresh --preview-only   # show what would change in state, change nothing
pulumi up --refresh             # sync state with the cloud, then deploy

Configuration habits

Use typed reads. config.getNumber("size") or get_int saves you from string-versus-number surprises that only appear at deploy time.

Use require for mandatory values. Failing fast with the message "Missing required configuration variable" is kinder than a half-working deployment with a default nobody chose.

Name keys consistently. Choose camelCase or snake_case for your project's keys and stick to it. Provider keys such as aws:region are fixed by the provider.

Prefer structured config for lists. pulumi config set --path 'teams[0]' data writes a list without inventing a comma-separated string that you must parse. Read it with requireObject.

Set the region explicitly. Every stack should carry aws:region (or the equivalent). If your employer or client has data-residency rules, the region is a compliance decision, and an unset region falling back to an ambient environment variable is how a resource ends up in the wrong country. Regions in the Gulf include me-central-1 (UAE) for AWS; check your provider's current list.

Working on a team

• One update at a time per stack. Pulumi Cloud enforces this with a lease; in CI, run one pipeline per stack at a time.
• Never share a login. Use your own account and, in CI, an access token or OIDC rather than a colleague's credentials.
• Do not mix console clicks and code on resources Pulumi manages. If an emergency forces a console edit, follow up with pulumi refresh and put the change into code so the next up does not revert it.
• Agree on naming. Decide together whether you use auto-naming or fixed names, and how logical names are formed. Logical names are hard to change later.
• Write a README that lists the required config keys, the login steps, and the order to deploy stacks.

Cost and cleanliness

Cloud resources bill while they exist, and forgotten ones are the classic beginner surprise.

• Tag everything with a purpose and an owner, including practice resources.
• Prefer the smallest sizes while learning, and the cloud-free sandbox for concept practice.
• Destroy at the end of each session: pulumi destroy --remove.
• Set a billing alert in your cloud account before you deploy anything larger than a bucket.
• Remember that Pulumi Cloud has a free individual tier, while team features are priced by managed resources, so check the current pricing page before adopting it for a team.

Things that change quickly

Pulumi ships a new minor release about weekly, so articles age fast. These changes from 2026 are the ones most likely to bite if you follow an older tutorial:

• Node.js 22 or later is required by the SDK (CLI 3.249.0); Node 20 no longer works.
• pulumi new asks for a cloud provider and a language (3.258.0) and shows one confirmation for project, stack, and config (3.259.0). The AI mode and its flags were removed in 3.257.0.
• pulumi logout deletes all stored backend configuration (3.246.0).
• The standalone esc command is retired; its functions live under pulumi env.
• pulumi cloud api was renamed pulumi api (3.238.0).
• The Pulumi.<stack>.deploy.yaml settings file was removed (3.251.0).
• DIY backends using the old non-project layout now error (3.257.0); pulumi state upgrade fixes it.
• transformations is deprecated in favour of transforms.

When a command from a tutorial is rejected, run pulumi <command> --help first: the help text is always current for your installed version.

Small things to do from day one

• Install shell completion: pulumi gen-completion zsh (or bash, fish).
• Keep a short RUNBOOK.md in the repository: login steps, config keys, deploy order.
• Add .gitignore entries for node_modules, venv, and .env.
• Set PULUMI_SKIP_UPDATE_CHECK=true in CI to avoid a network call for version checks.
• Use pulumi about output whenever you ask for help.
• Learn the Pulumi Registry search: every resource has a documentation page with its arguments, outputs, and examples in your language.
• Use pulumi console to see a stack's history and resource graph.

Learning from your own update history

Every update leaves a record, and reading it is one of the fastest ways to build intuition. With Pulumi Cloud, pulumi stack history lists each update with its time, its message, and a summary of how many resources were created, changed, or deleted. Open the update in the console and you can see the exact diff, the order in which resources were created, and the duration of each step. A DIY backend keeps a simpler record, but the command works there too.

Use this in three situations. When you are learning, compare your expectation of an update with what the history shows; the gaps are where your mental model is wrong. When something broke, find the last update that touched the resource and read its message, which is why writing a message with -m is worth the five seconds. And when you are handing work to someone else, the history is a free changelog of the infrastructure.

Asking for help well

When you are stuck, the quality of your question decides how quickly you get an answer. A good report to a teammate, a community channel, or the Pulumi issue tracker contains four things: the exact command you ran, the last few lines of the error message copied as text rather than a screenshot, the output of pulumi about so the reader knows your versions, and the smallest program that reproduces the problem. Shrinking the program often solves it on the spot, because you discover which resource or which line is the real cause.

Before posting, remove anything sensitive. State outputs, verbose logs, and config listings can contain account IDs, internal hostnames, and sometimes secret values if --show-secrets was used. Replace them with placeholders. If the problem looks like a provider bug rather than a Pulumi one, say which provider and which version you use, since providers are versioned separately from the CLI and a fix may already exist in a newer release.

Reading provider documentation

Each resource you create has a page in the Pulumi Registry listing its arguments (inputs), its properties (outputs), and examples in every language. Two habits make the pages useful. First, check whether an argument is marked as forcing a replacement: if it is, changing it later will show +- in the preview. Second, read the import section at the bottom of the page, which shows the ID format you would need to adopt an existing object, a skill you will want in the mid-level track.

Be careful about copying examples without reading them. Examples are written to be short, so they may use fixed names, wide-open permissions, or settings that are fine for a demo and wrong for your account. Treat them as a starting point for reading the arguments, not a finished design.

Checklist before you apply a change

A starter layout to copy

A layout that scales from your first project to a small team, with a file for each job:

infra/
  Pulumi.yaml            # project name and runtime
  Pulumi.dev.yaml        # dev config (secrets encrypted)
  Pulumi.staging.yaml    # staging config
  index.ts               # the program: read config, create resources
  components/
    team-storage.ts      # reusable components, one per file
  package.json           # dependencies, pinned by the lock file
  package-lock.json
  README.md              # login, config keys, deploy order
  .gitignore             # node_modules, .env

A starting .gitignore:

node_modules/
bin/
.env
*.log

And a starter README.md outline to keep beside the code:

# Team storage infrastructure

## Prerequisites
- Node.js 22 or later, Pulumi CLI v3.26x or later
- `pulumi login` and an AWS identity for the target account

## Deploy
1. `npm install`
2. `pulumi stack select dev`
3. `pulumi preview --diff`
4. `pulumi up -m "describe the change"`

## Required config
- `aws:region`
- `environment`
- `teams` (list)
- `apiToken` (secret)

Follow this, read every preview, and keep the stack you are on in view. That is most of what separates a confident beginner from a careful practitioner, and the mid-level track builds directly on it.

This is part two of three. It picks up where Beginner ended and takes every topic from there further, then adds the machinery you have not met yet. You already run pulumi up at work. By the end of this guide you will be able to predict what the engine is about to do before it does it, refactor code without destroying production, and set up a pipeline that a teammate cannot break by pushing at the wrong moment. Commands are checked against Pulumi CLI v3.266 (September 2026). The CLI ships a minor release every week or two, so treat "v3.26x or later" as the version contract and never hard-code a patch number in instructions.

Where this picks up

Each section starts with the problem it solves, and ends with a Try it you can do on a real project in a few minutes. Examples are TypeScript unless the language matters, in which case Python appears beside it. Everything in the Pulumi model is identical across languages, so if you write Go or Python, read the TypeScript as pseudocode for the same engine calls.

How an update really works

The problem: at Beginner level, pulumi up is a button. When it does something surprising, such as replacing a database you thought it would update, you have no model to explain why. Three cooperating processes sit behind that button, and knowing what each one does makes the surprises predictable.

The language host is a separate process, named pulumi-language-<language>, that runs your program. The engine lives inside the CLI. A resource provider is a plugin binary, cached under ~/.pulumi/plugins, that knows how to create, read, update and delete one family of cloud objects. They talk to each other over gRPC on 127.0.0.1. Your program never calls a cloud API. It registers resources: each new aws.s3.Bucket("logs", {...}) sends a message to the engine that says "I want a resource of this type, with this name, with these inputs."

For each registration the engine looks up the resource by its URN in the last recorded state. If it finds nothing, it plans a create. If it finds one, it asks the provider to compare old inputs with new inputs (the provider's diff call). The answer is one of three things: nothing changed, an in-place update, or a replace because some changed property cannot be modified in place. When your program has finished running, every resource in state that was not registered in this run is planned for delete. That last rule is the source of most "where did my resource go" incidents: a resource disappears from the cloud because its line disappeared from the code, or because the code path that registered it did not run.

The preview symbols are the engine's answer:

Replacement order matters. By default Pulumi creates the replacement first and deletes the original after dependents have been repointed, which gives you zero downtime where the cloud allows two objects to coexist. It fails where they cannot, for example a resource with a fixed name that must be unique. There you need deleteBeforeReplace, and you accept the gap.

State is a checkpoint, not a mirror

The state (also called the checkpoint) is a snapshot of every resource's inputs, outputs, dependencies and provider reference, stored in the backend. Two properties follow from that design:

• Pulumi does not refresh state before every operation. The diff compares your new inputs to the recorded inputs, not to the live cloud. If someone edits a security group in the console, pulumi up will say "no changes" until you run pulumi refresh, pulumi up --refresh, or set options: { refresh: always } in Pulumi.yaml.
• Since 3.225 the engine journals state writes by default, which reduces the cost of persisting a large checkpoint to Pulumi Cloud after each step. You can turn it off with PULUMI_DISABLE_JOURNALING, which you would only do while diagnosing an engine problem.

The engine also runs resource steps in parallel wherever the dependency graph allows it. A dependency exists when one resource uses another's output, or when you declare it with dependsOn or a parent. Anything without a path between them can run concurrently, which is why hidden dependencies (a resource that needs another to exist but never references it) produce flaky, order-dependent failures.

Get into the habit of reading pulumi preview --diff rather than the default summary. The diff shows which property triggered a replace, marked with the word replace next to the property name. That tells you immediately whether you caused it or a provider upgrade did.

Inputs, outputs and the unknown-value problem

The problem: a resource's ID, ARN or endpoint does not exist until the cloud creates it, yet you need to pass it to the next resource while writing code that runs before anything is created. Pulumi solves this with Output<T>, a value that will be available later, and most mid-level bugs come from forgetting that an output is not the thing it wraps.

An output carries three things: the eventual value, the set of resources it depends on (this is how dependency edges are created automatically), and a flag saying whether it is secret. During pulumi preview, outputs of resources that do not exist yet are unknown. Code inside apply does not run for unknown values in preview, and it runs only once the value resolves during the real update.

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

const bucket = new aws.s3.Bucket("logs");

// 1. apply: transform one output into another
const arn = bucket.arn.apply(a => a.toUpperCase());

// 2. interpolate: build strings from outputs (the right way to template)
const url = pulumi.interpolate`https://${bucket.bucketRegionalDomainName}/index.html`;

// 3. all: combine several outputs
const summary = pulumi.all([bucket.id, bucket.arn]).apply(([id, arn]) => `${id} -> ${arn}`);

// Inputs accept plain values, promises or outputs, so pass outputs straight through
new aws.s3.BucketPolicy("logs-policy", {
  bucket: bucket.id,
  policy: bucket.arn.apply(arn => JSON.stringify({
    Version: "2012-10-17",
    Statement: [{ Effect: "Allow", Principal: "*", Action: "s3:GetObject", Resource: `${arn}/*` }],
  })),
});

export const publicUrl = url;

The mistakes that follow from it

Stringifying an output. A template literal ${bucket.id} does not wait for anything. The resource receives the literal text produced by the conversion. In Node.js the SDK warns with Calling [toString] on an [Output<T>] is not supported., and suggests apply or pulumi.interpolate. In Python the equivalent message is Calling __str__ on an Output[T] is not supported. Set PULUMI_ERROR_OUTPUT_STRING=true to make it a hard error in CI, and add @pulumi/eslint-plugin to catch it while you type.

Creating resources inside apply. Resources made in an apply callback are invisible to preview, because the callback does not run for unknown values. You then get a preview that looks clean followed by an update that creates things nobody reviewed. Move resource creation outside and pass the output in as an input. The only legitimate cases involve values that are known at preview time, and even then the structure is fragile.

Conditionals on outputs. if (bucket.id === "x") compares an object to a string and is always false. You cannot branch program structure on a value that is not known yet. Branch on configuration instead, which is known at preview.

Leaking secrets through apply. A value derived from a secret output stays secret, but console.log inside apply prints the plaintext into your CI logs. Logging secrets is a human mistake the engine cannot stop.

Calling functions that return plain data, not outputs. Invoke-style data sources such as aws.getCallerIdentity() return promises of plain values in Node.js, and the Output versions (getCallerIdentityOutput) accept outputs as arguments. Reach for the Output form when any argument depends on another resource. Since 3.225, invoke results are marked secret automatically when their inputs are secret.

In Python the same operations read Output.all(...), Output.format(...) and Output.concat(...), and you write bucket.arn.apply(lambda a: a.upper()). In Go you use pulumi.Sprintf and pulumi.All(...).ApplyT(...).

Names, URNs and refactoring without replacement

The problem: you will rename things. A resource moves into a component, a variable gets a clearer name, a module is split. In Terraform that is a moved block. In Pulumi the same idea is the alias, and understanding why it is needed requires understanding identity.

Every resource has a URN, its unique ID within a stack:

urn:pulumi:prod::network::aws:ec2/vpc:Vpc::main
        |      |       |               |   |
      stack  project  type token      name  logical name

A child resource's type is prefixed by its parents' types joined with $, so a bucket inside an acme:storage:Logs component has a URN containing acme:storage:Logs$aws:s3/bucket:Bucket. The engine matches code to state by URN, nothing else. Change the logical name, the parent or the type, and the URN changes, so the engine sees a brand new resource and an orphaned old one.

Do not confuse the logical name with the physical name. The logical name is the first argument in code. The physical name is what the cloud sees. By default Pulumi auto-names physical resources by appending a random suffix, so logs becomes something like logs-d7c2fa0. That suffix is deliberate: it lets you deploy two stacks of the same program into one account, and it lets replacement create the new object before deleting the old one, because the two names do not collide. You can change the behaviour with the pulumi:autonaming config, which supports modes default, verbatim, disabled and pattern (with placeholders such as ${name}, ${project}, ${stack} and ${hex(n)}). Setting an explicit name on a resource opts that one resource out, and you then own uniqueness.

config:
  pulumi:autonaming:
    mode: pattern
    pattern: ${project}-${stack}-${name}-${hex(4)}

Aliases

An alias tells the engine "the resource I am now calling X used to be known as Y, so treat them as the same." It costs nothing and is removed once every stack has been updated.

// Before: const logs = new aws.s3.Bucket("logs");
// After: the bucket moves inside a component, so both its name and its parent change
class LogStore extends pulumi.ComponentResource {
  public readonly bucketName: pulumi.Output<string>;
  constructor(name: string, opts?: pulumi.ComponentResourceOptions) {
    super("acme:storage:LogStore", name, {}, opts);
    const bucket = new aws.s3.Bucket("bucket", {}, {
      parent: this,
      aliases: [{ name: "logs", parent: pulumi.rootStackResource }],
    });
    this.bucketName = bucket.bucket;
    this.registerOutputs({ bucketName: this.bucketName });
  }
}

Two rules keep aliases safe. First, run pulumi preview --diff after adding one and confirm the old resource shows as unchanged rather than as a create and delete pair. Second, keep the alias until every stack that uses the program has been applied at least once. A stack you forgot about (a long-lived staging) will otherwise replace its bucket the day somebody finally updates it.

A newer tool helps when an alias is not enough. Since 3.264 components accept a stateMigrations resource option, a callback that can reshape a component's recorded state when its shape changes between versions. It exists in the Node.js, Python and Go SDKs and is the right answer for a library team that ships breaking changes to a component used across many stacks.

Resource options in depth

The problem: the defaults are right for a first deployment, and wrong for a resource that has customers. Resource options are the third argument of every resource constructor, and they are where you express operational policy. The full list in the current docs is: additionalSecretOutputs, aliases, customTimeouts, deleteBeforeReplace, deletedWith, dependsOn, envVarMappings, hideDiffs, hooks, ignoreChanges, import, parent, protect, provider, providers, replaceOnChanges, replaceWith, replacementTrigger, retainOnDelete, stateMigrations, transforms, and version (with pluginDownloadURL). The older transformations option is deprecated, so use transforms in new code.

It helps to group them by what they change.

Options that change what the engine does to the cloud:

• protect: true refuses to delete the resource. A pulumi destroy fails with resource "<urn>" cannot be deleted because it is protected, and the message names the two fixes: remove the flag and run pulumi up, or run pulumi state unprotect <urn>. From 3.256 you can override with --ignore-protect on up, preview and destroy, which deletes protected resources without unprotecting them first. Treat that flag as break-glass.
• retainOnDelete: true removes the resource from state but leaves the cloud object alone. It is the right choice for a resource you want to outlive its stack, such as a Route 53 zone.
• deletedWith: parent tells the engine that deleting another resource implicitly deletes this one, so it skips the pointless (and sometimes failing) delete call. A classic use is Kubernetes resources that vanish when their cluster is deleted.
• deleteBeforeReplace: true flips replacement order for resources that cannot coexist.
• replaceOnChanges and replacementTrigger force a replacement when a property or an arbitrary value changes, which is how you roll a resource when an upstream input changes that the provider does not track.
• ignoreChanges: ["tags"] ignores differences in named properties. It is the honest answer when another system, such as an autoscaler or a tagging policy, owns a field. Overusing it hides real drift.

Options that change the dependency graph: parent, dependsOn, and provider/providers. Use dependsOn only for hidden dependencies that an output reference cannot express, such as an IAM policy attachment that must exist before a function is invoked.

Options that shape state and diffs: additionalSecretOutputs marks provider outputs as secret that the provider did not flag, hideDiffs hides noisy properties in preview output, aliases and stateMigrations preserve identity across refactors, and import adopts an existing object.

Options that run code: hooks runs code before or after create, update and delete, and an OnError hook (3.217) lets you write custom retry logic for errors a provider does not retry itself. Since 3.238, a failing engine after hook fails the deployment, so keep hooks fast and deterministic.

Options that change behaviour of many resources at once: transforms lets a function inspect and rewrite the arguments and options of every resource created beneath it. That is how you enforce "every bucket gets these tags" without touching every call site.

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

const db = new aws.rds.Instance("orders", {
  engine: "postgres",
  instanceClass: "db.t4g.medium",
  allocatedStorage: 50,
  username: "app",
  password: new pulumi.Config().requireSecret("dbPassword"),
  skipFinalSnapshot: false,
  finalSnapshotIdentifier: "orders-final",
}, {
  protect: true,                    // a destroy cannot silently delete customer data
  ignoreChanges: ["allocatedStorage"], // storage autoscaling owns this field
  customTimeouts: { create: "60m", update: "60m", delete: "60m" },
  additionalSecretOutputs: ["endpoint"],
});

// Stack-wide policy through a transform on the stack itself
pulumi.runtime.registerResourceTransform(args => {
  if (args.type.startsWith("aws:") && "tags" in args.props) {
    args.props["tags"] = { ...args.props["tags"], owner: "platform", env: pulumi.getStack() };
    return { props: args.props, opts: args.opts };
  }
  return undefined;
});

One more rule with real consequences: CLI-imported resources are marked protect by default. That is deliberate, because importing something means it already matters. You remove the flag in code once you are sure.

Components: reusable infrastructure with a boundary

The problem: copy-pasting 40 lines that create a VPC, subnets and route tables into every project means forty places to fix when security asks for flow logs. A component resource groups child resources behind one name and one set of arguments, like a class wrapping several objects.

A component is a class that extends ComponentResource. It calls super with a type token (<package>:<module>:<Type>, for example acme:network:Vpc), creates its children with parent: this, and finishes with registerOutputs. It creates no cloud object itself. It shows up in the console as a node with children beneath it, which makes the tree legible.

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

export interface VpcArgs {
  cidr: pulumi.Input<string>;
  azCount?: number;
  flowLogs?: boolean;
}

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

  constructor(name: string, args: VpcArgs, opts?: pulumi.ComponentResourceOptions) {
    super("acme:network:Vpc", name, {}, opts);
    const child = { parent: this };

    const vpc = new aws.ec2.Vpc(`${name}-vpc`, { cidrBlock: args.cidr, enableDnsHostnames: true }, child);
    const azs = aws.getAvailabilityZonesOutput({ state: "available" });

    this.privateSubnetIds = Array.from({ length: args.azCount ?? 2 }, (_, i) =>
      new aws.ec2.Subnet(`${name}-private-${i}`, {
        vpcId: vpc.id,
        cidrBlock: pulumi.interpolate`${args.cidr}`.apply(c => c.replace(/\.0\.0\/16$/, `.${i}.0/24`)),
        availabilityZone: azs.names[i],
      }, child).id);

    this.vpcId = vpc.id;
    this.registerOutputs({ vpcId: this.vpcId, privateSubnetIds: this.privateSubnetIds });
  }
}

Design rules that separate a good component from a liability:

• Prefix every child name with the component's own name, or two instances collide with a duplicate URN.
• Accept Input<T> types in args so callers can pass outputs from other resources.
• Expose what callers need as outputs, not the child resources themselves. Returning the raw child couples callers to your internals.
• Keep the surface small and opinionated. A component that mirrors every property of its children is just a slower way to call them.
• Use a provider pass-through deliberately. A component receives providers (plural) in its options so a caller can pick the regional or account-specific provider for all its children.

Components written in one language can be consumed from another. You package the component with componentProviderHost (Node.js) or component_provider_host (Python), and consumers run pulumi package add <source> to generate a local SDK in their language. For sharing inside a company, the Pulumi Cloud Private Registry hosts published packages and templates, and since 3.220 pulumi package and pulumi install resolve package names through the Cloud Registry by default.

Project layout, stacks and stack references

The problem: a single project that holds the network, the cluster, the database and the application becomes slow to preview, dangerous to change and impossible to give to different owners. Every resource lives in one state checkpoint, and pulumi up and refresh both walk all of it. A common rule of thumb is one project per bounded unit, one stack per environment: a network project, a cluster project and an app project, each with dev, staging and prod stacks.

Stacks in different projects exchange data through stack outputs. The producer exports, and the consumer reads with a StackReference:

export const vpcId = vpc.vpcId;
export const privateSubnetIds = vpc.privateSubnetIds;

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

const env = pulumi.getStack();                     // "prod"
const net = new pulumi.StackReference(`acme/network/${env}`);

const vpcId = net.requireOutput("vpcId");          // fails loudly if missing
const subnets = net.requireOutput("privateSubnetIds") as pulumi.Output<string[]>;

Prefer requireOutput over getOutput. A missing output then fails at preview with a message naming it, rather than flowing through the program as undefined until some provider rejects it. The fully qualified name is <organization>/<project>/<stack>, and the reference needs read permission on the other stack. Secret outputs stay secret across the reference.

Stack references create a hidden coupling that nothing in the engine tracks. The consumer's preview reads the producer's last deployed outputs, so there is an ordering rule you must enforce yourself: deploy network first, then cluster, then app. Removing or renaming an output breaks every consumer the next time it runs, and nothing warns you in the producer's preview. Treat outputs as a public API. Add new ones freely, deprecate before removing, and keep a list of consumers.

Stack files and naming

The project file Pulumi.yaml holds project-level settings, and each stack has Pulumi.<stack>.yaml next to it (or in the directory named by stackConfigDir). The stack file carries config:, an optional environment: list of ESC environments, and the secrets metadata (secretsprovider, encryptedkey or encryptionsalt). Commit all of them. The encrypted values are safe in version control, and the stack file is the record of how an environment differs from another.

Use the stack name for environment selection, never a hand-written if (env === "prod") scattered through code. Put differences in config: instance sizes, replica counts and feature flags. A program whose behaviour lives in data is reviewable, while one whose behaviour lives in branches needs a full read to know what production will do.

A few stack-admin commands you will use constantly once you have many stacks:

pulumi stack ls                                  # list stacks (alias of list)
pulumi stack select acme/app/prod                # fully qualified selection
pulumi stack select --create acme/app/dev        # idempotent: good for CI
pulumi stack tag set owner platform-team         # tags for search and governance
pulumi stack history                             # who deployed what, when
pulumi stack export --file prod-state.json       # state as JSON, for inspection
pulumi config cp --dest staging                  # copy config to another stack
pulumi stack rename prod-eu                      # rename a stack

Configuration and secrets, properly

The problem: Beginner taught you pulumi config set and config.require. At work you need typed and validated config, structured values, and secrets that are encrypted with a key your organisation controls.

Typed config

Declare the schema in Pulumi.yaml so the CLI validates values before the program runs:

name: app
runtime: nodejs
requiredPulumiVersion: ">=3.250.0"
config:
  instanceType:
    type: string
    default: t4g.small
  replicas:
    type: integer
    default: 2
  dbPassword:
    type: string
    secret: true

With that in place, pulumi config set replicas two fails immediately, and forgetting dbPassword produces Missing required configuration variable 'app:dbPassword' with the exact command to fix it. --skip-config-validation exists for the rare case where you need to bypass validation. requiredPulumiVersion is a guardrail: a teammate on an old CLI gets a clear refusal instead of strange behaviour.

Structured values and bulk operations

pulumi config set --path 'network.subnets[0]' 10.0.1.0/24
pulumi config set-all --plaintext region=me-central-1 --secret apiKey=abc123
pulumi config set --raw tlsCert < cert.pem          # preserves newlines, since 3.247
pulumi config cp --dest prod                        # copy this stack's config to prod
pulumi config refresh                               # pull remote config into the local file
pulumi config get network --json

Read structured values in TypeScript with config.requireObject<NetworkConfig>("network"), and in Python with config.require_object("network"). set-all is the tool for scripts, because it sets many values in one write.

Secrets: where they are encrypted

Secrets are encrypted in two places, the stack config file and the state, and both use the stack's secrets provider. The choices:

pulumi stack init prod --secrets-provider="awskms://alias/pulumi-prod?region=me-central-1"
pulumi stack change-secrets-provider "awskms://alias/pulumi-prod?region=me-central-1"

Choose the key for compliance reasons that you can explain. A KMS key in your own account gives you key-usage audit logs and lets a regulator-facing team say who can decrypt, and in the Gulf and Egypt that is often the conversation with a security or data-residency reviewer. For exact URL shapes of the other providers, use the current secrets documentation rather than a blog post.

Secrets have a propagation rule you should know cold: a value derived from a secret is secret. Interpolate a secret password into a connection string and the string is a secret output. Export a secret and pulumi stack output prints [secret] unless you pass --show-secrets. The limits are equally important:

• Resource inputs are only secret if you mark them secret (config.requireSecret or pulumi.secret(v)). A plaintext value passed to an input is stored in plaintext in state.
• Outputs the provider did not flag as sensitive can be marked with additionalSecretOutputs.
• Anything you log, and anything printed with --show-secrets, is plaintext.
• In non-interactive runs, a passphrase provider needs PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE, or the CLI errors with passphrase must be set with PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE environment variables. A wrong value gives incorrect passphrase. If the passphrase is lost, the secrets cannot be decrypted by any means.

Pulumi ESC and OIDC: configuration without static credentials

The problem: long-lived cloud keys in CI variables are the most common credential leak in infrastructure pipelines, and copying the same config into thirty stack files is the most common source of drift. Pulumi ESC (Environments, Secrets and Configuration) addresses both. An ESC environment is a YAML document, versioned and access-controlled in Pulumi Cloud, that composes values, pulls secrets from stores, and mints short-lived cloud credentials through OIDC.

imports:
  - acme/common
values:
  aws:
    login:
      fn::open::aws-login:
        oidc:
          roleArn: arn:aws:iam::123456789012:role/esc-oidc
          sessionName: pulumi-esc
  dbPassword:
    fn::secret: change-me-in-the-console
  environmentVariables:
    AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
    AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
    AWS_SESSION_TOKEN: ${aws.login.sessionToken}
  pulumiConfig:
    dbPassword: ${dbPassword}

Three outputs of an environment matter. environmentVariables are exported to a process, pulumiConfig is fed into stack configuration as if you had set it with pulumi config, and files (from 3.255) are written to disk with their paths exposed as variables. fn::open::aws-login exchanges an OIDC token for temporary AWS credentials, and there are matching providers for Azure and GCP and for secret stores such as AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, HashiCorp Vault and 1Password.

A stack consumes an environment by listing it:

environment:
  - acme/app/prod
config:
  app:replicas: 6

Explicit values in the stack file override the imported ones, so an environment can carry defaults and a stack can tune them. From a shell, the same environment works without a stack at all:

pulumi env init acme/app/prod                 # create (opens an editor)
pulumi env get acme/app/prod                  # read the definition
pulumi env open acme/app/prod --format json   # resolve values (secrets revealed)
pulumi env run acme/app/prod -- aws s3 ls     # run a command with its variables
pulumi env version tag acme/app/prod stable   # pin a version

OIDC in both directions

OIDC removes static keys at two separate seams, and people often fix only one.

CI to Pulumi Cloud. The CI job presents its own identity token and exchanges it for a short-lived Pulumi access token, so no PULUMI_ACCESS_TOKEN secret lives in CI. On the command line that is pulumi login --oidc-token <token-or-file://path> --oidc-org <org>, optionally with --oidc-team, --oidc-user and --oidc-expiration. In GitHub Actions, the pulumi/auth-actions@v1 action does the exchange. Since 3.216, an OIDC login defaults to Pulumi Cloud.

Pulumi to your cloud. ESC (or Deployments) uses OIDC to assume a role in your cloud account, so no cloud keys are stored anywhere. The cloud side needs a trust policy that names Pulumi as the issuer and restricts the subject claim to your organisation and environment. Since 3.261, pulumi env setup aws, azure or gcp configures that trust and creates the ESC environment for you, which is the fastest onboarding path.

Restrict the trust policy as tightly as you can. A role assumable by "any workflow in the organisation" turns one compromised repository into access to production.

State, drift and recovery

The problem: state is the one thing Pulumi cannot regenerate from your code. It records what exists, and when it disagrees with reality, or an update dies halfway, you need a procedure instead of panic.

Backends

Pulumi Cloud is the default backend and gives you locking, history, encryption, RBAC and the features built on top of them (ESC, Deployments, Insights). A DIY backend stores state in a local directory, S3 or an S3-compatible store, Azure Blob, GCS or PostgreSQL, and is free. The documented limitation is that a DIY backend cannot transparently recover from certain partial failures, and it has no built-in RBAC, so access control becomes bucket IAM. Two recent changes affect anyone on DIY: since 3.257, a bucket still using the old non-project (global) layout produces an error, not a warning, and pulumi state upgrade fixes it (the escape hatch is PULUMI_DIY_BACKEND_IGNORE_DEPRECATION_ERROR=true, renamed from ..._WARNING). And since 3.254, pulumi stack migrate moves a stack from another backend to the current one and re-encrypts its secrets, replacing the old export, login, init, import sequence.

Also note a breaking change that catches people in shared shells: since 3.246, pulumi logout deletes all backend configuration. pulumi logout --all --delete-credentials-key (3.265) additionally removes the key used when you opt into encrypted credential storage with PULUMI_CREDENTIAL_STORE.

Refresh and drift

Drift is the gap between recorded state and the cloud. The commands:

pulumi refresh --preview-only          # show drift, change nothing
pulumi refresh --yes                   # adopt the cloud's current values into state
pulumi up --refresh                    # refresh then update in one step
pulumi refresh --run-program           # refresh using the program's current provider config

refresh only rewrites state. It does not touch the cloud. After a refresh that shows drift, the next pulumi up will change the cloud back to what your code says, unless you change the code to match. Decide which side is right before you run it. For scheduled detection, Pulumi Deployments can run drift detection and optional remediation on a schedule, and pulumi stack drift list and pulumi stack drift status report results.

Locks and interrupted updates

An update takes a lease on the stack. If a run is killed (an impatient Ctrl-C, a CI runner that vanished), two classes of problem appear.

A stuck lock. On Pulumi Cloud you see error: [409] Conflict: Another update is currently in progress. On a DIY backend you see the stack is currently locked by N lock(s). Either wait for the other process(es) to end or delete the lock file with pulumi cancel. First confirm nobody is actually running an update, then run pulumi cancel. Cancelling makes the other person's update fail immediately, so check before you do it. The durable fix is to serialise CI so a stack is never updated concurrently.

Pending operations. A killed run can leave operations recorded as in flight, and the next up warns: Attempting to deploy or update resources with N pending operations from previous deployment. Pulumi cannot know whether the cloud object was created, so you tell it:

pulumi refresh                                   # interactive: choose per operation
pulumi refresh --clear-pending-creates --yes     # the resource was NOT created; forget it
pulumi refresh --import-pending-creates 'urn:pulumi:prod::app::aws:s3/bucket:Bucket::logs' \
               --import-pending-creates 'logs-d7c2fa0' --yes   # it WAS created; adopt it by physical ID

The import flag takes two consecutive values per resource: its URN, then its physical ID. You can find the physical ID in the cloud console, filtering by the tags or name prefix.

Surgery, sparingly

When state is wrong in a way refresh cannot fix, pulumi stack export and pulumi stack import let you edit the JSON by hand, and there are safer purpose-built commands: pulumi state delete (alias of remove) drops a resource from state without touching the cloud, pulumi state rename changes a URN, pulumi state unprotect clears a protect flag, pulumi state move transfers resources between stacks, and pulumi state repair fixes integrity errors. Always pulumi stack export --file backup.json first, and run a preview afterwards to confirm the engine now agrees with the cloud.

Importing and converting existing infrastructure

The problem: most real adoptions start with infrastructure that already exists, created in a console, by Terraform, or by a colleague who left. There are two separate jobs here, and they use different tools.

Adopting existing cloud objects. pulumi import reads a live resource and writes it into state, printing code you paste into the program:

pulumi import aws:s3/bucket:Bucket infra-logs company-infra-logs

The arguments are the type token, the logical name you want, and the physical ID. For many resources, generate an import file and run it in one go:

pulumi preview --import-file import.json   # write a skeleton from resources marked with `import`
pulumi import --file import.json           # import them all and print generated code

The generated code is a starting point. Review the properties, remove ones that are computed, and replace literal values with config or references. A successful import is proven by pulumi preview showing no changes after you paste the code in. If the preview shows an update, your code differs from reality, and you decide which one is right.

You can also do it in code with the import resource option (import_ in Python, pulumi.Import(pulumi.ID(...)) in Go, ImportId in C#). That form is reviewable in a pull request and works in a pipeline, which a one-off CLI import does not.

Converting code. pulumi convert translates a program from another format. pulumi convert --from terraform --language typescript --out ./ts converts Terraform, and --from hcl (HCL has had its own language host since 3.235) does the same for HCL sources. Conversion gives you code, not state: the resources it describes still have to be imported or recreated. The realistic migration from Terraform is: convert the code, import each existing resource so the stack's state matches the cloud, confirm a no-change preview, then retire the Terraform state. For resources you cannot express natively yet, pulumi package add terraform-provider hashicorp/random lets you use any Terraform provider, and runtime: hcl runs HCL itself. See our Terraform guide for the other side of this comparison.

Providers, packages and upgrades

The problem: the CLI and the providers release on different schedules, and a provider major version can change resource behaviour more than a CLI upgrade ever does.

A provider is a plugin binary plus a generated SDK in your language. Two families exist. Bridged providers are derived from Terraform providers (pulumi-aws, pulumi-gcp), so they inherit Terraform's semantics and behaviour. Native providers are generated from cloud APIs (azure-native, kubernetes, aws-native). The AWS provider is at 7.x as of September 2026, and major versions are where breaking changes live.

Every stack uses a default provider unless you say otherwise, configured from stack config (aws:region) and ambient credentials. An explicit provider gives you control:

const dr = new aws.Provider("dr-region", { region: "eu-west-1" });
const replica = new aws.s3.Bucket("replica", {}, { provider: dr });

Use explicit providers for multi-region and multi-account work. To stop accidents, set pulumi:disable-default-providers so any resource created without an explicit provider fails: pulumi config set --path 'pulumi:disable-default-providers[0]' aws.

A safe upgrade procedure

1. Read the provider's migration notes before touching versions.
2. Bump the SDK version in package.json (or requirements.txt, or go.mod), run pulumi install, then run pulumi preview --diff on a non-production stack first.
3. Look for unexpected replace lines. Upgrades that rename or retype properties show up here, long before they reach a database.
4. Fix code, use aliases or ignoreChanges where appropriate, preview again, and only then promote the change through staging to prod.

Keep the CLI and the language SDK close in version (the Automation API even checks a minimum CLI version), pin the CLI in CI rather than taking whatever is latest, and enforce a floor with requiredPulumiVersion. In 2026 several changes will break a stale environment and are worth checking against your own: the Node.js SDK requires Node.js 22 or later (since 3.249), TypeScript 7 is incompatible with Pulumi's built-in compilation (use TypeScript 6 or earlier, or precompile), Pulumi.<stack>.deploy.yaml was removed in 3.251, pulumi cloud api is now pulumi api, and the retired pulumi new --ai mode was replaced by pulumi neo.

Plugins are downloaded per version into ~/.pulumi/plugins. In CI, bake them into your image with pulumi install or pulumi plugin install resource aws <version>, because downloading at run time makes builds slow and exposes you to GitHub rate limits. Air-gapped environments can mirror with PULUMI_PLUGIN_DOWNLOAD_URL_OVERRIDES.

Testing infrastructure code

The problem: infrastructure code that nobody tests breaks in production, and a cloud integration test on every commit is slow and costs money. Pulumi gives you three layers, cheapest first.

Unit tests with mocks. You replace the engine's connection to providers with fake implementations, so the program runs in milliseconds with no cloud account and no network. In Node.js you call pulumi.runtime.setMocks, in Python pulumi.runtime.set_mocks, and in Go pulumi.WithMocks. Your test then inspects the resources the program registered.

import * as pulumi from "@pulumi/pulumi";
import { describe, it, before } from "node:test";
import assert from "node:assert";

pulumi.runtime.setMocks({
  newResource: (args) => ({ id: `${args.name}-id`, state: args.inputs }),
  call: (args) => args.inputs,
}, "app", "test", false);

describe("storage", () => {
  let infra: typeof import("./index");
  before(async () => { infra = await import("./index"); });

  it("blocks public access", async () => {
    const block = await new Promise<boolean>(res =>
      infra.publicAccessBlock.blockPublicAcls.apply(res));
    assert.strictEqual(block, true);
  });
});

Import the program after setMocks, since the program runs on import. Mock tests are for logic: naming, tags, conditionals, component wiring. They cannot tell you whether the cloud will accept your configuration, because no cloud is involved.

Property tests with policy packs. Run policies against a preview (pulumi preview --policy-pack ./policy) to enforce rules such as "no public buckets" or "every resource has an owner tag". Policies can be written in TypeScript, JavaScript, Python or OPA Rego, and the same pack can run locally, in CI, and as an organisation-wide enforcement in Pulumi Cloud. The enforcement levels are advisory, mandatory, remediate and disabled. Policies fit tests that are really compliance rules, and they fail the preview before anything is created.

Integration tests with the Automation API. Deploy to an ephemeral stack, assert on the outputs and real behaviour, then destroy it. This is the only layer that proves the infrastructure works, and you should run it on a schedule or before release, not on every commit. Use unique stack names (include the commit SHA), and always destroy in a finally block or a teardown so failures do not leak resources.

Pipelines: CI/CD, Deployments and Kubernetes

The problem: applying infrastructure from a laptop has no review, no audit trail and no protection from two people applying at once. The fix is the same pattern application code uses: preview on the pull request, apply on merge, one run per stack at a time.

A GitHub Actions version, with OIDC instead of stored tokens, looks like this. It uses pulumi/auth-actions@v1 to get a Pulumi token, pulumi/actions@v7 to run the command, and a concurrency group so two runs never touch the same stack together. See the GitHub Actions guide for the surrounding mechanics.

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

permissions:
  id-token: write      # needed for OIDC
  contents: read
  pull-requests: write # for preview comments

concurrency:
  group: pulumi-${{ github.ref }}-prod
  cancel-in-progress: false   # never cancel a running apply

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npm ci
        working-directory: infra
      - uses: pulumi/auth-actions@v1
        with:
          organization: acme
          requested-token-type: urn:pulumi:token-type:access_token:organization
      - uses: pulumi/actions@v7
        with:
          command: ${{ github.event_name == 'pull_request' && 'preview' || 'up' }}
          stack-name: acme/app/prod
          work-dir: infra
          comment-on-pr: true
          github-token: ${{ secrets.GITHUB_TOKEN }}

Four details decide whether this pipeline is safe:

• Never cancel an in-progress apply. A cancelled up leaves pending operations. Use cancel-in-progress: false and let runs queue.
• Preview on pull requests must not hold the stack lock for long. It is read-only but still uses the backend. Keep previews short, and avoid running one per push on a busy repo.
• Separate identities for preview and apply. Give the pull-request job a read-only role and the main-branch job the role that can write. A malicious PR from a fork must not obtain write credentials. Keep environments protected with required reviewers.
• Save the plan when the gap matters. pulumi preview --save-plan plan.json and pulumi up --plan plan.json (experimental) apply exactly what was previewed, closing the window in which the world changes between review and merge.

For review tooling in any CI, pulumi preview --json or --output json gives a structured summary, --diff a readable one, --expect-no-changes turns drift into a failing check, and --non-interactive --color never produces clean logs. GitLab CI, Azure Pipelines, Jenkins and CircleCI follow the same shape, and our GitLab CI guide and Jenkins guide cover those runners.

Pulumi Deployments

If you would rather not run your own pipeline, Pulumi Deployments runs up, preview, refresh and destroy for you inside Pulumi Cloud. It supports git-push triggers, review stacks (an ephemeral stack per pull request), scheduled drift detection and remediation, and TTL stacks that destroy themselves after a set time. Since 3.251 the settings live only in Pulumi Cloud: the old Pulumi.<stack>.deploy.yaml file and its init/pull/push commands were removed. You manage them with pulumi deployment settings get, edit and destroy, and you inspect runs with pulumi deployment list, get and cancel. Deployments can also use customer-managed agent pools to keep execution inside your network, which matters for private clusters and data-residency rules.

The Kubernetes Operator and GitOps

For teams that want a cluster to reconcile infrastructure from git, the Pulumi Kubernetes Operator v2 installs with a Helm chart and introduces the CRDs Stack, Workspace, Update and Program. It runs a workspace pod per stack, which keeps each stack's plugins and state handling isolated. It pairs naturally with Argo CD or Flux delivering the Stack objects. Use it when GitOps is already your operating model. It is additional machinery to run, and a plain CI pipeline is simpler when it is not.

Pulumi also manages Kubernetes objects directly. The @pulumi/kubernetes provider accepts YAML, Helm charts (helm.v4.Chart and Release) and Kustomize, and because it is a native provider it diffs against the cluster's API. See the Kubernetes, Helm and Kustomize guides for what you are wrapping. A sensible division is Pulumi for the cluster and cloud resources beneath it, and a GitOps tool for what runs on top.

The Automation API

The Automation API exposes the engine as a library, so programs can drive up, preview and destroy themselves. It underlies self-service portals, tenant provisioning and test harnesses. The Pulumi CLI must be installed and on PATH.

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

async function provisionTenant(tenant: string) {
  const stack = await LocalWorkspace.createOrSelectStack({
    stackName: `acme/tenants/${tenant}`,
    projectName: "tenants",
    program: async () => {
      const bucket = new aws.s3.Bucket(`${tenant}-data`);
      return { bucket: bucket.bucket };
    },
  });
  await stack.setConfig("aws:region", { value: "me-central-1" });
  try {
    const res = await stack.up({ onOutput: console.info });
    return res.outputs["bucket"].value;
  } catch (e) {
    if (e instanceof ConcurrentUpdateError) {
      console.error(`${tenant} is already being updated`);
    }
    throw e;
  }
}

An inline program like this has no Pulumi.yaml of its own, which is convenient and is also the trap: state and config still exist and must be managed. Always handle ConcurrentUpdateError, which is raised when the CLI reports another update in progress, and use a per-tenant stack rather than one giant stack.

Performance and debugging beyond the basics

The problem: a preview that takes twelve minutes, or a deploy that hangs with no output, is a productivity tax and a reliability risk. Debug by measuring where time goes, in this order.

Is it the stack size? Every resource lives in one checkpoint, and the engine diffs each of them. Thousands of resources in one stack make every operation slow. The fix is to split the project by lifecycle, not to tune flags. --target is an escape hatch that narrows an operation to specific URNs (pulumi up --target <urn> --target-dependents, or --exclude), and it leaves the rest of the stack unverified, so never build a workflow on it.

Is it the provider? Many slow previews are a provider making one API call per resource on refresh. Use --parallel N (or PULUMI_PARALLEL) to change concurrency, and PULUMI_PARALLEL_DIFF for diff calls, then watch for cloud rate limiting. More parallelism can make things slower once the provider starts retrying.

Is it plugins and installs? In CI, plugin downloads and dependency installs often dominate. Pre-install them in your image, cache ~/.pulumi/plugins and the package manager cache, and use --skip-plugin-pre-install where you know they are present.

Is it the program? Code that reads files, calls APIs or computes heavily runs on every command, including preview. Keep it cheap.

Logs and traces

pulumi up -v=9 --logtostderr 2> pulumi.log     # verbose engine and provider logs
pulumi up --debug                               # extra diagnostics
pulumi up --tracing file:./trace.json           # trace file, viewable in tooling
pulumi up --otel-traces grpc://localhost:4317   # export OpenTelemetry spans (3.226+)
PULUMI_DEBUG_GRPC=grpc.log pulumi up            # log the gRPC traffic

--otel-traces accepts a file or an OTLP endpoint, respects OTEL_RESOURCE_ATTRIBUTES and TRACEPARENT, and lets you see a deployment as one trace inside the same observability system as the rest of your pipeline. Since 3.249 the CLI also writes encrypted logs automatically to ~/.pulumi/logs, and you manage them with pulumi logs list, decrypt, share and remove. Note that plain pulumi logs is a different, experimental command that shows aggregated cloud resource logs.

Symptoms and causes

Corporate networks deserve a special mention. If your organisation inspects TLS with a gateway proxy, Pulumi's calls to api.pulumi.com and the plugin host can fail certificate verification, and the local gRPC channel must stay off the proxy. Allow https://api.pulumi.com:443 (and app.pulumi.com for the console), trust your organisation's root certificate for the Pulumi process, and do not disable verification.

Putting it all together

Here is a realistic week-one deliverable at mid level: a web service platform that a team can deploy to dev, staging and prod safely. It combines most of this guide.

1. Layout. Two projects, network and app, each with three stacks. app reads network with requireOutput. A requiredPulumiVersion floor is set in both Pulumi.yaml files.
2. Components. A Vpc component and a Service component wrap what repeats. Every child name is prefixed with its component's name. A transform adds owner and environment tags everywhere.
3. Protection. The database has protect: true, deletionProtection in the cloud, and a final snapshot. Dev stacks omit all three through config, not through code branches.
4. Config and secrets. Typed config in Pulumi.yaml, secrets through an ESC environment per stack, and a KMS-backed secrets provider for the production stack.
5. Credentials. No static keys anywhere. CI exchanges its OIDC token for a Pulumi token, and ESC assumes the cloud role through OIDC, with a trust policy scoped to one repository and branch.
6. Testing. Mock tests for the components, a policy pack forbidding public buckets, and one nightly integration test that deploys an ephemeral stack and destroys it.
7. Pipeline. Preview on pull request, apply on merge to main, concurrency group per stack, and a scheduled pulumi refresh --preview-only or Deployments drift schedule that alerts on changes.
8. Runbook. A short page that says how to read [409] Conflict, when pulumi cancel is allowed, and how to clear pending operations.

# The day-to-day loop, end to end
pulumi install
pulumi stack select acme/app/dev
pulumi preview --diff --expect-no-changes   # in CI: fail on surprise drift
pulumi up --refresh -m "add read replica"    # refresh, apply, with a message in history
pulumi stack output --json | jq .
pulumi stack history

Where you are now

You can now explain an update as registrations, a diff against recorded state, and provider calls, and you can predict replaces instead of discovering them. You handle outputs correctly, refactor with aliases, choose resource options deliberately, build components with clean boundaries, split projects by lifecycle, and pass data with stack references or ESC. You manage secrets with a key you can name, use OIDC at both seams, test at three layers, and keep a pipeline that cannot apply concurrently. You can also recover from a stuck lock, pending operations, drift and a bad upgrade.

The third level treats Pulumi as a platform that other teams depend on: state-backend architecture and failure modes, policy as governance, multi-tenant organisation design, upgrade and migration programmes, cost, and the point at which another tool is the better choice. If you are coming from Terraform or heading to Kubernetes, read the Terraform guide and the Kubernetes guide alongside it.

Sources

• Pulumi documentation
• Pulumi CLI releases and changelog
• Download and install
• How Pulumi works
• State and backends
• Using a DIY backend
• Inputs and outputs
• Resource names and URNs
• Resource options
• Providers
• Components
• Stacks
• Project file reference
• Configuration
• Secrets
• Importing existing infrastructure
• Automation API
• Environment variables
• CLI command reference
• Troubleshooting
• Update conflicts
• Interrupted updates
• GitHub Actions
• Pulumi Kubernetes Operator
• Pulumi ESC
• ESC environment syntax
• Migrating from the ESC CLI
• Pulumi Policies
• Pulumi Deployments
• OIDC access management

Part two of three. A cumulative review of Beginner and Mid-level material, organised by topic rather than level, in about thirty-five minutes. Read the fast review first and the scenario questions last. Senior reviews all three. Facts are checked against Pulumi CLI v3.266 (September 2026).

Where this picks up

The thirty-second answer, upgraded

Pulumi is infrastructure as code in general-purpose languages. Your program registers the resources you want with an engine, the engine diffs them against recorded state, and provider plugins make the cloud match. State lives in a backend, which is Pulumi Cloud by default, and stacks are independently configured instances of one program.

The mid-level addition is to say what makes it predictable: identity is the URN (stack, project, parent-qualified type, logical name), the diff compares new inputs to recorded state rather than the live cloud, and anything present in state but not registered this run is deleted.

Commands to have ready

pulumi preview --diff                       # readable plan; shows which property forces replace
pulumi up --refresh -m "message"            # refresh state first, annotate history
pulumi refresh --preview-only               # see drift without changing state
pulumi stack output --json [--show-secrets]
pulumi stack export --file backup.json      # before any state surgery
pulumi cancel                               # release a stuck lock (check first)
pulumi refresh --clear-pending-creates --yes
pulumi import aws:s3/bucket:Bucket name id
pulumi state unprotect <urn>
pulumi config set --secret key value
pulumi env run org/proj/env -- <command>    # ESC, never the retired `esc` CLI
pulumi up --target <urn> --target-dependents  # an escape hatch, not a workflow

How the engine decides

Q: Walk me through pulumi up. A strong answer names the three processes. The language host runs the program and each resource constructor sends a registration to the engine. The engine looks up the URN in recorded state. No match means create. A match means the provider's diff call compares old and new inputs and returns no change, an update or a replace. After the program finishes, anything in state that was never registered is deleted. Then the provider executes the steps, and the engine writes checkpoints as it goes.

A weak answer says "it calls the cloud APIs from my code." It misses that preview and real execution run the same program, and that registration is not creation.

Q: Why does pulumi up say no changes when someone edited the resource in the console? Because Pulumi does not refresh before every operation. The diff compares your inputs to recorded state. Run pulumi refresh or pulumi up --refresh to adopt reality, or set options: { refresh: always } in Pulumi.yaml. Follow-up to expect: "Is that good?" The honest answer is that it is faster and predictable, but it means drift is invisible unless you schedule detection.

Q: A teammate renamed a variable and the preview wants to replace the database. Why? Variable names do not matter, but the logical name string does, along with parent and type. A rename of the first constructor argument or moving the resource into a component changes the URN. The engine sees a new resource and an orphan. The fix is aliases on the new declaration, then a preview showing no create or delete. The strongest answers add: keep the alias until every stack has been deployed, and set protect: true on the database so the mistake cannot complete.

Inputs and outputs

Q: What is an Output and why does it exist? It is a value known only after a resource exists, carrying its dependencies and a secret flag. Passing outputs as inputs is how Pulumi builds the dependency graph without you declaring it.

Q: What goes wrong with apply? Five things, and naming them is what separates the levels.

1. Stringifying an output with a template literal gives an error or garbage. Use pulumi.interpolate, Output.format or apply, and set PULUMI_ERROR_OUTPUT_STRING=true to fail hard.
2. Creating resources inside apply hides them from preview, since callbacks do not run for unknown values then.
3. Branching program structure on an output is impossible, because it is not known when the program decides. Branch on config.
4. Logging inside apply leaks secret plaintext to CI logs.
5. Using plain-data invokes where the Output form is needed loses the dependency.

Q: How do you combine two outputs? pulumi.all([a, b]).apply(([a, b]) => ...) in TypeScript, Output.all(a, b).apply(...) in Python, and pulumi.All(a, b).ApplyT(...) in Go. Mention interpolate for strings, because it is the tool you actually reach for.

Resource options, in the order interviewers ask

Q: When would you use ignoreChanges? When an autoscaler, a tagging service or another tool legitimately owns a property and Pulumi would otherwise keep reverting it. The caveat a good candidate states is that it also masks genuine drift on that property, so scope it to named fields, never to *.

Q: What is special about imported resources? CLI imports are marked protect by default. After importing, paste the generated code and run preview until it shows no changes.

Components and structure

Q: Component or separate stack? A component shares code inside one stack and one lifecycle. A stack is a unit of deployment, permission and rollback. Choose a stack boundary when two parties need to deploy on different schedules or hold different permissions, and a component when they only need the same shape.

Q: What makes a good component? Children prefixed with the component's name (or duplicate URNs appear), Input<T> args, a small opinionated surface, outputs rather than exposed children, and registerOutputs. Bonus: multi-language components through componentProviderHost and pulumi package add, and stateMigrations (3.264) for evolving a component's shape.

Q: Why not one big stack? Because every resource lives in one checkpoint, so preview, up and refresh all slow down, the blast radius of a mistake grows, and ownership gets muddy. The counter-question is "why not a hundred tiny stacks?" Every boundary is a stack reference, an ordering rule to enforce and an output API to maintain.

Configuration, secrets and ESC

Q: Where are secrets encrypted, and with what? In the stack config file and in state, under the stack's secrets provider: the Pulumi Cloud per-stack key by default, or passphrase, awskms, azurekeyvault, gcpkms or hashivault. Anything derived from a secret is secret.

Q: How can a secret still leak? Resource inputs that were never marked secret sit in plaintext in state. Logging inside apply prints plaintext. --show-secrets and non-secret outputs expose values. A provider output it did not flag needs additionalSecretOutputs.

Q: A non-interactive run says passphrase must be set with PULUMI_CONFIG_PASSPHRASE.... What do you do? Export PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE. If the error is incorrect passphrase and the passphrase is lost, no secret can be recovered, so you re-set the values.

Q: Stack config or ESC? Stack config for values specific to one stack, such as replica count. ESC for values shared across stacks, for secrets pulled from a store, and for short-lived cloud credentials through OIDC. ESC needs Pulumi Cloud, and the explicit stack values override imported ones.

Backends and state

Q: Pulumi Cloud or a DIY backend? Cloud gives locking, history, RBAC, secrets management, ESC, Deployments and Insights, with pricing tied to managed resources. DIY (S3, Azure Blob, GCS, PostgreSQL, local) is free, but you own access control through bucket permissions, and the docs state it cannot transparently recover from certain partial failures. Say which you would choose and why. Good reasons for DIY include strict data-residency or air-gap constraints, and a good candidate mentions self-hosted Pulumi Cloud at Enterprise tier as the middle path.

Q: The pipeline was killed mid-apply. What now? First check there is no running update, then look for a stuck lock ([409] Conflict: Another update is currently in progress), and pulumi cancel if safe. Then look for the pending-operations warning and run pulumi refresh, choosing per operation, or --clear-pending-creates if the object was not created, or --import-pending-creates <URN> --import-pending-creates <id> if it was. Finally run a preview to confirm consistency.

Q: What changed for DIY backends recently? From 3.257 the legacy non-project layout is an error, fixed with pulumi state upgrade, and pulumi stack migrate (3.254) replaces the manual backend-migration steps.

Pipelines and identity

Q: Design a safe Pulumi pipeline. Preview on pull request with a read-only identity, apply on merge with a write identity, a concurrency group per stack that never cancels a running apply, OIDC instead of stored tokens (Pulumi Cloud via pulumi/auth-actions@v1, cloud via ESC fn::open::aws-login), pinned CLI version, pre-installed plugins, and saved plans (--save-plan, experimental) if you need exactly what was reviewed.

Q: Why not just let developers run pulumi up? No review, no audit trail, credentials on laptops, and concurrent applies. Deployments and CI give a consistent environment and a record.

Q: Where does the Pulumi Kubernetes Operator fit? It reconciles Stack objects from git inside a cluster, using Workspace pods, and suits teams with a GitOps operating model. For others, a plain CI job has fewer moving parts. See our Argo CD guide for what reconciles the CRDs.

Testing

Q: How do you test infrastructure code? Three layers, cheapest first. Unit tests with mocks (setMocks, set_mocks, WithMocks) check logic with no cloud. Policy packs check properties of the planned resources. Integration tests with the Automation API deploy an ephemeral stack and destroy it. The trade-off answer: mocks cannot know whether the cloud accepts a configuration, so you still need a few real deployments.

Trade-off questions

Q: Pulumi or Terraform? A balanced answer avoids tribalism. Pulumi's strengths are real languages (loops, functions, types, unit tests, Automation API) and components shared as packages. Terraform's are a huge ecosystem, a declarative constraint that some teams like for review, and broad hiring familiarity. Pulumi can consume Terraform providers through pulumi package add terraform-provider, and convert with pulumi convert --from terraform, so the choice is less binary than it sounds. The deciding factors are usually your team's skills and what you already operate. See the Terraform guide.

Q: Is a general-purpose language a risk? Yes: more power means more ways to write an unreadable or non-deterministic program, and the program runs during preview. Mitigate with code review, a small set of components, policies, and a rule that the program is deterministic given config.

Q: Stack references or ESC for sharing values? References for values another stack produces (a VPC ID). ESC for values that are configuration (account IDs, regions, credentials). References create ordering and coupling that nothing enforces.

What a strong answer covers that a weak one misses

• The identity model: URN, logical versus physical names, and aliases.
• Recorded state versus live cloud, and therefore drift.
• Preview as a prediction, including why unknown values matter.
• The operational shape of an answer: what you would check first, and how you would confirm recovery with a preview.
• Currency: pulumi env instead of esc, Node 22 minimum, no deployment settings file, Neo instead of pulumi new --ai.
• Honesty about limits: experimental features (--save-plan, pulumi do, Neo) called experimental.

Common interview questions

1. "Your preview shows a replace on a production database. What do you do?"Stop, run pulumi preview --diff to find which property forces it, and decide whether your change or an upgrade caused it. Look for a rename (fix with alias), a changed immutable property (accept a migration plan, or use ignoreChanges if safe), or a provider upgrade (pin back and read the migration guide). Confirm protect is set so a bad approval cannot complete.
2. "The preview takes fifteen minutes. What do you check first?"Stack size, since one checkpoint holds every resource. Then provider refresh behaviour and cloud rate limits, then --parallel, then plugin download and dependency install time in CI. Measure with --tracing or --otel-traces before changing anything.
3. "Two engineers ran updates at once."One gets [409] Conflict. Verify which update is live, never cancel someone else's blindly, and check for pending operations afterwards. Prevent recurrence with a concurrency group and, in Cloud, Deployments.
4. "How do you migrate from Terraform?"Convert with pulumi convert --from terraform, import each existing resource, reach a no-change preview, run both in parallel for a release, then retire the Terraform state. Do it by slice, not all at once.
5. "How do you roll out a provider major upgrade?"Read the migration notes, bump on dev, preview with --diff looking for replaces, fix with aliases or code, promote through staging, and keep the CLI pinned.
6. "A secret appeared in the CI log."Rotate it first. Then find the cause: logging inside apply, --show-secrets, or a non-secret output. Fix with requireSecret and additionalSecretOutputs, and prefer ESC plus OIDC so there is less to leak.

More scenarios to rehearse

1. "A destroy in dev fails halfway."Read the error for the real cause before retrying. Common ones are a cloud-level guard (forceDestroy on a bucket, deletionProtection on a database) that has to be changed in code and applied first, credentials that have expired (use pulumi destroy --run-program so the program's current provider config is used), or a protected resource. Re-run after fixing, then confirm with pulumi stack that nothing is left before removing the stack.
2. "We need the same program in three regions."Create an explicit provider per region and pass it with the provider option, or pass providers into a component so all its children inherit it. Keep names unique by including the region in the logical name, and consider disabling default providers so nothing lands in an unintended region.
3. "Someone committed a plaintext password to config."Rotate the credential, because version control remembers. Then re-set it with --secret, confirm the stack file now holds an encrypted value, and consider a typed config schema with secret: true so the CLI refuses plaintext going forward.
4. "The team wants a preview comment on every pull request."Use pulumi/actions@v7 with command: preview and comment-on-pr: true, authenticated through OIDC with a read-only role. Explain that fork pull requests should not receive credentials, and that the preview is a plan, not a guarantee, since the world can change before merge.
5. "A stack reference returns an error after a teammate's change."The producer removed or renamed an output. Restore it, or update the consumer. The lesson to state is that outputs are a public API between stacks, which means additive changes first and removals only after consumers have moved.
6. "Do we need Pulumi Cloud for ESC?"Yes. ESC requires Pulumi Cloud and does not work with a DIY backend. If DIY is a hard constraint, you would use a secrets provider with KMS and a separate secret store, and accept that the OIDC convenience is on you.

How to rehearse: pick three of these, answer each in ninety seconds, and end every answer with how you would verify the fix. A preview that shows no changes, a stack history entry, or a clean refresh is an answer that lands, because it shows you treat the tool as something to check rather than trust.

Final self-test

Answer aloud, without looking back.

1. Name the three processes behind pulumi up and what passes between them.
2. What exactly triggers a delete, apart from a destroy?
3. Why does preview say "no changes" when the cloud has drifted?
4. What does the URN contain, and which edits change it?
5. Five ways apply causes trouble.
6. What does protect stop, and three ways around it?
7. Stack reference versus ESC: when each?
8. Which seams does OIDC remove static keys from?
9. How do you clear a pending create that never happened? One that did?
10. What are the three layers of testing, and what can each not catch?
11. Why should a CI apply job never be cancelled mid-run?
12. Which of these are retired or renamed: esc, pulumi cloud api, Pulumi.<stack>.deploy.yaml, pulumi new --ai?

Part two of three. The errors you will meet once Pulumi is part of your job, the practices that pay off most (in order of leverage), practice cards, and operational recipes you can paste into a runbook. Checked against Pulumi CLI v3.266 (September 2026).

Common errors at this level

Each entry gives the message as the CLI prints it, the cause, and the fix.

error: [409] Conflict: Another update is currently in progress.

Cause. Another run holds the stack's update lease, or a crashed run left it active. Fix. Open the stack in the console and check the update list. If nobody is actually running, pulumi cancel. Be aware that cancelling makes the other person's update fail immediately. Prevent. One pipeline per stack, with a concurrency group that queues instead of cancelling. On a DIY backend the message is the stack is currently locked by N lock(s), and the fix is the same after you verify no process is running.

warning: Attempting to deploy or update resources with N pending operations from previous deployment.

Cause. A previous run was killed while an operation was in flight, so Pulumi does not know whether the object exists. Fix. Run pulumi refresh interactively and answer per operation. Non-interactively, pulumi refresh --clear-pending-creates --yes forgets creates that did not happen, and --import-pending-creates <URN> --import-pending-creates <physicalId> --yes adopts ones that did. Prevent. Never cancel a running apply.

Calling [toString] on an [Output<T>] is not supported.

Cause. An output went through a template literal or string concatenation, and the resource would have received the literal text. In Python it reads Calling __str__ on an Output[T] is not supported. Fix. pulumi.interpolate, apply, Output.format or Output.concat. Prevent. Set PULUMI_ERROR_OUTPUT_STRING=true in CI and install @pulumi/eslint-plugin.

Duplicate resource URN '...'; try giving it a unique name

Cause. Two resources share type, name and parent. Usually a loop, or a component that does not prefix its children with its own name. Fix. Build names from stable data (${name}-bucket-${key}), not array indexes.

resource "<urn>" cannot be deleted because it is protected.

Cause. protect: true, or a CLI import, which is protected by default. Fix. Remove protect in code and run pulumi up, or pulumi state unprotect <urn>. From 3.256, --ignore-protect deletes protected resources in one step. Use it only when you mean it.

Missing required configuration variable 'app:dbPassword'

Cause. config.require* (or a schema entry without a default) found no value. The message includes the exact command to fix it. Fix. pulumi config set [--secret] dbPassword ..., or supply it from an imported ESC environment's pulumiConfig. Watch for the secret variant: use --secret, or the value lands in the file in plaintext.

passphrase must be set with PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE environment variables

Cause. A passphrase secrets provider in a non-interactive shell. Fix. Export one of the two variables. It may be an empty string, but it must be set. incorrect passphrase means a wrong value for this stack's encryptionsalt, and a lost passphrase means secrets cannot be decrypted, so re-set them.

no stack selected; please use pulumi stack select or pulumi stack init to choose one

Cause. The workspace has no current stack, which is normal on a fresh CI runner. Fix. --stack, PULUMI_STACK, or pulumi stack select --create <org>/<project>/<stack>.

no Pulumi.yaml project file found (searching upwards from <dir>)

Cause. Wrong working directory. Fix. cd into the project, use -C <dir>, or set work-dir in GitHub Actions.

The Node.js program fails after an upgrade

Cause. Node.js 22 or later is required since 3.249, Node 20 no longer works, and TypeScript 7 is not compatible with Pulumi's built-in compilation. Fix. Use Node 22 or 24 and TypeScript 6 or earlier, or precompile with your own toolchain.

DIY backend fails with a legacy-layout error

Cause. Since 3.257 the old non-project layout errors instead of warning. Fix. pulumi state upgrade. You can bypass with PULUMI_DIY_BACKEND_IGNORE_DEPRECATION_ERROR=true while you schedule the upgrade, and note the variable was renamed from the ..._WARNING form.

A command hangs and prints nothing

Cause. A system proxy is intercepting Pulumi's local gRPC on 127.0.0.1. Fix. Add 127.0.0.1 and localhost to NO_PROXY, and allow https://api.pulumi.com:443.

The practices that pay off most

In order of leverage, highest first.

1. Read pulumi preview --diff every time, and read the replaces. It is the cheapest safety net you have, and most incidents skipped it.
2. Put protect: true on anything stateful, and pair it with the cloud's own guard (deletion protection, final snapshots).
3. Serialise applies per stack and never cancel a running one.
4. Use OIDC, not stored keys, from CI to Pulumi Cloud and from Pulumi to the cloud. pulumi env setup aws|azure|gcp (3.261) does most of the trust setup.
5. Split by lifecycle. One project per bounded unit, one stack per environment, and stack references as an API you version.
6. Keep differences between environments in config, not code. A program driven by data is reviewable.
7. Type your config in Pulumi.yaml and mark secrets secret: true.
8. Add aliases whenever you rename or reparent, and keep them until every stack has applied.
9. Test at the cheap layers. Mock tests and policy packs on every pull request, integration tests nightly.
10. Pin and enforce versions. Pin the CLI in CI, set requiredPulumiVersion, and read provider migration guides before a major upgrade.
11. Schedule drift detection. Drift you find on Tuesday is a chore, and drift you find during an outage is an incident.
12. Write the runbook before you need it.

Practice cards

Do these on a sandbox account, one at a time.

Making a pipeline safe

The pipeline is where a single mistake reaches everyone, so it is worth getting right once. A checklist for a GitHub Actions workflow:

• permissions: lists only what is needed, with id-token: write for OIDC and pull-requests: write for comments.
• A concurrency group per stack with cancel-in-progress: false.
• pulumi/auth-actions@v1 for the Pulumi token and pulumi/actions@v7 for the command, with a pinned Pulumi version.
• Preview on pull request using a read-only role, apply on main using a write role, production behind required reviewers.
• Plugins and dependencies installed in a cached step, so runs are fast and do not depend on a plugin host being reachable.
• --non-interactive --color never for readable logs, and --json where another tool parses the result.
• An explicit, documented rule about who may run pulumi cancel.

name: drift
on:
  schedule:
    - cron: "0 5 * * *"
permissions:
  id-token: write
  contents: read
jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pulumi/auth-actions@v1
        with:
          organization: acme
          requested-token-type: urn:pulumi:token-type:access_token:organization
      - run: |
          npm ci
          pulumi stack select acme/app/prod
          pulumi refresh --preview-only --expect-no-changes --non-interactive
        working-directory: infra

If you use Pulumi Cloud, Deployments can run the same drift schedule natively, with optional remediation and pulumi stack drift list and pulumi stack drift status to read the results. See the GitHub Actions guide for the surrounding mechanics.

Reading a preview like a reviewer

A preview is the only document that says what an update will do, so a reviewer who can read it quickly is worth more than one who can write clever components. Learn to scan in this order.

First, the summary line at the bottom. It counts creates, updates, deletes and replaces. A pull request titled "tweak tags" whose summary says 1 to delete deserves a question before anything else. Counts that do not match the description of the change are the fastest signal you have.

Second, every line that starts with - or +-. Deletes and replaces are where data is lost. For each one, ask three questions. Is the resource stateful? Is it protected? Did the author intend it? If the answer to the first is yes and the answer to the third is no, stop the review.

Third, the property that caused a replace. With --diff, the property that forces replacement is marked. If it is a name or an identifier, suspect a rename and look for a missing alias. If it is something like an engine version or an availability zone, the change is real and needs a migration plan, not just an approval. If a provider upgrade introduced it, the code did not change at all and the difference is in the provider's schema, so check its migration notes.

Fourth, unknown values. Properties shown as unknown (output<string> in the diff) are not errors. They are values the engine cannot know until something is created. A large number of unknowns beside an update often means a dependency is being replaced, and its replacement will ripple through everything that uses its ID.

Fifth, secrets and sensitive output. Masked values are good. If a value you expect to be secret appears in plaintext in the diff, the input was never marked secret, and it is also stored in plaintext in state.

What to do when the preview is huge

A preview with hundreds of changes is rarely a hundred real changes. It usually has one cause. Filter for the first change in the tree, often a shared parent or a provider, and the rest follow from it. Typical single causes include a provider major upgrade, a change to a default tag applied through a transform, a modified component used many times, or a region or account change in a default provider. Find that one line, decide whether it is intended, and only then read the rest.

Keep a record

Paste the summary line of the preview into the pull request, and the update permalink after apply. When something breaks a week later, the history of what was reviewed and what ran is one click away. pulumi stack history gives the same record locally, and it is much more useful when every update carried a message.

Pairing reviews with policy

Humans are good at spotting an unexpected delete, and poor at spotting a missing tag on the two hundredth resource. Give the second job to a policy pack. A mandatory rule such as "no public buckets, every resource has an owner tag" runs in preview, and the reviewer's attention goes to intent instead of hygiene. Start rules at advisory to see how noisy they are, then move the settled ones to mandatory. The remediate level can fix some violations automatically, which is useful for tags and a dangerous surprise for anything else, so introduce it deliberately.

Operational recipes

Adopt a hand-built resource

pulumi import aws:s3/bucket:Bucket assets company-assets   # prints code to paste
pulumi preview --diff                                      # repeat until no changes

Move a resource between stacks or rename it in state

pulumi stack export --file backup.json
pulumi state rename 'urn:pulumi:prod::app::aws:s3/bucket:Bucket::logs' logs-archive
pulumi preview --diff

For moves between stacks, pulumi state move --source <stack> --dest <stack> <urn> transfers the state entry. Check the current --help output before relying on its exact flags, and always export both stacks first.

Drop something from state without touching the cloud

pulumi state delete 'urn:pulumi:prod::app::aws:s3/bucket:Bucket::legacy'

delete is an alias of remove, and the command will refuse if other resources still depend on the target. Use it when you want Pulumi to forget a resource, for example before handing it to another stack.

Rotate the secrets provider

pulumi stack change-secrets-provider "awskms://alias/pulumi-prod?region=me-central-1"

The command re-encrypts config and state under the new key. Ensure the person or role running it can use both the old and the new key.

Migrate a stack between backends

pulumi stack migrate           # since 3.254; moves the stack to the current backend

Check the command's help for the source argument format in your version. It re-encrypts secrets under the target secrets provider, which replaces the older export, login, init and import sequence.

Pin the toolchain for everyone

name: app
runtime:
  name: nodejs
  options:
    packagemanager: npm
requiredPulumiVersion: ">=3.250.0"

curl -fsSL https://get.pulumi.com | sh -s -- --version 3.266.0   # pin in CI images

Debug a slow or strange run

pulumi up -v=9 --logtostderr 2> pulumi.log
pulumi up --tracing file:./trace.json
pulumi up --otel-traces grpc://localhost:4317
pulumi logs list              # the automatic encrypted CLI logs (3.249+)

Clean up an ephemeral stack

pulumi destroy --yes --skip-preview
pulumi stack rm --yes          # or: pulumi destroy --remove

If the destroy fails with stale credentials, add --run-program. If the cloud refuses because of deletionProtection or forceDestroy, change the attribute in code, run pulumi up, then destroy.

Habits that keep infrastructure boring

Give every update a message. pulumi up -m "add read replica, ticket 1234" costs a few seconds and saves hours when you read pulumi stack history during an incident.

Review state-changing commands like code. state delete, state unprotect, --ignore-protect and cancel belong in a change ticket or at least a chat message, because they alter what other people will see.

Keep programs deterministic. The program runs on every preview, so avoid reading the clock, calling random generators or fetching remote files in code. If a value must be random, use a Pulumi resource for it so it is recorded in state.

Prefer many small previews to one large one. Keep projects small enough that a preview finishes in under a minute or two. When it stops feeling instant, the project wants splitting.

Tag everything through a transform. One transform that sets owner, environment and cost centre is cheaper than forty reminders, and it makes cloud bills attributable.

Mark experimental features in your runbook. pulumi do, pulumi neo, --save-plan and pulumi insights are newer. Use them knowingly, and note that in your docs so the next person does not assume they are frozen.

Consider where your state lives. For organisations in the Gulf or Egypt with data-residency questions, know which region your backend and secrets key are in. A DIY backend in a regional bucket with a KMS key in the same region is a simple, explainable answer, and self-hosted Pulumi Cloud at Enterprise tier is the route when you want the full feature set inside your boundary.

Keep a "break glass" page. It lists who may run cancel and --ignore-protect, how to get a state export, where the passphrase or KMS key policy lives, and who to call. You will be glad of it once.

A short checklist

• Stateful resources are protected and have the cloud's own guard.
• CI applies are serialised per stack and never cancelled.
• No long-lived keys: OIDC to Pulumi Cloud and from Pulumi to the cloud.
• Config is typed, secrets are marked, and the secrets provider is a key you can name.
• Previews are read with --diff, and replaces are explained in the pull request.
• Renames and reparents carry aliases.
• Stack outputs are treated as an API, and references use requireOutput.
• The CLI is pinned, requiredPulumiVersion is set, and plugins are pre-installed in CI.
• Drift detection runs on a schedule and alerts somebody.
• There is a runbook for conflicts, pending operations and state recovery.

This is part three of three. It takes every topic from Beginner and Mid one level further and adds the work you own once Pulumi is not your tool but your platform: the thing forty engineers in six teams use to change production, whether or not they have ever read a line of its documentation.

Up to this point the questions were about making infrastructure code work. From here they change. What happens to a state file when a CI runner is killed halfway through an update? Which component slows down first when a stack grows to five thousand resources? Who can read the production database password, and how would you know if they did? How do you upgrade a provider across two hundred stacks without replacing a single database? And when is the honest answer that Pulumi is the wrong tool for the job in front of you?

Version note: this guide was checked against Pulumi CLI v3.266.0 (released 30 September 2026). Pulumi ships a minor release about once a week, so every instruction here says "v3.26x or later" in spirit and never depends on a patch number. The changes that matter for a platform owner are called out where they apply, because 2026 removed or renamed several things that older blog posts still teach.

Where this picks up

I am starting with the architecture, because every failure mode later in this guide is a consequence of how the pieces fit together, and you cannot reason about an incident in a system whose moving parts you cannot draw from memory.

Architecture and failure modes

Pulumi is often described as "Terraform with real languages", which is true of the authoring experience and misleading about the machinery. The machinery is three cooperating processes, a state store, and an optional managed service.

The language host is a separate executable (pulumi-language-nodejs, pulumi-language-python, and so on) that runs your program. The SDK inside your program does not call the cloud. It registers each resource with the engine over gRPC on 127.0.0.1. The engine, which lives inside the CLI, compares what your program registered with the last recorded state and decides whether each resource is created, updated, replaced or deleted. It then asks a provider, another local plugin process cached under ~/.pulumi/plugins, to perform the operation. Three processes, all talking over loopback.

Three consequences follow that matter when you own this for other people.

First, the program is not the source of truth at rest; the state is. Your code describes intent, but what Pulumi believes exists is whatever the last checkpoint says. If the state and the cloud disagree, Pulumi does not notice until you ask it to. It does not refresh state before every operation, which is a deliberate speed trade. You opt in with pulumi refresh, pulumi up --refresh, or options: refresh: always in Pulumi.yaml. A platform that never refreshes is a platform whose previews lie by omission.

Second, the engine deletes what the program no longer registers. This is the single most dangerous sentence in the tool. A conditional that evaluates differently because a config value was missing, a loop over a list that came back empty, an import that resolved to the wrong package: each of these silently removes resources from the registered set, and the engine treats the absence as an instruction. Preview shows it, but only if a human or a gate reads the preview.

Third, the local gRPC links make the CLI sensitive to its host environment. An HTTP proxy that intercepts 127.0.0.1, a security agent that blocks loopback sockets, or an x86_64 binary running under Rosetta on Apple silicon all show up as "Pulumi hangs with no output". The fix is at the environment level: exclude 127.0.0.1 and localhost from any proxy, and install the arm64 build on Apple silicon. Put both in your platform's "known environment" page so engineers stop filing them as Pulumi bugs.

The checkpoint is a transaction log

Every resource's inputs, outputs, dependencies and provider are kept in a snapshot called the checkpoint. During an update, the engine has to record the outcome of each step as it happens, because a provider call that created a database and then lost the network must still be remembered. Older CLIs rewrote the whole snapshot after each step. Journaling, on by default since v3.225.0, records incremental journal entries instead, which cuts the write cost for large stacks against Pulumi Cloud. You can turn it off with PULUMI_DISABLE_JOURNALING if you are debugging a suspected state-write problem, but you should treat that as a diagnostic step, not a setting.

The important idea is that an update is not atomic. It is a sequence of steps, each of which mutates the cloud and then the checkpoint. If the process dies between those two events you get one of the two classic dirty states.

The other dirty state is a held lock. On Pulumi Cloud the lock is an update lease held by the running update; if a runner is killed, the lease lingers until it expires or someone runs pulumi cancel. You will see error: [409] Conflict: Another update is currently in progress. On a DIY backend the lock is a file under .pulumi/locks/, and the message is the stack is currently locked by N lock(s). pulumi cancel clears both, and it deserves a warning label: if the other update is actually alive, it "will fail immediately", possibly in the middle of a step. The rule for a platform is that nobody runs pulumi cancel without first confirming, in the console or with pulumi stack history, that the holder is dead.

Why replacements are the risk event

A ~ update changes a thing in place. A +- replacement creates a new object and deletes the old one, unless you set deleteBeforeReplace. For a stateless object like a security group rule this is harmless. For a database, a load balancer with a DNS name, a KMS key or a volume with data, a replacement is an outage or data loss that happens to be printed in green. The provider decides which property changes force replacement, not Pulumi and not you. That means every provider upgrade can quietly turn an update into a replacement, which is why a later section makes preview --diff on upgrades mandatory.

Three resource options are your safety rails here, and a platform owner should know exactly what each does and does not do:

• protect: true makes the engine refuse to delete or replace the resource. The error reads resource "<urn>" cannot be deleted because it is protected. It guards against the engine, not against a person with cloud console access. Since v3.256.0 you can override with --ignore-protect, which deletes protected resources without unprotecting them first, so put that flag behind review in CI.
• retainOnDelete: true means that when Pulumi deletes the resource from state, the real object stays in the cloud. Use it for things whose deletion you never want to be a side effect of code removal.
• replaceOnChanges and deleteBeforeReplace shape how a replacement happens, for the cases where create-before-delete collides with a unique name or quota.

Resources imported with the CLI are marked protect by default, a choice that surprises people when pulumi destroy later refuses. It is the right default for brownfield adoption, and you should keep it until a resource has survived a few reviewed updates.

Backends: Pulumi Cloud, self-hosted, or DIY

The state backend is the most consequential decision you make for a platform, because it decides who holds the state, who holds the lock, and which features exist at all.

Self-hosting is an Enterprise-edition feature: you run the API and console containers yourself, with MySQL and object storage behind them, and there are reference deployments for Docker Compose (for testing only), AWS ECS or EKS, AKS and GKE. It exists for data-residency or network-isolation requirements, which matter in the Gulf and in Egypt where a regulator or a bank customer may require that state, which can contain resource identifiers and metadata, stays in a specific country or inside a private network. It is not a way to avoid cost, and you take on running a stateful service with its own upgrade and backup story.

The DIY backend deserves particular care because it is where platforms fail quietly. It is free and attractive, but it gives you a lock file rather than a lease, no history UI, no RBAC beyond bucket policy, and no ESC. It "cannot transparently recover from certain kinds of partial failures". If you run DIY, you are now responsible for the things Pulumi Cloud did for you:

• Versioning and backup on the bucket, so a corrupted or overwritten checkpoint can be rolled back. Object versioning is the floor.
• A KMS-backed secrets provider (awskms, azurekeyvault, gcpkms or hashivault), because the default DIY provider is a passphrase, and a passphrase in a CI variable is a secret shared by everyone who can read that variable.
• Serialisation at the CI layer, since the lock file will not save you from a crashed runner.

One 2026 change bites DIY users specifically. The deprecation of the old non-project layout began in v3.228.0, and as of v3.257.0 using it is an error, not a warning. A bucket created in the early days of the tool, before project-scoped stack names, fails until you run pulumi state upgrade. The escape hatch is the variable PULUMI_DIY_BACKEND_IGNORE_DEPRECATION_ERROR=true (renamed from ..._WARNING), and it is a temporary bridge, not a configuration.

Moving between backends

Migration between backends used to be a manual dance of pulumi stack export, pulumi login, pulumi stack init and pulumi stack import, with secrets re-encrypted by hand. Since v3.254.0, pulumi stack migrate moves a stack from another backend to your current one and re-encrypts config secrets and state under the target's secrets provider. Use it, but treat it as a production change with a rollback:

# 1. Take an independent copy first
pulumi stack export --file backup-prod-$(date +%F).json --stack acme/network/prod

# 2. Log in to the TARGET backend, then migrate from the source
pulumi login
pulumi stack migrate --help      # read the current flags for your CLI version

# 3. Prove the new home is equivalent before anyone deploys from it
pulumi stack select acme/network/prod
pulumi preview --expect-no-changes

The test at the end is the whole point. A migration that ends with preview --expect-no-changes returning clean has proved that the state, secrets and provider configuration all arrived intact. A migration that ends with "it imported without errors" has proved nothing.

Scaling: which component breaks first

Pulumi does not have a single throughput number, so scaling questions are really questions about which costs grow with what. The honest answer, in order of how soon you meet each one, is this.

1. The number of resources in one stack. Every resource is tracked in one checkpoint. preview, up and refresh all walk the resource graph, and refresh has to call the provider for every resource. A stack of a few hundred resources is unremarkable. A stack of several thousand is slow in every operation, produces a large checkpoint, has a blast radius that equals the whole stack, and makes every refresh a long and expensive event. This is the first limit you hit and the main reason architecture advice says "one project per bounded unit".

2. Cloud API rate limits. The engine runs operations in parallel by default, which is fast until AWS, Azure or GCP starts returning throttling errors. The knobs are --parallel (or PULUMI_PARALLEL) to cap concurrent resource operations and PULUMI_PARALLEL_DIFF for diffing. Lowering parallelism is a legitimate fix for a throttled stack, and a good reason to leave the default alone everywhere else. Measure before you tune.

3. Provider plugin start-up and download. Each provider version is a binary downloaded into ~/.pulumi/plugins. On a fresh CI runner that means every job re-downloads hundreds of megabytes, may hit a GitHub rate limit, and fails outright behind a firewall that blocks the download host. The mitigations are to bake plugins into your runner image with pulumi plugin install resource aws v7.x.y, to mirror downloads through PULUMI_PLUGIN_DOWNLOAD_URL_OVERRIDES, and to use pulumi install as an explicit, cacheable step. PULUMI_DISABLE_AUTOMATIC_PLUGIN_ACQUISITION makes a missing plugin a hard failure rather than a surprise network call in production.

4. The language runtime. For Node.js and Python programs, the program itself does real work: it loads SDKs, builds the resource graph, and runs apply callbacks. Very large programs are slow to start and use real memory. A TypeScript program that compiles on every run pays that cost every time; precompile and use typescript: false in the runtime options where that is appropriate. A cheap, often-overlooked improvement is the Node.js production runtime option (v3.252.0), which makes pulumi install skip devDependencies.

5. Pulumi Cloud itself. For the managed service, the scaling dimension is the bill, not a limit. Resources are metered hourly, and API calls beyond the free tier are metered too. Your stack-splitting decisions and your CI polling decisions have a direct cost, which the cost section returns to.

--target is an escape hatch, not a workflow

When a stack is slow, the tempting fix is pulumi up --target <URN> to update only one resource. It works, and it is sometimes the right emergency move. But a target update skips the dependency and drift checks you rely on for the rest of the stack, leaves unrelated pending changes for the next full run, and teaches the team that the preview is optional. If you find your team reaching for --target routinely, the stack is too big and the real fix is to split it. The matching flags, --exclude, --replace and --target-replace, are similarly sharp and belong in runbooks, not in pipelines.

Stack design and blast radius

Scaling and safety lead to the same design question: where do you cut? A stack is the unit of update, of lock, of refresh, of permission and of failure. Choose its boundary deliberately.

The pattern that holds up is one project per bounded unit, one stack per environment. A bounded unit is something with its own lifecycle and its own owner: the network foundation, a Kubernetes cluster, a data store, one application's infrastructure. Environments (dev, staging, prod) are stacks of the same project, differing only in configuration. The test for a good boundary is whether you could hand it to a different team without a long meeting.

Stack references are a public API

Splitting creates the coupling problem: the application stack needs the VPC ID from the network stack. The tool for this is a stack reference:

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

const net = new pulumi.StackReference("acme/network/prod");
// requireOutput fails loudly if the output is missing; getOutput returns undefined
const vpcId = net.requireOutput("vpcId");
const privateSubnetIds = net.requireOutput("privateSubnetIds");

Two things make this a platform concern. A stack reference reads another stack's exported outputs, so those exports are now an interface: renaming vpcId to vpc_id breaks every consumer the next time they deploy, not the moment you ship the change. And reading another stack's outputs requires permission to that stack, so a reference is also a cross-team access grant. Treat exports like a versioned API: add new names, deprecate old ones on a schedule, and keep the list of what each stack exports in its README.

Prefer requireOutput over getOutput in application code. A missing value that crashes the preview is a cheap failure. A missing value that becomes undefined and flows into a resource argument is the kind of bug that deletes a subnet.

There is a second route for shared values that is often better for configuration rather than infrastructure identifiers: put them in a Pulumi ESC environment and import it, so the data has an owner, a version history and its own access control rather than piggybacking on a stack's outputs. Use stack references for things that are produced by infrastructure (IDs, endpoints, ARNs) and ESC for things that are configured (feature flags, account numbers, shared secrets).

Security: the trust model

Security for an infrastructure tool is mostly a question of who holds which credential, for how long, and what they can do with it. Pulumi's model has four places where trust lives, and a platform owner should be able to name all four.

The most important sentence in this section is the last one in that diagram. Pulumi programs are arbitrary code. A pull request that changes index.ts can read environment variables, call any API the runner's credentials allow, and open a network connection, all before preview prints anything. A preview is not a sandbox. So the trust boundary for a Pulumi platform is the same as for any CI system that runs code from pull requests: untrusted branches get no production credentials, and production credentials are only reachable from a protected branch or a protected environment after review.

What state does and does not contain matters for threat modelling. Pulumi's own statement is that state "does not include your cloud credentials", which are kept local to the client and come from the provider's normal credential chain. But state does contain every resource's inputs and outputs, and outputs routinely include sensitive material the provider returned: a database endpoint, a generated password, a certificate. Whatever the provider marks as secret is encrypted; whatever it does not mark is stored as plain JSON. Anyone who can read the stack can read the plain part with pulumi stack export.

Secrets: what is protected and what leaks

Pulumi encrypts config values you set with --secret, and it encrypts any value flowing through an Output that has been marked secret. The mark is viral: an output computed from a secret input stays secret, and since v3.225.0 invoke results become secret when their inputs are. That is a good default, and it is also where people develop false confidence. Here is where plaintext still escapes:

• Resource inputs are only secret if you mark them. Passing a password as an ordinary string to a resource argument stores it in state in clear text. The fix is config.requireSecret("dbPassword") or pulumi.secret(value).
• Provider outputs that are sensitive but unmarked. If a provider returns a token in an output it does not flag as secret, use the additionalSecretOutputs resource option to force the flag.
• apply callbacks that log. Inside apply you hold the plaintext. A console.log(value) there writes it to CI logs.
• --show-secrets. On stack output, preview, up and stack export, this flag prints plaintext. It belongs in a break-glass runbook, not a wrapper script.
• Non-secret exports. An exported connection string built from a secret password stays secret, because the mark propagates. An export of the raw password string, read from a plain variable, is stored and displayed in clear text.

The second half of the model is the secrets provider, which decides who can decrypt. Options are the Pulumi Cloud per-stack key (the default), a passphrase, or a cloud KMS: awskms, azurekeyvault, gcpkms or hashivault. The choice matters because it decides whether Pulumi, your security team, or nobody can decrypt state outside your network.

# New stack with its secrets encrypted by a key you control
pulumi stack init prod \
  --secrets-provider="awskms://alias/pulumi-prod?region=me-central-1"

# Move an existing stack to a different provider (re-encrypts everything)
pulumi stack change-secrets-provider "awskms://alias/pulumi-prod?region=me-central-1"

A KMS-backed provider moves the decrypt permission into your cloud IAM, where you already have audit logs, key policies and rotation. It is the right choice when the same people who can read a stack must not automatically be able to read its secrets, or when a regulator wants the encryption key in a specific region. Note the region in the example: a Gulf or Egyptian employer that must keep key material in-region can pin the KMS key there, and then the question of where Pulumi Cloud stores the ciphertext becomes a question about ciphertext only.

The passphrase provider deserves a specific warning. It is the default on DIY backends, and its failure modes are operational: running non-interactively without the variable produces passphrase must be set with PULUMI_CONFIG_PASSPHRASE or PULUMI_CONFIG_PASSPHRASE_FILE environment variables, and using the wrong one produces incorrect passphrase. A lost passphrase means the secrets cannot be decrypted. The only recovery is to re-set the secret values. If you run passphrases at all, store them in a secrets manager with a documented break-glass path, and prefer PULUMI_CONFIG_PASSPHRASE_FILE so the value never appears in a process listing.

Short-lived credentials with OIDC

The single biggest security improvement for most platforms is deleting long-lived cloud keys from CI and replacing them with OpenID Connect trust. There are two separate exchanges, and mixing them up is a common source of confusion.

1. CI to Pulumi Cloud. The runner presents its CI-issued OIDC token to Pulumi, which issues a short-lived Pulumi access token. The CLI form is pulumi login --oidc-token <token|file://path> --oidc-org <org> (with optional --oidc-team, --oidc-user and --oidc-expiration), and in GitHub Actions the action pulumi/auth-actions@v1 does it for you. The audience is urn:pulumi:org:{ORG}. Since v3.216.0, an OIDC login defaults to Pulumi Cloud.
2. Pulumi to the cloud. Pulumi ESC or Pulumi Deployments assumes a cloud role using a trust relationship, so the program receives temporary AWS, Azure or GCP credentials and no static key exists anywhere. In an ESC environment this is fn::open::aws-login with an oidc block, and the easiest onboarding path since v3.261.0 is pulumi env setup aws (or azure, gcp), which configures the cloud trust and creates the environment.

values:
  aws:
    login:
      fn::open::aws-login:
        oidc:
          roleArn: arn:aws:iam::123456789012:role/pulumi-prod-deployer
          sessionName: pulumi-esc
  environmentVariables:
    AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
    AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
    AWS_SESSION_TOKEN: ${aws.login.sessionToken}

The trust policy on the cloud role is where you express least privilege, and it is the control most often left too wide. Scope it by organisation and by claim, so that only the intended repository, branch or environment can assume the production role. A role assumable by "any workflow in the GitHub organisation" is a static key with extra steps.

Beyond the pipeline, think about human credentials on laptops. The CLI stores logins in ~/.pulumi/credentials.json. Since v3.258.0 you can opt in to encrypting that file with an OS-protected key using PULUMI_CREDENTIAL_STORE, and v3.265.0 added pulumi logout --all --delete-credentials-key to remove the key. Remember also that since v3.246.0, pulumi logout deletes all backend configuration, which surprised many people who used it as a "switch account" shortcut.

Supply chain: providers, packages and plugins

A Pulumi update executes three categories of code you did not write. Your program's dependencies (npm, PyPI, Go modules), the provider plugins it downloads and runs as local processes with your cloud credentials in their environment, and any components or packages you consume. Each is a supply-chain surface.

Provider plugins deserve the most attention, because a provider receives the credentials to act in your cloud. Mitigations, in rough order of effort:

• Pin versions. Pin the SDK package in your lock file and use the version resource option or the package's exact version so a provider does not change between a reviewed preview and an apply. Note that provider majors, for instance the AWS provider moving from v6 to v7, carry breaking changes you must read the migration guide for.
• Control where plugins come from. PULUMI_PLUGIN_DOWNLOAD_URL_OVERRIDES redirects plugin downloads to an internal mirror, and since v3.220.0 names resolve through the Pulumi Cloud Registry by default (PULUMI_DISABLE_REGISTRY_RESOLVE turns that off). Bake approved plugins into the runner image and set PULUMI_DISABLE_AUTOMATIC_PLUGIN_ACQUISITION so a job can never fetch an unreviewed binary at run time.
• Lock the lockfiles. npm ci, uv sync --frozen or go mod verify in CI, never a bare install that may resolve newer versions than the review saw.
• Treat third-party components like dependencies. A component package can create IAM roles. Review what it provisions the way you would review a Terraform module, and prefer components from your own private registry.
• Use requiredPulumiVersion in Pulumi.yaml (for example ">=3.250.0") so that nobody runs an old CLI with missing safety fixes against a shared stack. Note that v3.221.0 renamed pulumiVersionRange to requiredPulumiVersion in PulumiPlugin.yaml, and old names in templates will not be honoured.

There is also the bridged provider subtlety. Many providers, including pulumi-aws and pulumi-gcp, are generated from Terraform providers, so they inherit that ecosystem's behaviour and release cadence. That is why pulumi package add terraform-provider <org/name> can wrap almost any Terraform provider. It also means a provider bug may be an upstream bug, and your support path goes through both projects.

Multi-tenancy

"Multi-tenancy" on Pulumi means two different things, and you should ask which one a stakeholder means before designing anything.

Tenancy inside your organisation means many teams sharing one Pulumi Cloud organisation. The boundaries available are teams, stack-level permissions, custom roles (RBAC), and ESC environments that are namespaced as org/project/env with their own access control. Custom roles are an edition feature (up to 25 on Pro, unlimited on Enterprise), SAML SSO starts at Pro, and SCIM provisioning is Enterprise. The working pattern is to give each product team ownership of its own project namespace, give the platform team ownership of the foundation layer and the shared ESC environments, and let teams read each other's exports only through explicit grants.

Tenancy for your customers, where you are building a product that provisions infrastructure on behalf of end customers, is a different design. Here the pattern is one stack (or one project) per tenant, stamped out by the Automation API, with the tenant's configuration and credentials held in a per-tenant ESC environment. The Pulumi Cloud organisation is then your boundary, not theirs, so if a customer demands that their state live in their own account you need a separate organisation, a DIY backend in their cloud, or a self-hosted instance.

Execution isolation is the piece people forget. If two tenants' updates run on the same shared runner, one tenant's program can read the other's environment variables and leftover files. Deployment agent pools (customer-managed runners for Pulumi Deployments) and ephemeral, per-job runners keep execution inside your network and keep tenants apart. Whichever you choose, the rule is the same as for any CI: one job, one identity, one clean workspace, destroyed afterwards.

Here is a minimal Automation API pattern for per-tenant stacks, with the two behaviours a platform must not skip: bounded concurrency and explicit handling of the lock error.

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

export async function provisionTenant(tenant: string, region: string) {
  const stack = await LocalWorkspace.createOrSelectStack({
    stackName: `acme/tenant-stack/${tenant}`,
    workDir: "./tenant-program",
  });
  await stack.setConfig("aws:region", { value: region });
  await stack.setConfig("tenantId", { value: tenant });
  try {
    const res = await stack.up({ onOutput: (line) => process.stdout.write(line) });
    return res.outputs;
  } catch (e) {
    if (e instanceof ConcurrentUpdateError) {
      // Another update holds this tenant's stack: queue it, never force it
      throw new Error(`tenant ${tenant} is busy, retry later`);
    }
    throw e;
  }
}

The Automation API requires the Pulumi CLI on the machine that runs it, and it checks a minimum CLI version (PULUMI_AUTOMATION_API_SKIP_VERSION_CHECK bypasses that, which you should not do in production). RemoteWorkspace instead runs the operation through Pulumi Deployments, which removes the need to install the CLI in your service and moves execution to a managed or agent-pool runner.

Cost

Pulumi has two cost centres, and only one of them is on the Pulumi invoice. The other is the cloud spend that your infrastructure code creates, which a platform team is usually best placed to influence.

For Pulumi Cloud, September 2026 pricing is structured as editions with included credits and a managed-resource allowance, and then metered beyond that:

Check the pricing page before quoting any of these to finance, because editions change. The metering model is the durable part: infrastructure resources are billed hourly (a fraction of a cent per resource-hour, varying by edition), ESC secrets are billed per secret per month, API calls beyond a free monthly allowance are billed per ten thousand, Pulumi Neo is billed per million tokens, and Deployments minutes beyond the allowance are billed per minute.

That model has design consequences you can act on:

• Resources are billed while they exist under management. Ephemeral environments are therefore cheap only if they are actually destroyed. Use TTL stacks or schedules in Pulumi Deployments so a preview environment disappears by itself, and use pulumi destroy --remove in pipelines.
• Not everything needs to be a managed resource. A thousand IAM policy attachments count the same as a thousand databases for metering. Consolidate where it does not hurt readability.
• Shared secrets are cheaper than copied secrets. A secret stored once in a shared ESC environment and imported everywhere is one metered secret. The same value copied into forty stack configs is forty places to rotate and, under ESC, potentially forty charges.
• Polling costs money. A dashboard that calls the API every few seconds for every stack can exceed the free API allowance quickly. Use webhooks for events, and pulumi api --paginate sparingly.

Against that, the open-source CLI with a DIY backend costs nothing in licences. The bill comes back as engineering time: you build locking discipline, history, RBAC approximations and secrets management, and you give up ESC, Deployments, Insights and managed policies. For a team of five with one product that is a fair trade. For a platform serving forty engineers, the engineering time almost always exceeds the subscription.

The other cost centre is the cloud bill, and a platform can make it visible by default. Enforce cost tags through a policy pack so untagged resources cannot be created, expose per-stack cost as a metric, and use pulumi preview output as an input to cost estimation before a change merges. A policy that refuses an over-sized instance type is worth more than a monthly report that shows it after the fact.

Upgrades and migrations

An upgrade story is what separates a platform from a pile of scripts. Pulumi has four independently versioned things, and each needs its own policy: the CLI, the language SDK (@pulumi/pulumi, the pulumi package on PyPI, or the Go module), the provider packages, and your own components.

The CLI moves fast and stays backwards compatible in most ways, but 2026 had several changes that would have hurt an unprepared platform. Keep this list in your upgrade runbook:

Pin the CLI in CI (the install script's --version flag, or the Actions pulumi-version input) and enforce a minimum with requiredPulumiVersion in Pulumi.yaml. Upgrade by promoting through environments: a canary project, then non-production, then production, with a week between steps. Because the CLI is released about weekly, "always latest" is a policy of perpetual change, and "never upgrade" is a policy of eventual emergency.

The SDK should stay close to the CLI. The Automation API checks the minimum CLI version it needs, and an SDK far behind the CLI misses fixes. Change both together in one reviewed pull request.

Providers are where real risk lives, because a provider major version changes how resources map to cloud objects. The AWS provider is at v7 as of this writing, and moving between majors can rename resources, change defaults and alter which properties force replacement. The safe procedure is mechanical:

# 1. Upgrade the package on a branch, in a non-production stack first
npm install @pulumi/aws@7

# 2. Read the diff like a change request, not like noise
pulumi preview --diff --stack acme/app/staging

# 3. Machine-check that nothing is replaced or deleted
pulumi preview --json --stack acme/app/staging \
  | jq '[.steps[] | select(.op=="replace" or .op=="delete" or .op=="create-replacement")] | length'

# 4. Only when that number is expected, apply; then prove convergence
pulumi up --stack acme/app/staging
pulumi preview --expect-no-changes --stack acme/app/staging

A few notes. The exact JSON shape of preview output has changed across CLI versions (newer CLIs also offer --output json for a structured summary), so verify the jq path against your version before wiring it into a gate. The important part is the principle: an upgrade PR is approved by reading the preview of every stack it touches, and a replace of anything stateful blocks the merge until a human has decided how to handle it. If a provider upgrade wants to replace a database, the answer is usually to add protect, apply the upgrade with ignoreChanges or aliases as the migration guide recommends, and handle the replacement separately.

Components follow semantic versioning if you publish them, and a platform should honour that. Renaming a component's type token or its child names is a replacement of everything inside it, unless you provide aliases. Since v3.264.0 there is also a stateMigrations resource option (Node.js, Python and Go) for migrating component state. The habit to build is that refactors which do not change infrastructure must produce an empty preview:

// Refactor: the component was "vpc", now lives inside a Network component.
// Aliases tell the engine these are the same resource, so nothing is replaced.
const vpc = new aws.ec2.Vpc(`${name}-vpc`, { cidrBlock: args.cidr }, {
  parent: this,
  aliases: [{ name: "vpc", parent: pulumi.rootStackResource }],
});

When aliases are not enough, state surgery is the tool. The state commands are sharp, so they belong to the platform team and deserve a runbook:

• pulumi state get <urn> to read one resource's recorded state.
• pulumi state rename <urn> <new-name> to rename a logical name without a replace.
• pulumi state move --source <stack> --dest <stack> <urn> to move a resource between stacks, for splitting a monolith.
• pulumi state remove <urn> (alias delete) to forget a resource without deleting it, used with care and in dependency-safe order.
• pulumi state protect and pulumi state unprotect to flip the protect flag.
• pulumi state edit to hand-edit state in your editor, which is the last resort before exporting JSON.
• pulumi state repair for integrity problems, and --disable-integrity-checking only as a last resort.

Every one of these should be preceded by pulumi stack export --file backup.json, and followed by pulumi preview --expect-no-changes. A state operation without a backup and a proof is a gamble.

Adopting existing infrastructure

Most platform work starts with estate that already exists, created by console clicks, CloudFormation, or Terraform. Pulumi gives you several routes. pulumi import generates code and records state for a resource; for bulk work, pulumi preview --import-file import.json builds a file you can edit and feed to pulumi import --file import.json. pulumi convert --from terraform --language typescript --out ./ts translates HCL to a Pulumi program, and since v3.235.0 the CLI bundles an hcl language host, so runtime: hcl runs HCL directly. Using a Terraform-only provider is possible with pulumi package add terraform-provider <org/name>. The adoption rules that protect you:

1. Import first, refactor second. Get an import that previews clean before you improve the code.
2. Keep imports protected until a resource has survived several reviewed updates.
3. Never run pulumi up against an imported resource whose generated code you have not compared to the live object. The preview will show what the generated code would change.
4. Migrate one stack at a time, and freeze changes in the source tooling during the window so the two systems do not fight.

Governance with policy

A platform with no guardrails is a platform where the first person to hold production credentials defines your security posture. Pulumi Policies (formerly CrossGuard) lets you express rules as code, evaluated against the planned state at preview time, which means they see the same resources the engine is about to create.

A policy pack is a program in TypeScript, JavaScript or Python, or an OPA (Rego) bundle, and Go is supported through policyx. Each policy carries an enforcement level:

Packs run in preventative mode (during preview and up) or audit mode against existing resources, which is how you learn what is already non-compliant before you enforce anything. A minimal rule:

import * as aws from "@pulumi/aws";
import { PolicyPack, validateResourceOfType } from "@pulumi/policy";

new PolicyPack("acme-baseline", {
  policies: [{
    name: "s3-requires-cost-tag",
    description: "S3 buckets must carry a cost-centre tag.",
    enforcementLevel: "mandatory",
    validateResource: validateResourceOfType(aws.s3.Bucket, (bucket, args, report) => {
      if (bucket.tags === undefined || bucket.tags["cost-centre"] === undefined) {
        report("Buckets must carry a cost-centre tag.");
      }
    }),
  }],
});

The rollout path is the governance skill. Publish the pack with pulumi policy publish, enable it with pulumi policy enable <org>/<pack> latest --policy-group <group> in advisory mode for a policy group that contains one friendly team, collect the warnings for two weeks, and only then promote the rules that are genuinely non-negotiable to mandatory. Policy groups (pulumi policy group new) let you apply a stricter pack to production stacks than to sandboxes. Pack behaviour can be tuned with a config file passed via --policy-pack-config, and pulumi policy analyze runs a pack over an exported state, which is how you score an existing estate.

Governance is also about people and change flow. Four mechanisms matter most:

• Review gate on preview. Every pull request gets a preview comment (the GitHub Action pulumi/actions@v7 can post it with comment-on-pr), and merging requires a human to have read it.
• Custom roles. Give the pipeline identity permission to update, and give people permission to preview and read. Humans updating production by hand should be rare and logged.
• Audit logs. Available from the Essentials edition; export with pulumi audit-log export and ship to your SIEM. A log nobody reads is a compliance artefact, not a control, so alert on the few events that matter: changed policy groups, role grants, token creation, and --ignore-protect runs.
• Webhooks. Stack and organisation webhooks can post to Slack, Teams or an HTTP endpoint on update, which turns production changes into visible events.

Running Pulumi as a platform

You own this as a service for other teams now, so the question becomes the product: what do you give engineers, and what do you make impossible? Four pieces make up a mature platform.

Golden paths: templates, components and a registry

Give teams a fast way to do the right thing. A component wraps a recommended pattern (a network, a service with its IAM role and alarms, a database with backups) behind a small typed interface:

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

export interface ServiceArgs {
  image: pulumi.Input<string>;
  cpu?: number;
  memory?: number;
  costCentre: string;
}

export class Service extends pulumi.ComponentResource {
  public readonly url: pulumi.Output<string>;

  constructor(name: string, args: ServiceArgs, opts?: pulumi.ComponentResourceOptions) {
    super("acme:platform:Service", name, {}, opts);
    const tags = { "cost-centre": args.costCentre, "managed-by": "pulumi" };
    const role = new aws.iam.Role(`${name}-task`, {
      assumeRolePolicy: aws.iam.assumeRolePolicyForPrincipal({ Service: "ecs-tasks.amazonaws.com" }),
      tags,
    }, { parent: this });
    // ... cluster, task definition, service, alarms: all with { parent: this }
    this.url = pulumi.output("https://" + name + ".internal.example.com");
    this.registerOutputs({ url: this.url });
  }
}

Two rules keep components maintainable. Every child resource sets parent: this, which groups them in the URN and in the console, and every child name is prefixed with the component's name, which prevents the classic Duplicate resource URN error when two instances exist. Publish components as packages so they are versioned: pulumi package publish, a git-referenced pulumi package add, or through the Pulumi Cloud Private Registry. A component written in one language can be consumed from another through a component provider host (componentProviderHost in Node.js, component_provider_host in Python) and pulumi package add, which matters for organisations with both TypeScript and Python teams.

Pair components with templates (pulumi new <template>, registry-backed) so a new project starts already wired to the right backend, secrets provider, ESC environment and policy pack. Remember that since v3.258.0 pulumi new asks for a cloud provider and a language rather than listing every template, and recordings from before August 2026 are out of date.

Delivery: pipelines, Deployments and the Kubernetes Operator

There are three mainstream ways to run updates, and they differ in who owns the runner.

The pipeline shape that works is the same across them: a pull request runs pulumi preview and posts the result; merge to the protected branch runs pulumi up using OIDC-issued credentials; nothing else can reach production. A skeleton for GitHub Actions:

name: infra
on:
  pull_request: { paths: ["infra/**"] }
  push: { branches: [main], paths: ["infra/**"] }
permissions: { id-token: write, contents: read, pull-requests: write }
concurrency:
  group: pulumi-${{ github.ref }}-prod     # one run per stack, never two
  cancel-in-progress: false                # never kill an update mid-flight
jobs:
  pulumi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
        working-directory: infra
      - uses: pulumi/auth-actions@v1
        with: { organization: acme, requested-token-type: urn:pulumi:token-type:access_token:organization }
      - uses: pulumi/actions@v7
        with:
          command: ${{ github.event_name == 'pull_request' && 'preview' || 'up' }}
          stack-name: acme/app/prod
          work-dir: infra
          comment-on-pr: true

Note cancel-in-progress: false. Cancelling a running update is exactly how you manufacture pending operations, so a platform pipeline queues rather than cancels. Pin the action and the CLI version, and check the inputs against the action's current README, since inputs evolve.

Drift needs a schedule, not a hope. Use Pulumi Deployments drift detection (pulumi stack schedule and pulumi stack drift status) or a scheduled pipeline that runs pulumi preview --refresh --expect-no-changes and alerts on failure. Decide in advance whether drift is reported or remediated, because auto-remediation silently reverts an emergency change made during an incident.

Testing your platform code

Infrastructure code has three testing layers, and each proves a different thing.

1. Unit tests with mocks (pulumi.runtime.setMocks in Node.js, pulumi.runtime.set_mocks in Python, pulumi.WithMocks in Go) run the program without a cloud. They are fast and good for checking your components' logic, such as "every child has a cost tag". They prove nothing about what the provider will do.
2. Policy checks are property tests on the planned state. They catch classes of problem (public buckets, missing encryption) regardless of which program produced them.
3. Integration tests that deploy a real ephemeral stack through the Automation API (or ProgramTest in Go), assert against the live result, and destroy it. They are slow and cost money, and they are the only tests that can detect a provider behaviour change.

Run the first two on every pull request and the third nightly and before publishing a new component version.

Incident playbooks

Most Pulumi incidents fall into a handful of shapes. Write a playbook for each, because the wrong first move (usually pulumi cancel or --target) makes them worse.

Pending operations and held leases are the two you will meet most. Practise both in a game day. The exercise that pays back most is to deliberately kill a production-like pipeline mid-update in a sandbox, hand the team only the runbook, and time how long they take to reach a clean preview.

There is also the lower-level diagnostic kit. -v=<0..11> with --logtostderr raises verbosity; --logflow passes the level to provider plugins; --debug (-d) prints more; --tracing and --otel-traces emit traces; and PULUMI_DEBUG_GRPC=<file> records the gRPC conversation between engine and plugins. Since v3.249.0 every command also writes automatic encrypted logs under ~/.pulumi/logs, managed with pulumi logs list|remove|decrypt|share, which means you can ask an engineer to share a failing run's log rather than reproducing it. Do not confuse these with plain pulumi logs, which is an experimental command for aggregated resource logs.

Where Pulumi stops

A platform owner's credibility depends on knowing when not to use the tool. Pulumi is an excellent fit for cloud infrastructure that benefits from real programming languages, but there are boundaries.

• Application deployment and GitOps. Pulumi can manage Kubernetes resources, Helm charts and Kustomize, and the Kubernetes Operator reconciles from a cluster. For continuous reconciliation of application manifests with progressive delivery, dedicated GitOps controllers such as Argo CD or Flux are the more established choice, and many organisations use Pulumi for the cluster and Argo CD for what runs on it. See Kubernetes and Helm for the other side of that line.
• Teams whose skills and estate are already in HCL. Terraform has the largest ecosystem, and Pulumi can run HCL natively or consume Terraform providers, but a mature Terraform organisation with working modules gains little from a rewrite. The honest driver to migrate is a need for real abstractions, testing in a general-purpose language, or one language across application and infrastructure, not fashion.
• Very dynamic programs. Because the program is code, it can do anything, including things that make previews unpredictable: network calls, randomness, reading files that change. Constrain programs to deterministic logic, or the preview stops being a promise.
• Configuration management on machines. Installing packages and editing files on a fleet of hosts is the job of Ansible or an image pipeline, not of a declarative resource engine.
• Environments that cannot run the CLI or reach a backend. Air-gapped sites need a DIY backend or self-hosted Cloud, a plugin mirror, and effort. If you cannot afford that effort, choose a tool whose dependencies you already operate.
• Very large flat estates. Thousands of resources in one place will be slow in any state-based tool. The answer is always to split, and if you cannot split, Pulumi will not save you.

Also consider the experimental surface. pulumi do, snippets, pulumi neo and pulumi insights are new in 2026 and their behaviour is still moving. They are interesting for individuals exploring, and they do not belong on your critical path until you have read their current documentation and accepted the churn.

The review checklist

Use this for pull requests that touch infrastructure code and for design documents that propose a new stack, component or workflow.

For a pull request

1. Did the author attach or link the pulumi preview output, and did a reviewer read every +- replace and every - delete?
2. Are stateful resources (databases, buckets with data, keys, load balancers with DNS names) protected or retainOnDeleted?
3. Are secrets marked with --secret, requireSecret or pulumi.secret, and do none appear in plain exports or logs?
4. Do new stack-reference outputs have names that will still make sense in a year, and does every consumer use requireOutput?
5. Were any logical names, parents or types changed, and if so is there an alias or a state operation, with an empty preview as proof?
6. Are provider and SDK versions pinned, and did a provider upgrade come with its own preview across every affected stack?
7. Does the change pass the mandatory policy pack, and was any exception recorded with an owner and an expiry?
8. Are new resources tagged for cost and owner?
9. Does the program do anything non-deterministic (network calls, random, time)?
10. Is there a documented way to roll back, and have you checked it is not "restore the database"?

For a design document

1. What is the blast radius of one bad update, and can it be smaller?
2. Where does state live, who holds the lock, and what is the recovery if the lock-holder dies?
3. Which credentials does the pipeline use, how long do they live, and who can change the pipeline?
4. How will this upgrade in a year, at the CLI, SDK and provider levels?
5. Which team owns each stack, component and ESC environment?
6. What does this cost under metering, and what deletes it when it is no longer needed?
7. Which part is experimental, and what is the exit if it changes?

The complete picture

Read the diagram as a single argument. Small, well-bounded stacks keep any failure contained. Components and a registry make the safe pattern the easy one. Preview and policy make the change reviewable and the rules enforceable. Short-lived credentials and serialised delivery mean the pipeline is both safe and predictable. Drift detection and audit logs tell you when reality and the code disagree, and who did what.

Everything else in this guide is detail about one of those boxes: what state is and how it fails, which backend to trust, where a secret can leak, how to cost it, how to upgrade it, and when to choose something else. If you can explain each box to a new engineer and each failure to an incident commander, you own the platform rather than merely operating it.

Where the series leaves you

Across three levels you went from running pulumi up on a bucket, to structuring real projects with components, stack references, ESC and policies, to owning the platform for other teams: its failure modes, its trust model, its cost, and its limits. The next steps are practical rather than theoretical.

• Run the game day in the incident section this month, with the runbook only.
• Publish one component to a private registry and have a second team use it.
• Move one long-lived cloud key out of CI and replace it with OIDC, then do the next.
• Pair this guide with the neighbouring ones: Terraform for the ecosystem you will be compared against, Kubernetes and Helm for what your clusters will run, Argo CD for GitOps, and Docker for the images it all deploys.
• Read the changelog every month. Pulumi moves weekly, and the platform owner is the person who reads it so nobody else has to.

Sources

• Pulumi documentation
• Pulumi CLI releases
• Pulumi changelog
• Download and install
• How Pulumi works
• State and backends
• Using a DIY backend
• CLI environment variables
• Resource options
• Inputs and outputs
• Secrets
• Stacks
• Components
• pulumi state command reference
• Importing resources
• Automation API
• Troubleshooting
• Update conflicts
• Interrupted updates
• Destroy failures
• GitHub Actions guide
• Pulumi Kubernetes Operator
• Pulumi ESC
• ESC migration from the standalone CLI
• Pulumi Policies
• Pulumi Deployments
• OIDC access management
• Self-hosting Pulumi Cloud
• Pricing

Part three of three. The senior interview is not a quiz on flags. It asks whether you can be trusted to own the system other people deploy through: to design it, to recover it at two in the morning, and to explain your choices to someone who controls the budget. This file is organised as system-design prompts, incident-response questions, and trade-off arguments, with a description of what a strong answer contains that a weak one misses. Plan on about fifty minutes.

How to use this file

Read each prompt, answer it aloud or on paper for three minutes, then compare with the model answer. The model answers are deliberately shaped the way a good interview answer is: a stated assumption, a structure, the trade-off, and the failure mode. Interviewers at this level are listening for that shape far more than for any single fact.

Two habits separate strong candidates. First, name the blast radius before the solution: "the risk here is that one update can touch everything, so I would..." Second, say what you would measure: a platform without a number attached to it is an opinion.

The thirty-second answer

Pulumi is an infrastructure-as-code engine where you declare resources in a general-purpose language. Running the program registers resources with an engine that diffs them against recorded state and calls providers to make the cloud match. As a platform it is the state backend, the secrets and identity model, the component library, the policy layer and the delivery pipeline, and my job is to make the safe way the easy way for every team.

System-design prompts

Prompt 1: Design the Pulumi platform for forty engineers in six teams

A strong answer begins by asking four questions: how many clouds and accounts, what compliance regime, how many environments, and what the existing tooling is. Then it commits.

Structure. One organisation in Pulumi Cloud, because teams, roles, ESC and policy groups all live there. Projects cut by lifecycle and owner: a foundation project (networks, accounts, identity), a platform project (clusters, shared services), data projects, and one or more application projects per team. One stack per environment per project. Dependencies flow one way, downwards through layers, and cross-stack values travel as stack-reference outputs for infrastructure identifiers and as ESC environments for configuration.

Identity. No static cloud keys anywhere. CI authenticates to Pulumi with OIDC (pulumi/auth-actions@v1 or pulumi login --oidc-token), and ESC assumes a per-environment cloud role with fn::open::aws-login or the Azure and GCP equivalents. The trust policy on each role names the repository and branch, so only the protected branch can assume production.

Delivery. Pull requests run pulumi preview and post it, merge to the protected branch runs pulumi up, and a concurrency group per stack means two updates can never start together. cancel-in-progress is false, because cancelling an update manufactures pending operations.

Guardrails. A policy pack published to the organisation, enabled through policy groups: advisory for sandboxes, mandatory for production. Custom roles so pipeline identities can update and humans can preview and read.

Golden paths. Components published to the private registry and templates that wire a new project to the right backend, secrets provider, ESC environment and policy pack.

What I would measure. Median and p95 preview time, the number of stacks above a thousand resources, drift detections per week, time to recover a stuck stack, percentage of resources created through components, and the count of long-lived credentials remaining.

What a weak answer does: describes pulumi up and a bucket, picks a single stack for everything because it is simpler, puts a cloud key in a CI secret, and never mentions failure or who owns what.

Prompt 2: We have a two-thousand-resource stack that takes fifteen minutes to preview. What do you do?

Start by measuring: run the slow operation with --otel-traces and find whether the time is in the provider calls, the program's start-up, or plugin loading. Do not guess.

Then address the structural cause. A stack of that size is carrying several lifecycles together, and the fix is to split it by lifecycle and owner. You can do that without an outage using pulumi state move --source ... --dest ... to transfer resources between stacks, and stack references or ESC to reconnect the pieces. Every move is preceded by pulumi stack export and followed by pulumi preview --expect-no-changes in both stacks.

While splitting, there are quick wins: lower or raise --parallel depending on whether the cloud API is throttling, pre-install plugins in the runner image, and make refresh a scheduled job rather than part of every update. I would be explicit that --target is an emergency tool, not the answer, because it skips the checks the team relies on.

What the interviewer listens for: that you measure first, that you treat splitting as a state migration with backup and proof, and that you do not propose "just use --target".

Prompt 3: Migrate from Terraform to Pulumi without an outage

Anchor on the fact that the cloud resources do not change; only who manages them does. So the migration is about state, and the risk is two tools managing the same object at once.

1. Inventory and choose the order. Migrate leaf stacks first, foundations last, or the reverse if the foundation is stable and small. One stack at a time.
2. Generate. pulumi convert --from terraform --language typescript --out ./ts translates the code, or run the HCL unchanged with runtime: hcl while you learn, since the CLI bundles the HCL language host. For providers that exist only in Terraform, pulumi package add terraform-provider <org/name> wraps them.
3. Adopt the real resources with pulumi import, or pulumi preview --import-file import.json and pulumi import --file import.json for bulk. CLI imports are protected by default, which I keep until the resource has survived reviewed updates.
4. Prove equivalence. pulumi preview --expect-no-changes must be clean before any update. If it wants to change something, the generated code does not match reality, and I fix the code, not the resource.
5. Cut over with a freeze. Stop Terraform applies for that stack, remove the resources from Terraform state with terraform state rm (so nothing is destroyed), and let Pulumi own it. Only then start improving the code.
6. Keep a read bridge for stacks not yet migrated, by reading Terraform outputs from Pulumi during the transition.

I would add honestly: if the organisation's Terraform is healthy, the reason to migrate must be concrete (real abstractions, testing in a general-purpose language, one language across the stack), and I would run a pilot on one team before committing the company.

A weak answer says "convert and run pulumi up", which creates duplicate resources or fails with name collisions.

Prompt 4: Build a self-service portal where teams request environments

The pattern is the Automation API: a service that accepts a request, creates or selects a stack, sets configuration, runs up, and returns outputs. The design questions are the ones that matter.

• Identity: the service assumes a role per tenant or environment via OIDC, never a shared key.
• Concurrency: it serialises per stack and handles ConcurrentUpdateError by queueing, never by forcing.
• Isolation: each run gets a clean workspace on an ephemeral runner, so one request cannot read another's files or environment. Pulumi Deployments with an agent pool, or one-shot containers, both work.
• Lifecycle: every environment has an owner and a TTL, and a schedule destroys expired ones. Otherwise you are building a cost leak with a nice user interface.
• Auditability: every request and every update links to a person, using audit logs and stack tags.
• Failure handling: a failed provisioning is a first-class state with a retry and a clean-up path, because half-created tenants are the normal case, not the exception.

If the portal should not depend on installing the CLI in the service, RemoteWorkspace runs the operation through Deployments instead.

Prompt 5: Design secrets management for a regulated workload

Two questions first: where must key material live, and who is allowed to decrypt? For a bank in the Gulf or an Egyptian government workload, the answer is often "a key in a specific region that the security team controls".

I would use a KMS-backed secrets provider (awskms, azurekeyvault, gcpkms or hashivault) pinned to an in-region key, with IAM on the key that grants decrypt only to the pipeline role and a small break-glass group. Runtime secrets stay in the cloud's secrets manager and are referenced from Pulumi ESC through fn::open providers, so they are fetched, not copied. Anything that has to sit in config is set with --secret. I mark provider outputs that are sensitive with additionalSecretOutputs, and I add a policy that denies plaintext secrets in resource inputs where a policy can detect them.

Then I would state the limits out loud: state still contains non-secret metadata, --show-secrets prints plaintext so it is restricted by role and audited, and a secret in history is not removed by rotation. A strong answer names the leak paths; a weak one says "Pulumi encrypts secrets".

Incident-response questions

Q: A production update was killed by a CI timeout. What now?

First, do not run anything. Check that the update is actually dead, in the console or with pulumi stack history. Only then clear the lock if one lingers with pulumi cancel. Expect a pending-operations warning on the next run. Decide per resource: if the thing was not created, pulumi refresh --clear-pending-creates --yes; if it was, pulumi refresh --import-pending-creates <URN> --import-pending-creates <physicalId> --yes; if unsure, run pulumi refresh interactively and inspect. Finish with pulumi preview --expect-no-changes.

The prevention half is what earns the marks: raise or remove the timeout on apply steps, never cancel in progress, and serialise per stack.

Q: pulumi preview on a routine change wants to replace the production database. Walk me through it.

I stop the merge. I read pulumi preview --diff to find which property forces replacement. The usual culprits are a provider upgrade that changed a property's behaviour, a renamed logical name or changed parent (so the engine sees a new resource), or a property that is genuinely immutable in the cloud. For the rename, I add aliases. For a provider change, I use the migration guide, possibly ignoreChanges for the property while I plan the real migration. For a genuinely immutable property, it becomes a planned migration with a snapshot and a maintenance window, not a routine update.

And the structural fix: the database should have been protect: true, in which case the engine would have refused with cannot be deleted because it is protected. That sentence, a protected resource turns a disaster into an error message, is worth saying in the interview.

Q: Someone changed a security group by hand during an outage. What happens on the next update?

If nobody refreshed, nothing is noticed, and the next update may silently leave the change in place or revert it depending on what the code changed, because Pulumi does not refresh state by default. The correct first move is pulumi refresh --preview-only to see drift without touching state. Then decide which is right. If the console change was the correct emergency fix, put it in the code and run pulumi up. If it was wrong, pulumi up reverts it. The anti-pattern is refresh followed by up without looking, which launders the change into the state.

The platform answer: detect drift on a schedule (pulumi preview --refresh --expect-no-changes, or Deployments drift detection), and decide ahead of time whether drift is reported or auto-remediated, because auto-remediation can undo an emergency fix mid-incident.

Q: A secret was printed in CI logs. What do you do?

Rotate first, then investigate. The credential is compromised the moment it was logged, and cleaning the log does not undo that. Update the stack's secret or the ESC value. Find the cause: usually a console.log inside apply, a --show-secrets flag, or an input that was never marked secret. Check the stack history and any exports or backups that may hold the old value. Add a control so it cannot recur, such as a lint rule, a masked log step, and a policy. Write down the exposure window, because compliance will ask.

Q: pulumi destroy fails halfway through. The team wants to delete the stack.

Do not pulumi stack rm --force a stack that still owns real resources, because that orphans them with no owner and no record. Read the error. If it is stale credentials, use pulumi destroy --run-program so current credentials apply. If the cloud refused because of deletionProtection, forceDestroy or disableApiTermination, change the attribute in code, run pulumi up, then destroy. If a resource is already gone outside Pulumi, pulumi refresh reconciles it, and pulumi state remove <urn> forgets one that cannot be reconciled. Only when the stack is empty is pulumi stack rm correct.

Q: Pulumi hangs forever on a new build agent and prints nothing.

Suspect the environment, not Pulumi. The CLI, language host and providers talk over gRPC on 127.0.0.1, so a proxy that intercepts loopback is the classic cause. Exclude 127.0.0.1 and localhost with NO_PROXY, and allow outbound HTTPS to api.pulumi.com. Second suspect: the wrong CPU architecture (an x86_64 build under Rosetta on Apple silicon). Verify with file $(which pulumi). Third: missing plugins and a blocked download host, which pulumi install or a pre-baked runner image resolves. A candidate who asks "what changed on this machine?" before touching Pulumi's configuration is showing seniority.

Q: A state file looks corrupt after an engine bug. Options?

Export first. On the Cloud backend, integrity problems are repaired automatically in many cases since v3.226.0. Otherwise pulumi state repair attempts a fix. As a last resort, --disable-integrity-checking lets you proceed so you can export, inspect, edit with pulumi state edit or by hand, and import. Every step is paired with a backup and followed by preview --expect-no-changes. Mention that DIY backends have the additional risk of partial writes, and that bucket versioning is what lets you roll back.

Trade-off questions and how to argue them

The senior skill is making a recommendation that survives challenge. For each of these, the structure is the same: state the options, state the criteria, recommend, and state what would change your mind.

Pulumi Cloud versus a DIY backend

Options: the managed service, the self-hosted Enterprise edition, or an object-store backend. Criteria: team size, compliance, engineering time, and features needed. Pulumi Cloud gives locking with leases, history, RBAC, audit logs, ESC, Deployments and managed policies. A DIY backend is free and keeps state in your bucket, but it has file locks that cannot transparently recover from certain partial failures, no ESC, and no built-in RBAC, so you build those. Recommendation: for a platform serving many teams, the managed service, because the engineering time to replicate its features exceeds its cost. Self-host only when a data-residency or network-isolation requirement forces it. DIY for a single team or a constrained environment, with bucket versioning, a KMS secrets provider and serialised CI. What would change my mind: a regulator that forbids external state, or a customer whose contract requires state in their cloud.

Pulumi versus Terraform

Criteria: existing estate and skills, ecosystem coverage, the need for real abstraction and testing, and organisational risk appetite. Terraform has the larger ecosystem and more hiring depth. Pulumi lets you use a general-purpose language, unit-test with mocks, write components in the same language as your application, and stamp environments through the Automation API. Pulumi can consume Terraform providers and run HCL natively, so the ecosystem gap is smaller than it was. Recommendation: do not migrate a healthy Terraform estate for its own sake. Choose Pulumi for new platform work where abstraction and testing matter, and migrate gradually where a team has a concrete pain. Say aloud that the expensive part of any migration is people and process, not syntax.

Stack references versus ESC for sharing values

Stack references read another stack's outputs, which suits infrastructure identifiers produced by code, but they couple consumers to the producer's export names and require permission on the producing stack. ESC gives values an owner, versions, tags and their own access control, which suits configuration and secrets. Recommendation: references for produced infrastructure identifiers, ESC for configuration, and treat both as versioned public APIs.

Kubernetes Operator versus Deployments versus plain CI

Plain CI is simplest when you already run it well. Deployments gives managed runners, drift detection, TTL stacks and review stacks, at a per-minute cost beyond the allowance. The Operator reconciles from inside a cluster, good for GitOps-shaped teams, at the price of running another control plane with its own CRDs (Stack, Workspace, Update, Program). Recommendation: start with CI, move to Deployments when you need drift and ephemeral environments, and use the Operator only if your organisation is committed to in-cluster reconciliation.

Monorepo versus repo per stack

A monorepo makes cross-cutting changes and shared components easy and gives one place for policy, but needs path-filtered pipelines so a change to one project does not trigger every stack. A repo per stack gives clean ownership and permissions but fragments components and upgrades. Recommendation: a monorepo for foundation and platform code owned by one team, repos per product team for their application stacks, components in their own versioned repository.

Arguing a trade-off to leadership

Leadership does not want a tool comparison; it wants a decision framed in money, risk and time. Four techniques help.

Lead with the outcome, not the tool. "Right now a production change takes three days and needs two engineers who remember how the scripts work. The proposal reduces that to a reviewed pull request and a fifteen-minute pipeline."

Quantify the cost of the status quo. Incidents caused by manual changes, hours lost to environment setup, number of long-lived credentials, time to onboard an engineer. Even rough numbers change the conversation.

Put the price in their language. Pulumi Cloud is priced by edition plus metered managed resources, so you can give a per-month range from a real resource count. Then compare with the engineering time to build locking, history, RBAC and secrets management yourself. Quote from the current pricing page, not from memory.

Name the exit and the risk. Every decision has a reversal cost. Pulumi state can be exported, and pulumi stack migrate moves stacks between backends, so backend lock-in is lower than people fear. The real lock-in is the code and the team's skills, so you propose a pilot with a defined success measure and a date to review.

A worked example: justifying a policy programme

Suppose you want mandatory policies in production. The pushback will be that it slows teams down. A strong case runs like this: two security findings last quarter came from public buckets and over-broad IAM roles, both would have been blocked at preview. The pack will run advisory for a month so nobody is surprised; the false-positive rate is tracked and mandatory rules only start when it is below an agreed threshold. Exceptions have an owner and an expiry. The measurable outcome is fewer findings in audit and no increase in lead time, and you will report both. You have answered the objection before it was raised, and you have committed to a number.

Current-state questions you should be ready for

Senior interviews test that you are current, because platforms rot when their owners stop reading changelogs. Be ready to explain these as of CLI v3.266.0.

• Node.js requirement. The Node.js SDK requires Node.js 22 or later since v3.249.0, and TypeScript 7 is not compatible with Pulumi's runtime compilation.
• ESC CLI. The standalone esc CLI is retired. Everything is pulumi env ....
• Deployment settings. The committed Pulumi.<stack>.deploy.yaml file is gone since v3.251.0. Settings live in Pulumi Cloud and are managed with pulumi deployment settings get, edit and destroy.
• pulumi api. Renamed from pulumi cloud api, with --output replacing --format.
• Journaling. On by default since v3.225.0.
• DIY layout. The legacy non-project layout is an error since v3.257.0; pulumi state upgrade fixes it.
• pulumi logout. Deletes all backend configuration since v3.246.0.
• Backend migration. pulumi stack migrate since v3.254.0.
• Experimental features. pulumi do, snippets, pulumi neo and pulumi insights are new and still moving. Say that you would evaluate but not depend on them yet.

If you are asked about something you do not know, say so and describe how you would find out. "I would check the changelog and the resource options documentation" is a perfectly good senior answer. A confident wrong one is not.

What a strong answer covers that a weak one misses

Sixty-second self-test

Answer these without looking. If you hesitate on more than two, revisit the matching section of the detailed guide.

1. What are the three processes in a Pulumi update, and what do they use to talk to each other?
2. Why is an update not atomic, and what are the two dirty states it can leave?
3. Write the exact commands that resolve a pending create both ways.
4. What does protect guard against, and what does it not?
5. Why is a stack reference a public API?
6. Name four places plaintext can still leak from a Pulumi program that uses secrets.
7. What are the two OIDC exchanges, and which tool handles each?
8. Why does cancel-in-progress matter in a Pulumi pipeline?
9. How do you make a provider major upgrade safe?
10. Give two situations where you would tell a team not to use Pulumi.

If you can answer all ten in a minute, you are ready to be asked the harder versions by someone trying to find the edge of what you know.

Part three of three. At this level the problems are operational and they appear with scale: a stack that got slow by degrees, a pipeline that killed an update, a provider upgrade that wanted to replace a database, a secret that outlived its rotation. Start with the error table, then the platform habits, then the review checklists you can paste into your own templates.

Production traps that only appear at scale

Cumulative: everything from Beginner and Mid still applies. These cause incidents rather than failed first runs.

The practices that pay off most

These are in order of leverage. The first three remove most of the incidents on the list above.

Practice cards

1. Kill an update on purposeIn a sandbox, send kill -9 to pulumi up during a create. Read the pending-operations warning, then recover both ways: --clear-pending-creates and --import-pending-creates. Time yourself.
2. Trigger a 409Start two updates for one stack. Capture the exact error, then change the pipeline so the second cannot start. Confirm it queues rather than cancels.
3. Prove a rename is freeRename a logical name and watch the preview want a replace. Add an alias, preview again, and confirm it is empty. Repeat with pulumi state rename instead.
4. Split a stackMove three resources between two scratch stacks with pulumi state move. Export before, run --expect-no-changes in both after.
5. Audit your state for plaintextExport a stack without --show-secrets and search for anything secret-looking that is not encrypted. Fix each with requireSecret or additionalSecretOutputs.
6. Upgrade a provider safelyBump a provider one major version on a branch, read preview --diff across every affected stack, and list every replace. Decide what you would do about each.
7. Score your estate with a policyWrite one tag policy and run pulumi policy analyze --file state.json on an export. Count existing violations before deciding an enforcement date.
8. Trace a slow previewRun --otel-traces file:./trace.json on your slowest stack and identify the five longest spans. Decide whether the fix is splitting, parallelism, or plugins.

Platform-ownership habits

Owning a platform is a different job from using a tool. These habits are what people notice after you have done it for a year.

Publish a contract, not a wiki. Each stack has a README that lists its owner, what it exports, what it consumes, and how to reach the on-call. Exports are treated as a versioned API: add new names, deprecate old ones on a stated schedule, and never rename silently. A stack reference from another team is an access grant and a coupling, so record it.

Give every team a paved road. Publish components to the private registry, provide templates that wire in the backend, secrets provider, ESC environment and policy pack, and make the paved road faster than the alternative. A component is successful when teams use it without asking you. Count the percentage of resources created through components and watch it climb.

Own the upgrade calendar. Pulumi ships weekly. Decide a rhythm, for example a monthly CLI upgrade through canary to production, and a provider upgrade per quarter, each with a preview review. Publish the calendar. Read the changelog and post the two or three changes that matter, such as the 2026 removals of Node 20 support, the deploy settings file and the standalone esc CLI, so no team is surprised.

Keep break-glass real. Emergencies happen, and someone will need to pulumi cancel, --ignore-protect or --show-secrets. Define who may do it, how it is logged, and review each use. Alert on these in audit logs. A break-glass path that is undocumented becomes a habit, and a habit becomes the normal workflow.

Measure the platform. A small set of numbers tells you whether it is healthy.

Treat experiments as experiments. pulumi do, snippets, pulumi neo and pulumi insights are new and their behaviour is still moving. Let individuals try them, write down what you learn, and keep them off the critical path until the documentation is stable. Say this explicitly to teams, so nobody builds a dependency by accident.

Teach the recovery, not just the workflow. Run a game day twice a year. Hand the team only the runbook, break a sandbox stack in one of the ways in the table above, and measure the time to a clean preview. The runbook improves every time, and the team stops fearing state.

Do and do not

A timeline of a bad update, and the control that would have stopped it

Review checklists

Paste these into pull request templates and design-document templates. They are intentionally short, so people actually use them.

For a pull request touching infrastructure code

• The pulumi preview output is attached, and a reviewer has read every +- and -.
• Stateful resources are protected or retainOnDeleted.
• Secrets use --secret, requireSecret or pulumi.secret, and none appear in exports or logs.
• No logical name, type or parent changed without an alias or a state operation, proven by an empty preview.
• New stack outputs have stable names and every consumer uses requireOutput.
• Provider, SDK and CLI versions are pinned, and any provider major upgrade has a preview diff for every affected stack.
• Mandatory policies pass, and any exception has an owner and an expiry.
• Every new resource carries the owner and cost tags.
• Nothing in the program is non-deterministic: no network calls, randomness or time-dependent values feeding resources.
• Nothing creates resources inside an apply callback.
• There is a stated rollback that does not depend on a database restore.

For a design document proposing a new stack, component or workflow

• What is the blast radius of one bad update, and can it be smaller?
• Where does state live, who holds the lock, and how is it recovered if the holder dies?
• Which identity does the pipeline use, how long does its credential live, and who can change the pipeline?
• Which secrets exist, where are they stored, and which secrets provider protects them?
• Which stacks does this read from and which read from it?
• How does it upgrade over the next year at CLI, SDK, provider and component level?
• What does it cost under metering, and what removes it when it is no longer needed?
• How is drift detected, and what happens when it is found?
• Which parts are experimental, and what is the exit if they change?
• Who owns it, and who is on call?

For a provider or CLI upgrade

• Release notes and the provider's migration guide read, with the breaking changes listed in the PR.
• Non-production stacks upgraded first, with preview --diff read in full.
• A machine check confirms no unexpected replace or delete.
• After apply, pulumi preview --expect-no-changes is clean.
• The CLI version in CI and in requiredPulumiVersion has been updated together.
• Node.js, Python and Go runtimes on runners meet the new minimums (Node.js 22 or later).

Operational recipes

Short commands worth having in a runbook. Each assumes you have exported state first if it changes anything.

# Who holds the stack right now?
pulumi stack history --stack acme/app/prod | head -20

# See drift without changing state
pulumi refresh --preview-only --stack acme/app/prod

# CI drift gate: fails the job if code and cloud disagree
pulumi preview --refresh --expect-no-changes --non-interactive --stack acme/app/prod

# Clear a pending create that was never actually created
pulumi refresh --clear-pending-creates --yes --stack acme/app/prod

# Adopt a pending create that does exist (two consecutive flags per resource)
pulumi refresh --yes --stack acme/app/prod \
  --import-pending-creates 'urn:pulumi:prod::app::aws:s3/bucket:Bucket::logs' \
  --import-pending-creates 'acme-prod-logs'

# Back up, move a resource between stacks, prove both sides
pulumi stack export --file backup-src.json --stack acme/monolith/prod
pulumi stack export --file backup-dst.json --stack acme/data/prod
pulumi state move --source acme/monolith/prod --dest acme/data/prod \
  'urn:pulumi:prod::monolith::aws:rds/instance:Instance::main'
pulumi preview --expect-no-changes --stack acme/monolith/prod
pulumi preview --expect-no-changes --stack acme/data/prod

# Debug a failing plugin: verbose logs to stderr, flowed to providers
pulumi up -v=9 --logtostderr --logflow 2> pulumi-debug.log

# Emit OpenTelemetry traces for a slow update
pulumi preview --otel-traces file:./trace.json

# Share a failing run's automatic log with a colleague
pulumi logs list
pulumi logs share --help

The pulumi state move example uses the current flag names from the CLI reference; run pulumi state move --help on your version before putting it in a runbook, because state commands are the most likely to change between releases. The same caution applies to the jq path in any script that parses --json preview output.

Quick reference for the platform owner

Related guides: Terraform for the ecosystem Pulumi is most often compared with, Kubernetes and Helm for what your clusters run, and Argo CD for GitOps delivery of what Pulumi provisions.

A final word on judgement

Most of what goes wrong on a Pulumi platform is not a bug in Pulumi. It is a decision made quietly: a stack that was allowed to grow, a key that was left in CI because OIDC was next quarter's work, a rule that was made mandatory before anyone measured its false positives. The tool will do what the program says, including deleting what the program stopped mentioning. Your leverage as the owner is the small set of controls above, applied early and verified often. Keep them boring, keep them automatic, and keep a runbook that a tired engineer can follow.