Pulumi Blog: Julien Poissonnier

Introducing Bun as a Runtime for Pulumi

Julien Poissonnier — Wed, 08 Apr 2026 00:00:00 +0000

Last year we added support for Bun as a package manager for Pulumi TypeScript projects. Today we’re taking the next step: Bun is now a fully supported runtime for Pulumi programs. Set runtime: bun in your Pulumi.yaml and Bun will execute your entire Pulumi program, with no Node.js required. Since Bun’s 1.0 release, this has been one of our most requested features.

Why Bun?

Bun is a JavaScript runtime designed as an all-in-one toolkit: runtime, package manager, bundler, and test runner. For Pulumi users, the most relevant advantages are:

Native TypeScript support: Bun runs TypeScript directly without requiring ts-node or a separate compile step.
Fast package management: Bun’s built-in package manager can install dependencies significantly faster than npm.
Node.js compatibility: Bun aims for 100% Node.js compatibility, so the npm packages you already use with Pulumi should work out of the box.

With runtime: bun, Pulumi uses Bun for both running your program and managing your packages, giving you a streamlined single-tool experience.

Getting started

To create a new Pulumi project with the Bun runtime, run:

pulumi new bun

This creates a TypeScript project configured to use Bun. The generated Pulumi.yaml looks like this:

name: my-bun-project
runtime: bun

From here, write your Pulumi program as usual. For example, to create a random password using the @pulumi/random package:

bun add @pulumi/random

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

const password = new random.RandomPassword("password", {
 length: 20,
});

export const pw = password.result;

Then deploy with:

pulumi up

Prerequisites:

Bun 1.3 or later
Pulumi 3.227.0 or later

Converting existing Node.js projects

If you have an existing Pulumi TypeScript project running on Node.js, you can convert it to use the Bun runtime in a few steps.

1. Update `Pulumi.yaml`

Change the runtime field from nodejs to bun:

Before:

runtime:
 name: nodejs
 options:
 packagemanager: npm

After:

runtime: bun

When the runtime is set to bun, Bun is also used as the package manager — there’s no need to configure a separate packagemanager option.

2. Update `tsconfig.json`

Bun handles TypeScript differently from Node.js with ts-node. Update your tsconfig.json to use Bun’s recommended compiler options:

{
 "compilerOptions": {
 "lib": ["ESNext"],
 "target": "ESNext",
 "module": "Preserve",
 "moduleDetection": "force",
 "moduleResolution": "bundler",
 "allowJs": true,
 "allowImportingTsExtensions": true,
 "verbatimModuleSyntax": true,
 "strict": true,
 "skipLibCheck": true,
 "noFallthroughCasesInSwitch": true,
 "noUncheckedIndexedAccess": true,
 "noImplicitOverride": true
 }
}

Key differences from a typical Node.js tsconfig.json:

module: "Preserve" and moduleResolution: "bundler": Let Bun handle module resolution instead of compiling to CommonJS. The bundler resolution strategy allows extensionless imports while still respecting package.json exports, matching how Bun resolves modules in practice.
verbatimModuleSyntax: true: Enforces consistent use of ESM import/export syntax. TypeScript will flag any remaining CommonJS patterns like require() at compile time.

3. Switch to ESM

Bun makes it easy to go full ESM and it’s the recommended module format for Bun projects. Add "type": "module" to your package.json:

{
 "type": "module"
}

With ECMAScript module (ESM) syntax, one thing that gets easier is working with async code. In a CommonJS Pulumi program, if you need to await a data source or other async call before declaring resources, the program must be wrapped in an async entrypoint function. With ESM and Bun, top-level await just works, so you can skip the wrapper function entirely and await directly at the module level:

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

const azs = await aws.getAvailabilityZones({ state: "available" });

const buckets = azs.names.map(az => new aws.s3.BucketV2(`my-bucket-${az}`));

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

If your existing program does use an async entrypoint with export =, just replace it with the ESM-standard export default:

// CommonJS (Node.js default)
export = async () => {
 const bucket = new aws.s3.BucketV2("my-bucket");
 return { bucketName: bucket.id };
};

// ESM (used with Bun)
export default async () => {
 const bucket = new aws.s3.BucketV2("my-bucket");
 return { bucketName: bucket.id };
};

4. Update the Pulumi SDK

Make sure you’re running @pulumi/pulumi version 3.226.0 or later:

bun add @pulumi/pulumi@latest

5. Install dependencies and deploy

pulumi install
pulumi up

Bun as runtime vs. Bun as package manager

With this release, there are now two ways to use Bun with Pulumi:

Configuration	Bun’s role	Node.js required?
`runtime: bun`	Runs your program and manages packages	No
`runtime: { name: nodejs, options: { packagemanager: bun } }`	Manages packages only	Yes

Use runtime: bun for the full Bun experience. The package-manager-only mode is still available for projects that need Node.js-specific features like function serialization.

Known limitations

The following Pulumi features are not currently supported when using the Bun runtime:

Callback functions (magic lambdas) are not supported. APIs like aws.lambda.CallbackFunction and event handler shortcuts (e.g., bucket.onObjectCreated) use function serialization which requires Node.js v8 and inspector modules that are only partially supported in Bun.
Dynamic providers are not supported. Dynamic providers (pulumi.dynamic.Resource) similarly rely on function serialization.

If your project uses any of these features, continue using runtime: nodejs. You can still benefit from Bun’s fast package management by setting packagemanager: bun in your runtime options.

Start using Bun with Pulumi

Bun runtime support is available now in Pulumi 3.227.0. To get started:

Create a new project: pulumi new bun
Read the docs: TypeScript (Node.js) SDK
Report issues or share feedback on GitHub or in the Pulumi Community Slack

Thank you to everyone who upvoted, commented on, and contributed to the original feature request. Your feedback helped shape this feature, and we’d love to hear how it works for you.

Resource hooks

Will Jones — Mon, 30 Jun 2025 00:00:00 +0000

Pulumi programs are declarative, allowing you to specify the desired state of your infrastructure while Pulumi figures out the rest. But what about the times where you want to be more involved in what Pulumi is doing? Resource hooks are one of our most requested features, and from Pulumi 3.182.0 we’re excited to announce that you’ll be able to use them to run arbitrary code at any point in Pulumi’s resource lifecycle!

When you run pulumi up, Pulumi runs your program and works out the set of create, update and delete operations required to realise the state it describes. Hooks allow you to attach custom callbacks to these operations, enabling you to execute custom behaviour before or after they occur. You might want to set up an SSH tunnel to a bastion host before Pulumi attempts to create or update a virtual machine or database; or you may wish to send metrics to your data warehouse whenever Pulumi updates certain resources or properties. Hooks allow you to do all this and more – as with everything else in Pulumi, you are free to make use of the full power of your favourite programming language.

Hooks in action

Let’s check out the use case of opening a tunnel to a remote host before running a command. For this we’ll use a contrived example where we use the socat command to open a local TCP port that forwards to a remote host. Here we’ll open localhost:1234 and forward it to example.com:80. We’ll then use Pulumi’s command provider to invoke curl to make a request to that local port, which will be forwarded to the remote host. To start with, let’s write the program without hooks:

import * as command from "@pulumi/command"

export = async () => {
 const curl = "curl -H'Host: example.com' localhost:1234"

 const cmd = new command.local.Command("curl", {
 create: curl,
 update: curl,
 delete: curl,
 triggers: [new Date().toString()],
 })

 return {
 stdout: cmd.stdout,
 }
}

import * as command from "@pulumi/command"

export = async () => {
 const curl = "curl -H'Host: example.com' localhost:1234"

 const cmd = new command.local.Command("curl", {
 create: curl,
 update: curl,
 delete: curl,
 triggers: [new Date().toString()],
 })

 return {
 stdout: cmd.stdout,
 }
}

