Agent Skills: Pulumi Knowledge Patch

Pulumi Knowledge Patch

Use this skill when authoring, upgrading, automating, or operating Pulumi projects, providers, packages, policy packs, and backends. Inspect Pulumi.yaml, the stack configuration, language manifests and lockfiles, provider schemas, and the selected backend before applying guidance. Prefer the repository's pinned CLI and SDK versions, tests, and observed behavior where they differ.

Reference Index

| Reference | Topics | | --- | --- | | Automation and integrations | Automation API, Pulumi Cloud API, remote deployments, MCP, CI, Operator, Neo | | CLI and operations | Engine commands, flags, environment controls, direct-resource work, diagnostics, logs | | Components and packages | Cross-language components, YAML components, package sources, registries, publishing | | Languages and runtimes | Node.js, Python, Go, Java, .NET, Bun, YAML, testing and toolchains | | PCL and conversion | PCL types and forms, HCL, code generation, imports, converters, snippets | | Policy, security, and authentication | OIDC, ESC, policy analysis, credentials, secrets, traces | | Provider and protocols | Provider SDKs, schemas, RPCs, handshakes, invokes, plugin hosts | | Resources and engine behavior | Hooks, replacement, inheritance, imports, refresh, diffs, component semantics | | State, imports, and backends | State repair, migration, converters, DIY backends, tags, journaling |

Breaking Changes and Required Migrations

Raise Runtime Baselines

• Node.js projects now require Node.js 22 or later. The test matrix includes Node.js 26, TypeScript 6 is accepted, and generated TypeScript uses nodenext.
• Generated Go programs and SDK modules target Go 1.25; Automation API supports Go 1.26. Generated output-form invokes require Pulumi SDK v3.255.0 or later.
• Python supports Python 3.14, which requires grpcio>=1.75.1.

Remove Retired Surfaces

• Replace scripts that call removed pulumi query or the removed provider StreamInvoke RPC.
• Remove Pulumi.<stack>.deploy.yaml, its CLI subcommands, --config-file, and SDK file readers. Manage deployment settings in Pulumi Cloud instead.
• Replace the discontinued pulumi new --ai workflow with pulumi neo.
• Migrate .NET provider code generation away from pulumi/pkg/v3/codegen/dotnet to the pulumi-dotnet repository package.

Update Provider and Package Contracts

• Rename PulumiPlugin.yaml's pulumiVersionRange to requiredPulumiVersion; the handshake field pulumi_version_range is gone.
• Pass explicit schema loaders during PCL/schema binding and plugin.Context to Go host boot and resolution APIs. Configure and DiffConfig require a resource type.
• Provider schemas reject whitespace or control characters in names, reserved package names pulumi and input, and modules nested under the index module.
• Prefix local package paths with ./ or ../; an unprefixed source is no longer assumed to be a path. Unqualified package names resolve through the Pulumi Cloud Registry.

Account for Backend and Authentication Changes

• Logout deletes all configuration for the backend and clears shared temporary and current tokenless credentials.
• Legacy non-project DIY backend mode now fails instead of warning. The bypass variable is PULUMI_DIY_BACKEND_IGNORE_DEPRECATION_ERROR.
• Current-stack selection is backend-scoped, so switching backends no longer carries a stale stack selection.

Safe Engine Operations

Preview Before Overriding Protection

Use resource targets and protection overrides narrowly:

pulumi preview --exclude '<URN>' --exclude-dependents
pulumi preview --ignore-protect

--ignore-protect permits protected deletion for that operation. A child may explicitly set protect: false or retainOnDelete: false to override inherited true. Use pulumi state protect, taint, and untaint for durable state changes, and use multi-URN pulumi state delete for dependency-safe deletion.

Run the Program When the Operation Needs It

refresh and destroy do not normally incorporate changed program code. Add --run-program when code establishes credentials, secrets, dynamic providers, or hooks needed by the operation. With --refresh, preview and up also accept it; PULUMI_RUN_PROGRAM supplies the global setting.

pulumi refresh --run-program
PULUMI_RUN_PROGRAM=true pulumi up --refresh

Prefer Structured Output for Automation

up, preview, refresh, destroy, and import accept --output json. Historical operations can be reduced to the same summary shape:

pulumi preview --output json
pulumi stack history events --summary

Non-UTF-8 bytes appear as b"<base64>" in machine output. CLI diagnostics are written to stderr, and full output is hidden unless --show-full-output is set.

Components and Packages

A component directory needs PulumiPlugin.yaml only when it is consumed across languages. TypeScript exports component classes directly; YAML uses top-level components; Python, Go, .NET, and Java start a component provider host. Use pulumi package add for Git, local, registry, extension, or direct-server sources, then pulumi install to restore entries from Pulumi.yaml.

pulumi package add ./components/secure-s3
pulumi package add --extension <source>
pulumi install

An invoke parented to a component inherits its provider from the component's providers option. Keep that parent relationship in generated or handwritten code so invokes and resources choose providers consistently.

Resource Lifecycle and Recovery

• replaceWith replaces a resource when any referenced resource is replaced; relationships may be transitive or mutual. replacement_trigger instead replaces when an arbitrary value changes.
• Resource hooks cover lifecycle and retry behavior. Destroy operations with delete hooks must run the program; a successful OnError hook retries the failed operation, while a failed after-hook fails the deployment.
• Output.recover in Node.js and Python can recover failed output resolution. Failed registrations now produce faulted, not unknown, outputs.
• Output-form invokes declare dependencies so the engine delays them until resources and remote-component children are ready; preview returns unknown while those dependencies are unresolved.

Authentication, Secrets, and Observability

Use pulumi login --oidc-token for short-lived Pulumi Cloud credentials. The token may be raw or read from file://; its organization, team, and user can be inferred from claims, or narrowed explicitly. The default lifetime is two hours.

Automatic encrypted CLI logging is enabled by default. Property secrets are redacted, and pulumi logs ls, decrypt, rm, and share manage captures. Treat --show-secrets as an explicit disclosure into terminals and logs.

For tracing, --otel-traces accepts files plus gRPC, secure gRPC, and HTTPS endpoints, headers, and OTEL_RESOURCE_ATTRIBUTES; TRACEPARENT connects CLI spans to a parent trace.

Configuration and Environment Controls

• Any command flag can be expressed as PULUMI_OPTION_*; for example, PULUMI_OPTION_REFRESH=true. PULUMI_STACK selects the stack.
• PULUMI_PARALLEL supplies --parallel; PULUMI_PARALLEL_DIFF enables concurrent diffs, and cgroup CPU limits constrain effective parallelism.
• up, preview, destroy, and refresh accept --override-env and --skip-config-validation for one operation.
• pulumi config set --type selects a scalar type, set-all --json sets bulk JSON configuration, and set --raw preserves newlines from stdin.

Open the matching reference before changing a protocol, state format, provider schema, package source, policy pack, or language runtime; those areas have additional compatibility constraints that do not fit safely in a quick guide.