pulumi-overview

Pulumi

Pulumi is a tool for creating and managing cloud infrastructure: virtual machines, storage, Kubernetes clusters, databases, anything from any provider. You write code or run CLI commands, Pulumi previews what would change, then applies it. This skill walks three levels of working with Pulumi, from a single CLI command up to a project with policies and scheduled drift. Start at the smallest level that fits the task.

The three levels

Level 1 is pulumi do, a CLI for direct CRUD against any provider, with no project files or programming language. Level 2 is a Pulumi project in Python, TypeScript, Go, C#, or Java, used once the work involves multiple related resources, loops or conditionals, reusable abstractions, or environment-specific variants. Level 3 layers Pulumi Cloud onto a project for ESC credentials and configuration, policy, hosted execution, drift detection, schedules, and audit.

Level	Surface	When to use
1	pulumi do	Single resource or multi-vendor bootstrapping
2	Pulumi project (Python, TS, Go, C#, Java)	Multiple resources, abstractions, environments
3	ESC, policy, deployments, drift, schedules	Governance, secrets, scheduled and hosted runs

When the directory has no existing Pulumi project, a user asking to create a single bucket is a Level 1 task; do not scaffold a new project for it. A request to provision a VPC with subnets and a Kubernetes cluster is Level 2 from the start. A request for nightly drift detection on an existing stack is Level 3.

Converting existing infrastructure code from another tool (Terraform, CloudFormation, CDK, ARM, or Bicep) is a separate path: route straight to the migration skills listed in the table at the end, independent of the level model.

Picking the right level requires knowing what is already in the directory. If you can inspect the filesystem, do so. If you cannot (restricted agent contexts), ask the user before any Pulumi command runs whether there is an existing Pulumi project in the directory. Don't run a Pulumi command to find out: commands that would otherwise require a login silently provision a new agent account, parallel to one the user may already own.

---

Level 1: pulumi do for direct resource operations

Use pulumi do for one-shot resource operations against any provider. Examples: create a Cloudflare DNS record, create an S3 bucket for backups, create a GCP storage bucket for image uploads, stand up an Azure virtual machine, configure a Datadog monitor, register a Vercel deployment's domain in Cloudflare DNS. There is no project file, directory layout, or programming language involved.

pulumi do is stateless. Each command runs once and operates directly against the cloud provider: create provisions a resource and prints its cloud-side identifier, while read, patch, and delete act on a resource addressed by that identifier. Nothing is written to a Pulumi state file, so there is no resource graph and no ${...} wiring between commands. To connect two resources, capture an output from one command and pass it as a literal value to the next.

When a Pulumi project (Pulumi.yaml) already exists in the directory, do not use pulumi do to mutate resources the project manages. Changes go through the program instead.

First invocation and signup

The canonical invocation is npx pulumi <command>. It works on any machine with Node.js installed and requires no prior Pulumi setup. If pulumi is on PATH, the npx shim defers to it; otherwise the command runs from the npm registry. To confirm the CLI is available before any command that would trigger signup, run npx pulumi version; it does not touch Pulumi Cloud. The resource verbs (create, read, patch, delete, list) require CLI v3.243.0 or newer, where pulumi do gained resource support. npx pulumi fetches a current release, but a pulumi already on PATH may be older, so confirm the version is recent.

pulumi do writes no Pulumi state, but it resolves provider packages through the Pulumi registry, which can reach Pulumi Cloud. In an agent context without saved credentials, that means a first pulumi do may silently provision an ephemeral agent account and print a claim banner.

The CLI prints one line to stderr noting the new account and a claim URL. Surface that claim URL to the user immediately and again in the final response, since it is the only way the user takes ownership of the account; a session that ends without it leaves resources stranded in the cloud. The access token expires in 3 days and the claim URL stays valid for 30 days; Pulumi Cloud sets both, so surface whatever validity the banner reports.

If the account-creation banner appears more than once in the same session, credentials may not have been cached. Agent credentials are written to /tmp/.pulumi/credentials.json and the claim metadata to /tmp/.pulumi/agent-claim.json, but the claim URL itself is printed in the banner, not stored in those files. Capture it from each banner and surface the most recent one before doing more work.

If authentication fails, ask the user to run pulumi login. Never fall back to pulumi login --local or set PULUMI_CONFIG_PASSPHRASE; both silently change the user's setup.

Provider credentials are separate from Pulumi Cloud credentials. pulumi do reads them from the same environment variables the provider's native CLI uses (AWS_PROFILE, CLOUDFLARE_API_TOKEN, GOOGLE_APPLICATION_CREDENTIALS). If they aren't set, ask the user before invoking commands that call out to the cloud. If a command fails with a provider authorization error, look up that provider's required credentials or configuration and have the user supply them rather than guessing at the cause. ESC (Level 3) is the durable place to keep them once a project exists.

Command shape

Here are two invocations: create an S3 bucket, then read it back by the cloud id the create printed.

npx pulumi do aws:s3:Bucket create --yes --bucket my-data
npx pulumi do aws:s3:Bucket read my-data

The shape is:

pulumi do <pkg:mod:type> create [flags]
pulumi do <pkg:mod:type> read|patch|delete <id> [flags]
pulumi do <pkg:mod:type> list [flags]

• <pkg> is the provider package (aws, azure-native, gcp, cloudflare, kubernetes, etc.).
• <mod> is the module within the package (compute, storage, dns); optional when the module is index. For example, cloudflare:index/record:Record invokes as cloudflare:Record.
• <type> is the resource type (VirtualMachine, Bucket, Record).
• <id> is the cloud provider's identifier for an existing resource, the value create prints as id. create and list take no positional argument; read, patch, and delete each take exactly one <id>.
• [flags] set resource properties, or you pass a body file via --input-file <file>. See Property input below for how flags and files combine, and which values must come from a file.

There is no Pulumi logical name to choose. The CLI derives an internal name from the resource type, and you address existing resources by their cloud id.

Verbs

• create provisions the resource and prints its properties, including the cloud id, as JSON. Capture that id to read, patch, or delete the resource later. Pass --yes in non-interactive contexts; read and list never need it.
• read <id> fetches the resource's current state from the provider and prints it as JSON. It writes nothing.
• patch <id> reads the resource's current inputs, overlays the top-level properties you pass as flags or in --input-file, and updates the resource in place. The overlay is shallow: properties you do not mention are left as they are. patch only updates; it cannot replace a resource, so a change that would require replacement fails rather than recreating it. The command makes you confirm by typing the resource id; pass --yes to skip that prompt in non-interactive contexts.
• delete <id> removes the resource from the cloud. This is irreversible. Get explicit user confirmation for the specific resource before invoking; use --yes only after that confirmation, not as a default for non-interactive runs.

pulumi do also supports two non-CRUD operations. pulumi do <pkg:mod:type> list [flags] enumerates existing instances of a resource type, but only for types that implement listing. Native providers support it broadly. The Terraform-bridged providers (aws, azure, gcp) support it too, but coverage varies by resource type, so a type that lacks it rejects the verb. pulumi do <pkg:mod:function> [flags] invokes a stateless function the provider exposes alongside its resources.

Property input

Properties come from per-property flags, a body file, or both; flags overlay the body. Flags set top-level scalar properties only, so nested or structured values (tags, nested blocks) must come from the body file. The body defaults to PCL, written as flat name = value attributes; pass --input yaml (which needs the YAML converter plugin) to use YAML instead.

cat > bucket.pcl <<'EOF'
bucket = "my-data"
tags = {
  Environment = "dev"
}
EOF
npx pulumi do aws:s3:Bucket create --yes --input-file bucket.pcl

Before authoring properties for a resource new to this session, run npx pulumi package info <pkg> --module <mod> --resource <Type> to list its inputs and outputs with descriptions, scoped to that one resource. Reach for npx pulumi package get-schema <pkg> only when you need the full machine-readable schema with the nested type definitions info does not expand; for a large provider it runs to tens of MB, so do not read it whole. Property names are camelCase (flags are the kebab-case form). To discover names, run npx pulumi package info <pkg> with no module to list its modules and resources, or browse the catalog at https://www.pulumi.com/registry/.

Connecting resources

`pulumi d

---

Content truncated.