import datetime
import pulumi
import pulumi_command

curl = "curl -H'Host: example.com' localhost:1234"

cmd = pulumi_command.local.Command("curl",
 create=curl,
 update=curl,
 delete=curl,
 triggers=[str(datetime.datetime.now())],
)

pulumi.export("stdout", cmd.stdout)

package main

import (
 "time"

 "github.com/pulumi/pulumi-command/sdk/go/command/local"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 curl := "curl -H'Host: example.com' localhost:1234"

 cmd, err := local.NewCommand(ctx, "curl", &local.CommandArgs{
 Create: pulumi.String(curl),
 Update: pulumi.String(curl),
 Delete: pulumi.String(curl),
 Triggers: pulumi.StringArray{pulumi.String(time.Now().String())},
 })
 if err != nil {
 return err
 }

 ctx.Export("stdout", cmd.Stdout)

 return nil
 })
}

using System.Threading.Tasks;

using Pulumi;
using Pulumi.Command.Local;

class Program
{
 static Task<int> Main() => Deployment.RunAsync<MyStack>();
}

class MyStack : Stack
{
 public MyStack()
 {
 var curl = "curl -H'Host: example.com' localhost:1234";

 var cmd = new Command("curl", new CommandArgs
 {
 Create = curl,
 Update = curl,
 Delete = curl,
 Triggers = { System.DateTime.Now.ToString() },
 });

 return new Dictionary<string, object?>
 {
 ["stdout"] = cmd.Stdout,
 };
 }
}

We set up a local Command that will run the same curl command whether it is being created, updated, or deleted. For the purposes of illustration, we also set the triggers property to the current date and time, so that the command will always be run when we run pulumi up. Let’s now do just that:

pulumi up

Assuming we have nothing running on port 1234, we’ll get an error such as the following:

Updating (...)
View in Browser (Ctrl+O): https://app.pulumi.com/...
Type Name Status Info
pulumi:pulumi:Stack resource-hooks **failed** 1 error; 9 messages
++ └─ command:local:Command curl **creating failed** [diff: ]; 1 error
Diagnostics:
command:local:Command (curl):
error: exit status 7: running "curl -H'Host: example.com' localhost:1234":
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0
curl: (7) Failed to connect to localhost port 1234 after 0 ms: Could not connect to server

As expected, nothing is listening on port 1234, so curl fails with an error. Previously, we might have fixed this by using a wrapper around our Pulumi program, such as the Automation API. With resource hooks, however, the solution is at our fingertips! We’ll hook into the Command resource’s lifecycle to open a tunnel before any operation is run, and to close it afterwards:

import * as child_process from "child_process"
import * as command from "@pulumi/command"
import * as pulumi from "@pulumi/pulumi"

export = async () => {
 let tunnel

 const beforeHook = new pulumi.ResourceHook("before", async args => {
 console.log("Opening tunnel")

 tunnel = child_process.spawn(
 "socat",
 [
 "TCP-LISTEN:1234,fork",
 "TCP:example.com:80",
 ],
 { detached: true }
 )

 console.log(`Tunnel opened: ${tunnel?.pid}`)
 })

 const afterHook = new pulumi.ResourceHook("after", async args => {
 console.log(`Closing tunnel: ${tunnel?.pid}`)
 tunnel?.kill("SIGKILL")
 })

 const curl = "curl -H'Host: example.com' localhost:1234"

 const cmd = new command.local.Command("curl", {
 create: curl,
 update: curl,
 delete: curl,
 triggers: [new Date().toString()],
 }, {
 hooks: {
 beforeCreate: [beforeHook],
 afterCreate: [afterHook],
 beforeUpdate: [beforeHook],
 afterUpdate: [afterHook],
 beforeDelete: [beforeHook],
 afterDelete: [afterHook],
 },
 })

 return {
 stdout: cmd.stdout,
 }
}

import * as child_process from "child_process"
import * as command from "@pulumi/command"
import * as pulumi from "@pulumi/pulumi"

export = async () => {
 let tunnel: child_process.ChildProcessWithoutNullStreams | undefined

 const beforeHook = new pulumi.ResourceHook("before", async args => {
 console.log("Opening tunnel")

 tunnel = child_process.spawn(
 "socat",
 [
 "TCP-LISTEN:1234,fork",
 "TCP:example.com:80",
 ],
 { detached: true }
 )

 console.log(`Tunnel opened: ${tunnel?.pid}`)
 })

 const afterHook = new pulumi.ResourceHook("after", async args => {
 console.log(`Closing tunnel: ${tunnel?.pid}`)
 tunnel?.kill("SIGKILL")
 })

 const curl = "curl -H'Host: example.com' localhost:1234"

 const cmd = new command.local.Command("curl", {
 create: curl,
 update: curl,
 delete: curl,
 triggers: [new Date().toString()],
 }, {
 hooks: {
 beforeCreate: [beforeHook],
 afterCreate: [afterHook],
 beforeUpdate: [beforeHook],
 afterUpdate: [afterHook],
 beforeDelete: [beforeHook],
 afterDelete: [afterHook],
 },
 })

 return {
 stdout: cmd.stdout,
 }
}

import datetime
import subprocess
import pulumi
import pulumi_command

tunnel = None

def before(args: pulumi.ResourceHookArgs):
 global tunnel
 pulumi.log.info("Opening tunnel")
 tunnel = subprocess.Popen(
 ["socat", "TCP-LISTEN:1234,fork", "TCP:example.com:80"],
 )
 pulumi.log.info(f"Tunnel opened: {tunnel.pid}")


before_hook = pulumi.ResourceHook("before", before)

def after(args: pulumi.ResourceHookArgs):
 global tunnel
 if tunnel:
 pulumi.log.info(f"Closing tunnel: {tunnel.pid}")
 tunnel.terminate()
 tunnel.wait()
 tunnel = None

after_hook = pulumi.ResourceHook("after", after)

curl = "curl -H'Host: example.com' localhost:1234"

cmd = pulumi_command.local.Command(
 "curl",
 create=curl,
 update=curl,
 delete=curl,
 triggers=[str(datetime.datetime.now())],
 opts=pulumi.ResourceOptions(
 hooks=pulumi.ResourceHookBinding(
 before_create=[before_hook],
 after_create=[after_hook],
 before_update=[before_hook],
 after_update=[after_hook],
 before_delete=[before_hook],
 after_delete=[after_hook],
 )
 ),
)

pulumi.export("stdout", cmd.stdout)

package main

import (
 "fmt"
 "os/exec"
 "time"

 "github.com/pulumi/pulumi-command/sdk/go/command/local"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

var tunnel *exec.Cmd

func before(args *pulumi.ResourceHookArgs) error {
 fmt.Println("Opening tunnel")
 tunnel = exec.Command("socat", "TCP-LISTEN:1234,fork", "TCP:example.com:80")
 err := tunnel.Start()
 if err != nil {
 return fmt.Errorf("failed to start tunnel: %w", err)
 }
 fmt.Printf("Tunnel opened: %d\n", tunnel.Process.Pid)
 return nil
}

func after(args *pulumi.ResourceHookArgs) error {
 if tunnel != nil && tunnel.Process != nil {
 fmt.Printf("Closing tunnel: %d", tunnel.Process.Pid)
 if err := tunnel.Process.Kill(); err != nil {
 return err
 }
 tunnel.Wait()
 tunnel = nil
 }
 return nil
}

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 beforeHook, err := ctx.RegisterResourceHook("before", before, nil)
 if err != nil {
 return err
 }
 afterHook, err := ctx.RegisterResourceHook("after", after, nil)
 if err != nil {
 return err
 }

 curlCmd := "curl -H'Host: example.com' localhost:1234"

 cmd, err := local.NewCommand(ctx, "curl", &local.CommandArgs{
 Create: pulumi.String(curlCmd),
 Update: pulumi.String(curlCmd),
 Delete: pulumi.String(curlCmd),
 Triggers: pulumi.Array{pulumi.String(fmt.Sprintf("%d", time.Now().Unix()))},
 }, pulumi.ResourceHooks(&pulumi.ResourceHookBinding{
 BeforeCreate: []*pulumi.ResourceHook{beforeHook},
 AfterCreate: []*pulumi.ResourceHook{afterHook},
 BeforeUpdate: []*pulumi.ResourceHook{beforeHook},
 AfterUpdate: []*pulumi.ResourceHook{afterHook},
 BeforeDelete: []*pulumi.ResourceHook{beforeHook},
 AfterDelete: []*pulumi.ResourceHook{afterHook},
 }),
 )
 if err != nil {
 return err
 }

 ctx.Export("stdout", cmd.Stdout)

 return nil
 })
}

using System.Diagnostics;
using System.Threading.Tasks;

using Pulumi;
using Pulumi.Command.Local;

class Program
{
 static Task<int> Main() => Deployment.RunAsync<MyStack>();
}

class MyStack : Stack
{
 public MyStack()
 {
 Process? tunnel = null;

 var beforeHook = new ResourceHook("before", async (args, cancellationToken) =>
 {
 System.Console.WriteLine("Opening tunnel");

 tunnel = Process.Start(new ProcessStartInfo
 {
 FileName = "socat",
 Arguments = "TCP-LISTEN:1234,fork TCP:example.com:80",
 UseShellExecute = false,
 CreateNoWindow = true,
 });

 System.Console.WriteLine($"Tunnel opened: {tunnel?.Id}");
 });

 var afterHook = new ResourceHook("after", async (args, cancellationToken) =>
 {
 System.Console.WriteLine($"Closing tunnel: {tunnel?.Id}");
 tunnel?.Kill();
 });

 var curl = "curl -H'Host: example.com' localhost:1234";

 var cmd = new Command("curl", new CommandArgs
 {
 Create = curl,
 Update = curl,
 Delete = curl,
 Triggers = { System.DateTime.Now.ToString() },
 }, new CustomResourceOptions
 {
 Hooks =
 {
 BeforeCreate = { beforeHook },
 AfterCreate = { afterHook },
 BeforeUpdate = { beforeHook },
 AfterUpdate = { afterHook },
 BeforeDelete = { beforeHook },
 AfterDelete = { afterHook },
 }
 });

 return new Dictionary<string, object?>
 {
 ["stdout"] = cmd.Stdout,
 };
 }
}

When we run pulumi up now, the hooks will be invoked before and after the relevant operation. Since our previous operation failed, we should expect to see a hooked create on our first run:

pulumi up

Updating (...)
View in Browser (Ctrl+O): https://app.pulumi.com/...
Type Name Status Info
+ pulumi:pulumi:Stack resource-hooks created (3s) 3 messages
+ └─ command:local:Command curl created (0.66s)
Diagnostics:
pulumi:pulumi:Stack (resource-hooks):
Opening tunnel
Tunnel opened: 2131167
Closing tunnel: 2131167
Outputs:
stdout: "<!doctype html>\n<html>\n<head>\n <title>Example Domain</title>\n\n <meta charset=\"utf-8\" />\n <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n <style type=\"text/css\">\n body {\n background-color: #f0f0f2;\n margin: 0;\n padding: 0;\n font-family: -apple-system, system-ui, BlinkMacSystemFont, \"Segoe UI\", \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;\n \n }\n div {\n width: 600px;\n margin: 5em auto;\n padding: 2em;\n background-color: #fdfdff;\n border-radius: 0.5em;\n box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n }\n a:link, a:visited {\n color: #38488f;\n text-decoration: none;\n }\n @media (max-width: 700px) {\n div {\n margin: 0 auto;\n width: auto;\n }\n }\n </style> \n</head>\n\n<body>\n<div>\n <h1>Example Domain</h1>\n <p>This domain is for use in illustrative examples in documents. You may use this\n domain in literature without prior coordination or asking for permission.</p>\n <p><a href=\"https://www.iana.org/domains/example\">More information...</a></p>\n</div>\n</body>\n</html>"
Resources:
+ 2 created
Duration: 5s

Success! The tunnel was opened before our create operation and our stack output contains the HTML of the page at example.com.

Another example: application health checks

Let’s tackle a more realistic scenario where hooks can be useful. We’ll take the how-to guide for creating an EC2 web server and add resource hooks to health check the web server before allowing Pulumi to mark the deployment as complete. In this way, we know that when Pulumi is finished, the application is up and ready to go!

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

export = async () => {
 // Define the instance's user data script to set up a simple HTTP server that
 // serves some static content. We'll try to fetch the health.json in a
 // lifecycle hook later on to check whether or not the server is up and running.
 const userData = `#!/bin/bash
echo "Hello, World!" > index.html
echo '{"ok": true}' > health.json
nohup python -m SimpleHTTPServer 80 &`

 // Define a resource hook that will run after create and update and not return
 // until the health check passes.
 const afterHook = new pulumi.ResourceHook("after", async args => {
 // Since this is an after hook, we'll have access to the new outputs of the
 // resource.
 const outputs = args.newOutputs

 // Attempt to fetch health.json from the instance's public endpoint, backing
 // off linearly if it is not yet available.
 const maxRetries = 30
 for (let i = 0; i < maxRetries; i++) {
 try {
 const response = await fetch(`http://${outputs.publicDns}/health.json`)
 if (response.ok) {
 const data = await response.json()
 console.log(`Health check passed: ${JSON.stringify(data)}`)
 return
 }
 } catch (error) {
 console.log(`Health check attempt ${i + 1} failed`)
 }

 await new Promise(resolve => setTimeout(resolve, (i + 1) * 1000))
 }
 })

 // Set up the resources needed to run the web server, as outlined in the
 // how-to guide linked above.

 const instanceType = "t2.micro"
 const ami = aws.ec2.getAmiOutput({
 filters: [{
 name: "name",
 values: ["amzn2-ami-hvm-*"],
 }],
 // Amazon owns this AMI so we'll use their owner ID.
 owners: ["137112412989"],
 mostRecent: true,
 })

 const group = new aws.ec2.SecurityGroup("webserver-secgrp", {
 ingress: [
 { protocol: "tcp", fromPort: 22, toPort: 22, cidrBlocks: ["0.0.0.0/0"] },
 { protocol: "tcp", fromPort: 80, toPort: 80, cidrBlocks: ["0.0.0.0/0"] },
 ],
 })

 const server = new aws.ec2.Instance("webserver-www", {
 instanceType,
 vpcSecurityGroupIds: [group.id],
 ami: ami.id,
 userData,
 }, {
 hooks: {
 afterCreate: [afterHook],
 afterUpdate: [afterHook],
 },
 })

 return {
 publicDns: server.publicDns,
 publicIp: server.publicIp,
 }
}

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

export = async () => {
 // Define the instance's user data script to set up a simple HTTP server that
 // serves some static content. We'll try to fetch the health.json in a
 // lifecycle hook later on to check whether or not the server is up and running.
 const userData = `#!/bin/bash
echo "Hello, World!" > index.html
echo '{"ok": true}' > health.json
nohup python -m SimpleHTTPServer 80 &`

 // Define a resource hook that will run after create and update and not return
 // until the health check passes.
 const afterHook = new pulumi.ResourceHook("after", async args => {
 // Since this is an after hook, we'll have access to the new outputs of the
 // resource.
 const outputs = args.newOutputs as aws.ec2.InstanceState

 // Attempt to fetch health.json from the instance's public endpoint, backing
 // off linearly if it is not yet available.
 const maxRetries = 30
 for (let i = 0; i < maxRetries; i++) {
 try {
 const response = await fetch(`http://${outputs.publicDns}/health.json`)
 if (response.ok) {
 const data = await response.json()
 console.log(`Health check passed: ${JSON.stringify(data)}`)
 return
 }
 } catch (error) {
 console.log(`Health check attempt ${i + 1} failed`)
 }

 await new Promise(resolve => setTimeout(resolve, (i + 1) * 1000))
 }
 })

 // Set up the resources needed to run the web server, as outlined in the
 // how-to guide linked above.

 const instanceType = "t2.micro"
 const ami = aws.ec2.getAmiOutput({
 filters: [{
 name: "name",
 values: ["amzn2-ami-hvm-*"],
 }],
 // Amazon owns this AMI so we'll use their owner ID.
 owners: ["137112412989"],
 mostRecent: true,
 })

 const group = new aws.ec2.SecurityGroup("webserver-secgrp", {
 ingress: [
 { protocol: "tcp", fromPort: 22, toPort: 22, cidrBlocks: ["0.0.0.0/0"] },
 { protocol: "tcp", fromPort: 80, toPort: 80, cidrBlocks: ["0.0.0.0/0"] },
 ],
 })

 const server = new aws.ec2.Instance("webserver-www", {
 instanceType,
 vpcSecurityGroupIds: [group.id],
 ami: ami.id,
 userData,
 }, {
 hooks: {
 afterCreate: [afterHook],
 afterUpdate: [afterHook],
 },
 })

 return {
 publicDns: server.publicDns,
 publicIp: server.publicIp,
 }
}

import json
import time

import pulumi
import requests
from pulumi_aws import ec2

# Define the instance's user data script to set up a simple HTTP server that
# serves some static content. We'll try to fetch the health.json in a
# lifecycle hook later on to check whether or not the server is up and running.
user_data = """#!/bin/bash
echo "Hello, World!" > index.html
echo '{"ok": true}' > health.json
nohup python -m SimpleHTTPServer 80 &"""


# Define a resource hook that will run after create and update and not return
# until the health check passes.
def health_check(args: pulumi.ResourceHookArgs):
 # Since this is an after hook, we'll have access to the new outputs of the
 # resource.
 outputs = args.new_outputs

 # Attempt to fetch health.json from the instance's public endpoint, backing
 # off linearly if it is not yet available.
 max_retries = 30
 for i in range(max_retries):
 try:
 response = requests.get(
 f"http://{outputs['publicDns']}/health.json", timeout=10
 )
 if response.status_code == 200:
 data = response.json()
 print(f"Health check passed: {json.dumps(data)}")
 return
 except Exception as error:
 print(f"Health check attempt {i + 1} failed: {error}")

 # Linear backoff - wait (i + 1) seconds before next attempt
 time.sleep(i + 1)


instance_type = "t2.micro"

ami = ec2.get_ami_output(
 filters=[
 {
 "name": "name",
 "values": ["amzn2-ami-hvm-*"],
 }
 ],
 # Amazon owns this AMI so we'll use their owner ID.
 owners=["137112412989"],
 most_recent=True,
)

group = ec2.SecurityGroup(
 "webserver-secgrp",
 ingress=[
 {
 "protocol": "tcp",
 "from_port": 22,
 "to_port": 22,
 "cidr_blocks": ["0.0.0.0/0"],
 },
 {
 "protocol": "tcp",
 "from_port": 80,
 "to_port": 80,
 "cidr_blocks": ["0.0.0.0/0"],
 },
 ],
)

server = ec2.Instance(
 "webserver-www",
 instance_type=instance_type,
 vpc_security_group_ids=[group.id],
 ami=ami.id,
 user_data=user_data,
 opts=pulumi.ResourceOptions(
 hooks=pulumi.ResourceHookBinding(
 after_create=[health_check],
 after_update=[health_check],
 ),
 ),
)

package main

import (
 "encoding/json"
 "fmt"
 "net/http"
 "time"

 "github.com/pulumi/pulumi-aws/sdk/v6/go/aws/ec2"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

// Define a resource hook that will run after create and update and not return
// until the health check passes.
func healthCheck(args *pulumi.ResourceHookArgs) error {
 // Since this is an after hook, we'll have access to the new outputs of the
 // resource.
 publicDns := args.NewOutputs["publicDns"].StringValue()

 // Attempt to fetch health.json from the instance's public endpoint, backing
 // off linearly if it is not yet available.
 maxRetries := 30
 for i := 0; i < maxRetries; i++ {
 url := fmt.Sprintf("http://%s/health.json", publicDns)

 client := &http.Client{
 Timeout: 10 * time.Second,
 }

 resp, err := client.Get(url)
 if err == nil && resp.StatusCode == 200 {
 var data map[string]interface{}
 if err := json.NewDecoder(resp.Body).Decode(&data); err == nil {
 resp.Body.Close()
 dataJSON, _ := json.Marshal(data)
 fmt.Printf("Health check passed: %s\n", string(dataJSON))
 return nil
 }
 resp.Body.Close()
 }

 if resp != nil {
 resp.Body.Close()
 }

 fmt.Printf("Health check attempt %d failed: %v\n", i+1, err)

 // Linear backoff - wait (i + 1) seconds before next attempt
 time.Sleep(time.Duration(i+1) * time.Second)
 }

 return fmt.Errorf("health check failed after %d attempts", maxRetries)
}

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // Define the instance's user data script to set up a simple HTTP server
 // that serves some static content. We'll try to fetch the health.json
 // in a lifecycle hook later on to check whether or not the server is up
 // and running.
 userData := `#!/bin/bash
echo "Hello, World!" > index.html
echo '{"ok": true}' > health.json
nohup python -m SimpleHTTPServer 80 &`

 instanceType := "t2.micro"

 ami, err := ec2.LookupAmi(ctx, &ec2.LookupAmiArgs{
 Filters: []ec2.GetAmiFilter{
 {
 Name: "name",
 Values: []string{"amzn2-ami-hvm-*"},
 },
 },
 // Amazon owns this AMI so we'll use their owner ID.
 Owners: []string{"137112412989"},
 MostRecent: pulumi.BoolRef(true),
 })
 if err != nil {
 return err
 }

 group, err := ec2.NewSecurityGroup(ctx, "webserver-secgrp", &ec2.SecurityGroupArgs{
 Ingress: ec2.SecurityGroupIngressArray{
 &ec2.SecurityGroupIngressArgs{
 Protocol: pulumi.String("tcp"),
 FromPort: pulumi.Int(22),
 ToPort: pulumi.Int(22),
 CidrBlocks: pulumi.StringArray{pulumi.String("0.0.0.0/0")},
 },
 &ec2.SecurityGroupIngressArgs{
 Protocol: pulumi.String("tcp"),
 FromPort: pulumi.Int(80),
 ToPort: pulumi.Int(80),
 CidrBlocks: pulumi.StringArray{pulumi.String("0.0.0.0/0")},
 },
 },
 })
 if err != nil {
 return err
 }

 hook, err := ctx.RegisterResourceHook("health-check", healthCheck, nil)
 if err != nil {
 return err
 }

 server, err := ec2.NewInstance(ctx, "webserver-www", &ec2.InstanceArgs{
 InstanceType: pulumi.String(instanceType),
 VpcSecurityGroupIds: pulumi.StringArray{group.ID()},
 Ami: pulumi.String(ami.Id),
 UserData: pulumi.String(userData),
 }, pulumi.ResourceHooks(&pulumi.ResourceHookBinding{
 AfterCreate: []*pulumi.ResourceHook{hook},
 AfterUpdate: []*pulumi.ResourceHook{hook},
 }))
 if err != nil {
 return err
 }

 ctx.Export("publicDns", server.PublicDns)
 ctx.Export("publicIp", server.PublicIp)

 return nil
 })
}

using System;

using System.Threading.Tasks;
using Pulumi;

using Pulumi.Aws.Ec2;
using Pulumi.Aws.Ec2.Inputs;
using Pulumi.Command.Local;
using System.Diagnostics;
using System.Collections.Generic;

class Program
{
 static Task<int> Main() => Deployment.RunAsync<MyStack>();
}

class MyStack : Stack
{
 public MyStack()
 {
 // Define the instance's user data script to set up a simple HTTP server that
 // serves some static content. We'll try to fetch the health.json in a
 // lifecycle hook later on to check whether or not the server is up and running.
 var userData = @"#!/bin/bash
echo ""Hello, World!"" > index.html
echo '{""ok"": true}' > health.json
nohup python -m SimpleHTTPServer 80 &";

 // Define a resource hook that will run after create and update and not return
 // until the health check passes.
 var afterHook = new ResourceHook("after", async (args, cancellationToken) =>
 {
 // Since this is an after hook, we'll have access to the new outputs of the
 // resource.
 var outputs = args.NewOutputs

 // Attempt to fetch health.json from the instance's public endpoint, backing
 // off linearly if it is not yet available.
 const int maxRetries = 30;
 for (var i = 0; i < maxRetries; i++)
 {
 try
 {
 using var client = new HttpClient();
 var response = await client.GetAsync($"http://{outputs?["publicDns"]}/health.json");
 if (response.IsSuccessStatusCode)
 {
 var data = await response.Content.ReadAsStringAsync();
 Console.WriteLine($"Health check passed: {data}");
 return;
 }
 }
 catch (Exception)
 {
 Console.WriteLine($"Health check attempt {i + 1} failed");
 }

 await Task.Delay((i + 1) * 1000);
 }
 });

 // Set up the resources needed to run the web server, as outlined in the
 // how-to guide linked above.

 var instanceType = "t2.micro";
 var ami = GetAmi.Invoke(new GetAmiArgs
 {
 Filters =
 {
 new GetAmiFilterArgs
 {
 Name = "name",
 Values = { "amzn2-ami-hvm-*" },
 },
 },
 Owners = { "137112412989" }, // Amazon owns this AMI so we'll use their owner ID.
 MostRecent = true,
 });

 var group = new SecurityGroup("webserver-secgrp", new SecurityGroupArgs
 {
 Ingress =
 {
 new SecurityGroupIngressArgs
 {
 Protocol = "tcp",
 FromPort = 22,
 ToPort = 22,
 CidrBlocks = { "0.0.0.0/0" },
 },
 new SecurityGroupIngressArgs
 {
 Protocol = "tcp",
 FromPort = 80,
 ToPort = 80,
 CidrBlocks = { "0.0.0.0/0" },
 },
 },
 });

 var server = new Instance("webserver-www", new InstanceArgs
 {
 InstanceType = instanceType,
 VpcSecurityGroupIds = { group.Id },
 Ami = ami.Apply(a => a.Id),
 UserData = userData,
 }, new CustomResourceOptions
 {
 Hooks =
 {
 AfterCreate = { afterHook },
 AfterUpdate = { afterHook },
 }
 });

 // Export the public DNS and IP of the server.
 this.PublicDns = server.PublicDns;
 this.PublicIp = server.PublicIp;
 }

 [Output]
 public Output<string> PublicDns { get; private set; }

 [Output]
 public Output<string> PublicIp { get; private set; }
}

Thanks to our hooks, pulumi up will now wait until the web server is up and running before marking the deployment as complete. We can see this in action thanks to our logging output:

pulumi up

Updating (...)

View in Browser (Ctrl+O): https://app.pulumi.com/...

 Type Name Status Info
 + pulumi:pulumi:Stack resource-hooks created (79s) 6 messages
 + ├─ aws:ec2:SecurityGroup webserver-secgrp created (3s)
 + └─ aws:ec2:Instance webserver-www created (67s)

Diagnostics:
 pulumi:pulumi:Stack (resource-hooks):
 Health check attempt 1 failed
 Health check attempt 2 failed
 Health check attempt 3 failed
 Health check attempt 4 failed
 Health check attempt 5 failed
 Health check passed: {"ok":true}

Outputs:
 publicHostName: "ec2-XXX-YYY-ZZZ-WWW.us-west-2.compute.amazonaws.com"
 publicIp : "XXX.YYY.ZZZ.WWW"

Resources:
 + 3 created

Duration: 1m21s

And indeed, a command such as curl http://ec2-XXX-YYY-ZZZ-WWW.us-west-2.compute.amazonaws.com/health.json returns {"ok":true} immediately, without us having to wait for the web server to start up after the pulumi up command completes!

Where can we go from here?

Resource hooks are a powerful new feature that allow you to run custom code at any point in the resource lifecycle. This opens up a wide range of possibilities, such as:

Custom application health checks after creating or updating resources
Collecting logs or metrics when your Pulumi resources change
Running custom scripts such as database migrations as part of your Pulumi workflow.

Resource hooks require Pulumi to run your program. For refresh and destroy operations, this means you must use the --run-program flag for hooks to work. Read the full documentation on resource hooks to learn more.

Share any issues with your experience with us on GitHub, X, or our Community Slack.

Pulumi + uv: Fast Python Package and Project Management

Adam Gordon Bell — Wed, 27 Nov 2024 12:43:45 +0100

Continuing our work to bring the best of modern Python to Infrastructure as Code, we are excited to announce built-in support for uv in Pulumi. uv is an extremely fast Python package manager that can install dependencies up to 100x faster than traditional tools, providing one of the fastest ways to manage your Python dependencies and virtual environments.

Why uv?

Listen in on this discussion between Adam Gordon Bell and Julien Poissonnier as they discuss Pulumi + uv and why uv is so fast!

uv brings several key advantages to your Python development workflow:

Blazing Fast Performance: Written in Rust, uv can install packages 10-100x faster than pip
Reliable Dependency Resolution: Advanced resolution algorithm ensures consistent environments
Drop-in Replacement: Works seamlessly with existing requirements.txt and pyproject.toml files
Built-in Virtual Environment Management: Simplified environment handling out of the box

Using uv in Pulumi

To use uv to manage your Python virtual environment and dependencies, set the toolchain option to uv in your Pulumi.yaml file:

name: uv-goes-brrrr
runtime:
 name: python
 options:
 toolchain: uv
 virtualenv: .venv

If you have uv installed, you can run pulumi new python and select uv as the toolchain to use for installing dependencies and running the program.

You can find more information on how to use uv in Pulumi in our Python documentation.

Improving Pulumi’s Docker Images

Julien Poissonnier — Fri, 27 Sep 2024 00:00:00 +0000

The Pulumi Docker Containers provide a convenient way for running Pulumi in CI/CD pipelines, or for running Pulumi in environments where you don’t want to install the Pulumi CLI directly. These images also power Pulumi Deployments. We provide several flavors of images, including the pulumi/pulumi image that includes all supported language runtimes in a single image, as well as slim images for each language runtime, for example pulumi/pulumi-python or pulumi/pulumi-nodejs.

To provide more flexibility for choosing the version of the programming language to use, we have added versioned images for the language specific images covering all of our supported languages. We now also support setting the version of the Node.js and Python runtimes used in Pulumi Deployments by using .node-version and .python-version files.

.NET 6.0 has since reached end of life. The .NET 6.0 images referenced in this post are no longer available. See the current supported .NET versions.

For Python we provide images for Python 3.9 to 3.12, for Node.js we have images for Node.js 18, 20 and 22, and for .NET we have images for .NET 6.0 and 8.0. These versioned images include the language version in the image name, for example pulumi/pulumi-python-3.12 or pulumi/pulumi-nodejs-22.

The Go image is not versioned, as the Go runtime natively supports multiple versions via its Go Toolchains feature. The go statement in your Pulumi project’s go.mod file determines the Go version used to compile your program.

Updating the Default Language Versions

In November 2024 the images without a version suffix, like pulumi/pulumi-python, and the pulumi/pulumi image, will be updated to use the latest versions for each of the language runtimes by default:

Language Runtime	Current Version	New Version
.NET	6.0	8.0
Go	1.21	1.23
Node.js	18	22
Python	3.9	3.13
Java	17	21

The default versions will be updated as new versions of the language runtimes are released, matching the versions supported by the Pulumi CLI. This will enable the unversioned pulumi/pulumi image to stay evergreen as new runtimes come into and out of support.

The pulumi-provider-build-environment image, which is useful for building Pulumi providers, will also be updated with the latest language runtimes, as well as upgrading GoReleaser from v1 to v2. See the upgrade instructions on how to migrate your configuration to v2.

If you require a specific version of a language runtime, you can use the versioned images. If you want to use the latest versions of the language runtimes, you can use the images without a version suffix.

Setting the Language Version in Pulumi Deployments

When developing Node.js and Python programs, it is common to use a tool like nvm or pyenv to manage the version of the runtime used in your development environment. These tools use a .node-version or .python-version file to specify the version of the runtime to use in the current directory.

Using the latest version of the pulumi/pulumi image, Pulumi Deployments now supports these files to set the version of the Node.js and Python runtimes used in the Deployment environment. For example, to use Node.js 22 in a Deployment, you can add a .node-version file to your project with the content 22. The Deployment will then use Node.js 22 to run your Pulumi program.

The pulumi/pulumi image ships with Node.js 18, 20 and 22 pre-installed, as well as Python 3.9, 3.10, 3.11 and 3.12. Only the latest patch release of these versions is pre-installed, and it is therefore recommended you only specify the major version in the .node-version and .python-version files. If you provide a more specific version that does not match any of the pre-installed versions, it will be downloaded and installed on demand for each Deployment run.

To support more flexibility for .NET versions, the default image now also ships both .NET 6.0 and 8.0, allowing you to specify the version of .NET used in a deployment in the TargetFramework property in your project’s .csproj or .fsproj file.

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net8.0</TargetFramework>
 ...

If you want to use one of the language specific images, or your own custom built image, you can set a custom executor image in the Deployment settings.

Additional Tools

We recently added native Poetry support to Pulumi, and all of our images that include Python now ship with Poetry pre-installed. Images that include Node.js now ship with pnpm pre-installed.

To use Poetry set the toolchain runtime option to poetry:

name: pulumi-and-poetry-are-best-friends
runtime:
 name: python
 options:
 toolchain: poetry

To use pnpm set the packagemanager runtime option to pnpm:

name: pulumi-and-pnpm-sitting-in-a-tree
runtime:
 name: nodejs
 options:
 packagemanager: pnpm

These options work everywhere you run Pulumi, be it by directly running the Pulumi CLI locally, in CI/CD pipelines using our docker images, in GitHub Actions using the Pulumi Action, or in Pulumi Deployments.

Conclusion

These updates ensure that you get the latest version of the language runtimes by default, and provide more flexibility for choosing a specific version of the language runtime in your Pulumi projects and Deployments when required. Pulumi Deployments now also ship with Poetry and pnpm pre-installed, making it easier to use these tools in your Pulumi projects.

Pulumi + Python: Bringing the Best of Modern Python to IaC

Julien Poissonnier — Wed, 03 Jul 2024 14:17:38 +0200

One of our most important goals at Pulumi is to bring the very best of software engineering tools and practice to your cloud infrastructure. Pulumi embraces existing popular programming languages as a way to tap into everything that these language ecosystems offer developers – rich programming models, familiar syntax, IDE productivity, package management and versioning, componentization and reuse, testing, and so much more.

Python in particular has been one of the most popular languages used across the Pulumi platform, and the fastest growing over the last 2 years. Over the last few months, we’ve worked on a set of improvements that allow Pulumi users to take advantage of the latest and greatest tooling and features from the Python ecosystem. The key new features include:

More Pythonic resource APIs: A new dictionary-based API design which embraces a simple and familiar Pythonic API design along with access to great type checking and tooling building on recent enhancements to TypedDict support in the Python programming language and tools.
Native support for Poetry: Built-in support for working with Poetry in place of pip, making it easy to integrate Pulumi into projects and repositories leveraging the popular Poetry package management toolchain for Python.
Type checker integration: New ability to run your favorite Python type checkers directly within the Pulumi deployment process.

Pulumi + Python

Python was one of the first languages we ever supported in Pulumi, and has grown rapidly for defining and building Infrastructure as Code across any cloud. This growth has accelerated over the last year, driven by a few different trends:

DevOps practitioners with existing Python scripting experience who can naturally extend that experience into their IaC development
AI and Data-focused organizations with deep Python focus broadly within their organization leaning on IaC development which leverages the same language and tools
Broad growth in the Python developer ecosystem

The result has been strong and steady growth of Python Pulumi usage. This has been especially pronounced among some of the largest and most advanced Pulumi users, who are pushing the boundaries on managing complexity at scale using the best of the Python ecosystem.

New Features for Pulumi Python Users

Native Support for Poetry

Pulumi has long had support to create and manage virtual environments using Python’s builtin package manager pip. With the latest release of Pulumi, we are excited to announce that we now support Poetry as well. Poetry is a popular Python dependency management tool that allows you to declare your dependencies in a simple and concise way and manage your virtual environment with ease.

When creating a new Pulumi project, the Pulumi CLI will now ask you if you want to use Poetry to manage your dependencies. If you choose to use Poetry, the Pulumi CLI will automatically create a new Poetry project for you and install the necessary dependencies. To opt-in to using Poetry for an existing Pulumi project, set the toolchain runtime option to poetry and run pulumi install.

name: python-and-poetry-are-best-friends
runtime:
 name: python
 options:
 toolchain: poetry

Built-in type checking

Pulumi Python SDKs include type hints compatible with type checkers such as MyPy and Pyright. In the latest release of Pulumi, you can ask Pulumi to run your typechecker of choice for you as part of Pulumi operations and fail if there are any type errors. This can help you catch type errors earlier and ensure that your Pulumi programs are type-safe.

Add the typechecker of your choice to your dependencies and set the typechecker runtime option in your project file to mypy or pyright to enable automatic type checking.

name: python-with-typechecking
runtime:
 name: python
 options:
 typechecker: pyright

To enable live type checking in Visual Studio Code set the typeCheckingMode setting of the Pylance extension to basic or higher.

"python.analysis.typeCheckingMode": "basic"

Extensions for other editors typically have this already enabled.

We have updated the NGINX on AWS ECS Fargate example to use builtin typechecking and Poetry to manage dependencies. Check it out to see how you can use these new features in your Pulumi projects.

Pythonic input types

Pulumi has always had a focus on making Infrastructure as Code feel like idiomatic code and the latest release of Pulumi makes it easier to work with input types in Python.

Pulumi supports two ways of specifying inputs for resources in Python. You can use strongly typed, but verbose, argument classes, or you can use dictionaries, which are more idiomatic, but lack type hints. Leveraging improvements to Python’s TypedDict types, we can offer the best of both worlds – dictionary inputs now have type hints, providing you with type safety and the flexibility and simplicity of dictionaries.

This really pays off with large nested data structures, such as those you might use when configuring Kubernetes resources. Consider this program that uses argument classes to configure a deployment specification:

from pulumi_kubernetes.apps.v1 import Deployment
from pulumi_kubernetes.apps.v1 import Deployment, DeploymentSpecArgs
from pulumi_kubernetes.meta.v1 import LabelSelectorArgs, ObjectMetaArgs
from pulumi_kubernetes.core.v1 import ContainerArgs, PodSpecArgs, PodTemplateSpecArgs

app_labels = {"app": "nginx"}
deployment = Deployment(
 "nginx",
 spec=DeploymentSpecArgs(
 selector=LabelSelectorArgs(match_labels=app_labels),
 replicas=1,
 template=PodTemplateSpecArgs(
 metadata=ObjectMetaArgs(labels=app_labels),
 spec=PodSpecArgs(containers=[ContainerArgs(name="nginx", image="nginx")]),
 ),
 ),
)

With type hinted dictionaries, we can write the following, which is much more concise and just as type safe!

from pulumi_kubernetes.apps.v1 import Deployment

app_labels = {"app": "nginx"}

deployment = Deployment(
 "nginx",
 spec={
 "selector": {"match_labels": app_labels},
 "replicas": 1,
 "template": {
 "metadata": {"labels": app_labels},
 "spec": {"containers": [{"name": "nginx", "image": "nginx"}]},
 },
 },
)

The new Pythonic input types are available in the latest release of the Pulumi SDKs for Kubernetes, AWS and GCP, with more provider SDKs to follow soon.

Due to a performance issue in MyPy, type checking of TypedDict-based inputs is currently disabled when using MyPy as a type checker. We are working on helping resolve this issue. In the meantime, we recommend using Pyright as a type checker to get the most complete type checking possible for Dict-based Pulumi Python programs.

Build infrastructure in Python

Write your cloud infrastructure in Python with Poetry, built-in type checking, and idiomatic input types. Deploy your first stack, and manage it in Pulumi Cloud.

Get started

Summary

We hope you enjoy using these new features and we look forward to hearing your feedback. If you have any questions or need help, please don’t hesitate to reach out to us on Slack or GitHub.

Run Pulumi with Any TypeScript Version

Julien Poissonnier — Tue, 16 Apr 2024 10:28:28 +0200

Pulumi allows you to use the best features of programming languages to build your infrastructure while ensuring compatibility with your current development environments. To this end Pulumi provides a seamless experience when authoring TypeScript programs, managing the compilation of your program for you. With the latest release of our Node.js SDK, we’ve made this even more flexible by making it easier than ever to choose the version of TypeScript you want to use.

Each new release of TypeScript comes with new features and improved type checking, as well as support for the latest JavaScript features. Using the latest version of TypeScript provides you with the maximum flexibility for creating types and gives you more confidence that your program will behave as expected.

Until now, Pulumi’s seamless experience was limited to using Pulumi’s builtin TypeScript version 3.8. If you wanted to use a more recent version, you had to introduce a build step to your project and let Pulumi run in plain Javascript mode. With the release of the Pulumi Node.js SDK 3.113.0 you can now use any version of TypeScript by adding it as a dependency to your project’s package.json file.

Pulumi supports all TypeScript versions from 3.8 and up, including TypeScript 5.4.

If you have an existing project, you can upgrade your project to the latest versions of TypeScript and Pulumi by running:

npm add typescript@^5.4.5 @pulumi/pulumi@^3.113.0

We have also updated our Pulumi templates to include the latest version of TypeScript. To create a new project, run:

pulumi new

Adding TypeScript as a dependency to your project is optional, as TypeScript and ts-node are optional peer dependencies of the Node.js SDK. This makes it easy to use a single version of TypeScript or ts-node within monorepos. To ensure backward compatibility, Pulumi ships with bundled versions of TypeScript 3.8 and ts-node 7, and falls back to these versions if they are not installed in your project’s node modules.

Example

Let’s show an example of how to use one of TypeScripts’s new features with Pulumi. TypeScript 4.1 introduced Template Literal Types, which allow you to build types using template literals. Imagine you wanted to enforce that names of S3 buckets are all lower case and always start with a given prefix. Of course you can check this at runtime, but with Template Literal Types this can be enforced during typechecking.

type prefix = `acme_corp`
type BucketName = Lowercase<`${prefix}_${string}`>;

We can create a custom Bucket subclass that expects a name matching our new BucketName type.

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

type prefix = `acme_corp`
type BucketName = Lowercase<`${prefix}_${string}`>;

class AcmeCorpBucket extends aws.s3.Bucket {
 constructor(name: BucketName, args?: aws.s3.BucketArgs, opts?: pulumi.CustomResourceOptions) {
 super(name, args, opts);
 }
}

const myBucketWrong = new AcmeCorpBucket("MyBucket");
// ❌ Fails typechecking with: Argument of type '"MyBucket"' is not assignable to parameter of type '`acme_corp_${Lowercase<string>}`'.ts(2345)

const myBucketWrongAgain = new AcmeCorpBucket("acme_corp_MyBucket");
// ❌ Fails typechecking with: Argument of type '"acme_corp_MyBucket"' is not assignable to parameter of type '`acme_corp_${Lowercase<string>}`'.ts(2345)

const myBucketCorrect = new AcmeCorpBucket("acme_corp_my_bucket");
// ✅ Passes typechecking

This example shows just one of Typescript’s many new features that have shipped since version 3.8, and now all are available for you to use in your Pulumi programs without jumping through hoops.

Conclusion

We recently shipped improved support for Node.js monorepos, and with the latest version of the Pulumi Node.js SDK, we further improved how Pulumi integrates into your development environment by letting you easily pick the version of TypeScript to use.

Using Pulumi Inside Node.js Monorepos

Julien Poissonnier — Tue, 26 Mar 2024 17:19:00 +0100

One of Pulumi’s core goals is to provide cloud engineers with access to the very best software engineering tooling available. Using traditional programming languages like Node.js, Python, Go, .NET and Java means the latest and greatest software engineering tools from each of these ecosystems is available to bring to bear on managing cloud infrastructure, natively integrated with your existing development environments.

In the Node.js ecosystem, we’ve seen an explosion of great tooling over the last couple of years around support for monorepos - larger repositories built out of many smaller projects, and sharing code and dependencies smartly across all the various projects. We’ve seen many of our Pulumi Node.js users adopting these tools and repo structures, including tools like Yarn Workspaces, pnpm, Turborepo, and especially Nx.

While it has always been possible to apply these tools to Pulumi Node.js projects in TypeScript or JavaScript just like any other Node.js project, we’ve recently made a number of enhancements and fixes to make sure that Pulumi works truly seamlessly with these tools.

In this post, we’ll show how you can build a seamless development workflow by integrating Pulumi code level abstractions, such as Component Resources, with a monorepo-based build system like Nx.

Component resources let us create reusable components that manage logical groupings of resources. With modern monorepo tooling, and our recent improvements to make Pulumi aware of monorepo setups, we can colocate these reusable components, Pulumi infrastructure programs, and application code all in one monorepo, and have Nx manage the build and deploy-time dependencies for us.

We will walk through an example project that deploys a website built with Astro to AWS S3. The complete code can be found at pulumi/examples/nx-monorepo.

Our example monorepo has the following structure:

website: A website built with Astro.
components/s3folder: A component resource that manages a S3 bucket and its access policies.
components/website-deploy: A component resource resource that manages files in a S3 bucket
infra: A Pulumi program that uses the s3folder and website-deploy component resources to deploy the generated website.

By using npm workspaces we can have multiple npm packages managed from a singular top-level package. Npm will take care of installing the dependencies for all our packages and enables packages within the monorepo to reference each other. In the package.json at the root of the monorepo we set up the workspaces matching our folder structure. Yarn workspaces work similarly and are fully supported by Pulumi.

// package.json
{
 ...
 "workspaces": [
 "components/*",
 "infra",
 "website"
 ]
}

TypeScript

Pulumi has builtin TypeScript support and compiles your code on the fly without manual build-step, however this is currently limited to TypeScript 3.8. We are working on providing more choice here, but in the mean time Nx makes it easy to add a build-step to compile code using any version of TypeScript. For this example we are using the latest and greatest, TypeScript 5.4.

As of v3.113.0 of the @pulumi/pulumi NPM package any version of TypeScript is supported natively. To select the version to use, add it as a dependency to your package.json.

Declaring Dependencies

If we were to manually build and deploy the code in our monorepo, we would have to run the following steps:

Run astro build to generate the HTML output that we want to deploy.
Run npm run build for s3folder and website-deploy.
Run npm run build for infra afterwards, since this imports s3folder and website-deploy.
Run pulumi up to deploy our website.

Instead of running these steps manually, we will leverage Nx’s task running mechanism, which can be made aware of the dependencies between the packages in the monorepo. This ensures we don’t accidentally forget a step. On top of that, Nx provides caching, so we also avoid re-running unnecessary tasks on subsequent runs.

Because we are using npm workspaces, Nx can understand the dependencies declared in the package.json for each of the packages in our monorepo. For example in infra/package.json we declare that we depend on s3folder, website and website-deploy. We also let Nx know that the deploy target in the infra package depends on the build step, and the HTML generation step of the website package:

// infra/package.json
{
 "name": "infra",
 "dependencies": {
 "@pulumi/pulumi": "latest",
 "s3folder": "*",
 "website-deploy": "*",
 "website": "*"
 },
 "scripts": {
 "build": "tsc",
 "deploy": "pulumi up --stack dev"
 },
 "nx": {
 "targets": {
 "deploy": {
 "cache": true,
 "dependsOn": [
 "build",
 "website:generate"
 ]
 }
 }
 }
}

In nx.json we let Nx know that each package’s build-step depends on its dependencies’ build-steps. With that Nx now knows that in order build infra, it first needs to build its dependencies.

// nx.json
{
 "extends": "nx/presets/npm.json",
 "$schema": "./node_modules/nx/schemas/nx-schema.json",
 "targetDefaults": {
 "build": {
 "cache": true,
 "dependsOn": [
 "^build"
 ]
 }
 }
}

The full dependency graph, as understood by Nx, can be visualized by running npx nx deploy infra --graph.

Walkthrough

Now that we have taught Nx all about the dependencies in our monorepo, we can run npx nx deploy infra and Nx will run all the required steps in the correct order, using parallelism where possible.

 ✔ 4/4 dependent project tasks succeeded [0 read from cache]
Hint: you can run the command with --verbose to see the full dependent project outputs
————————————————————————————————————————————————————————————————————————————————
> nx run infra:build
> infra@1.0.0 build
> tsc
> nx run infra:deploy
> infra@1.0.0 deploy
> pulumi up --stack dev
The stack 'dev' does not exist.
If you would like to create this stack now, please press <ENTER>, otherwise press ^C:
Created stack 'dev'
Previewing update (dev)
View in Browser (Ctrl+O): https://app.pulumi.com/julienp/nx-monorepo/dev/previews/fc7630fd-7dc4-4c7e-baa0-3d6e014fc90a
Type Name Plan
+ pulumi:pulumi:Stack nx-monorepo-dev create
+ ├─ pulumi:examples:WebsiteDeploy my-website create
+ │ └─ aws:s3:BucketObject index.html create
+ └─ pulumi:examples:S3Folder my-folder create
+ ├─ aws:s3:Bucket my-folder create
+ ├─ aws:s3:BucketPublicAccessBlock public-access-block create
+ └─ aws:s3:BucketPolicy bucketPolicy create
Outputs:
websiteUrl: output<string>
Resources:
+ 7 to create
Do you want to perform this update? yes
Updating (dev)
...
NX Successfully ran target deploy for project infra and 4 tasks it depends on (27s)

The output tells us that Nx found the 4 dependent tasks for the deploy task of the infra package and ran them successfully.

If we now run npx nx deploy infra again, we can see Nx’s caching mechanism in action. Nx notices that there are no code changes to the infra package, and that none of its dependencies have changed either, so it just replays the output from the previous run.

 ✔ 3/3 dependent project tasks succeeded [3 read from cache]
Hint: you can run the command with --verbose to see the full dependent project outputs
————————————————————————————————————————————————————————————————————————————————
>nx run infra:build [existing outputs match the cache, left as is]
> infra@1.0.0 build
> tsc
> nx run infra:deploy [existing outputs match the cache, left as is]
> infra@1.0.0 deploy
> pulumi up --stack dev
Previewing update (dev)
...
NX Successfully ran target deploy for project infra and 4 tasks it depends on (29ms)
Nx read the output from the cache instead of running the command for 5 out of 5 tasks.

Now let’s create a new page in our website by adding a markdown file in the src/pages folder.

echo "Hello, World!" > website/src/pages/hello.md

When we run npx nx deploy infra again, Nx notices that there is a change to the website and reruns the HTML generation step. Since one of the dependencies of infra has now changed, the stack is re-deployed.

 ✔ 2/2 dependent project tasks succeeded [2 read from cache]
Hint: you can run the command with --verbose to see the full dependent project outputs
————————————————————————————————————————————————————————————————————————————————
> nx run infra:build
> infra@1.0.0 build
> tsc
> nx run infra:deploy
> infra@1.0.0 deploy
> pulumi up --stack dev
Previewing update (dev)
View in Browser (Ctrl+O): https://app.pulumi.com/v-julien-pulumi-corp/nx-monorepo/dev/previews/8d9db825-77e1-4d1a-8f9b-8279481e7e40
Type Name Plan
pulumi:pulumi:Stack nx-monorepo-dev
└─ pulumi:examples:WebsiteDeploy my-website
+ └─ aws:s3:BucketObject hello/index.html create
Resources:
+ 1 to create
8 unchanged
Do you want to perform this update? yes
Updating (dev)
...
NX Successfully ran target deploy for project infra and 4 tasks it depends on (19s)
Nx read the output from the cache instead of running the command for 2 out of 5 tasks.

We can see that Nx used the cached results for 2 of our tasks, s3folder and website-deploy didn’t change, so Nx skips rebuilding them. Nx also ran the other 3 tasks to generate the website’s HTML, building the infra package and finally deploying the infra package.

Ship infrastructure from your monorepo

Colocate reusable Pulumi component resources, infrastructure programs, and application code in one monorepo, then build and deploy them together with Nx. Manage every stack in Pulumi Cloud.

Get started

Conclusion

In this post we’ve shown how we can combine Pulumi’s code level abstractions with a build system to create a seamless developer workflow. By using a monorepo we can colocate our reusable components with the Pulumi programs that use the components, as well as our application code. Tools like Nx allow us to intelligently manage the dependencies between the packages in the monorepo, ensuring we are always deploying the correct version of the code.

Pulumi provides you with access to the latest and greatest software engineering tools (like Nx), and allows you to bring them to bear on managing cloud infrastructure, natively integrated with your existing development environments.

Pulumi Blog: Julien Poissonnier

Introducing Bun as a Runtime for Pulumi

Why Bun?

Getting started

Converting existing Node.js projects

1. Update Pulumi.yaml

2. Update tsconfig.json

3. Switch to ESM

4. Update the Pulumi SDK

5. Install dependencies and deploy

Bun as runtime vs. Bun as package manager

Known limitations

Start using Bun with Pulumi

Resource hooks

Hooks in action

Another example: application health checks

Where can we go from here?

Pulumi + uv: Fast Python Package and Project Management

Why uv?

Using uv in Pulumi

Improving Pulumi’s Docker Images

Updating the Default Language Versions

Setting the Language Version in Pulumi Deployments

Additional Tools

Conclusion

Pulumi + Python: Bringing the Best of Modern Python to IaC

Pulumi + Python

New Features for Pulumi Python Users

Native Support for Poetry

Built-in type checking

Pythonic input types

Summary

Run Pulumi with Any TypeScript Version

Example

Conclusion

Using Pulumi Inside Node.js Monorepos

TypeScript

Declaring Dependencies

Walkthrough

Conclusion

1. Update `Pulumi.yaml`

2. Update `tsconfig.json`